mirror of
https://github.com/slicer69/doas
synced 2024-07-09 12:05:49 +00:00
7648f25667
- Use mv(1) to install doas.conf to avoid writing a configuration file while other processes might be reading it. - Define the DOAS_CONF path once in Makefile and pass that to the substitutions instead of recreating the full path independently in multiple files. - Add a separate rule for building the doas binary, instead of creating it in the "all" target. This avoids some unnecessary re-linking.
185 lines
6.2 KiB
Groff
185 lines
6.2 KiB
Groff
.\" $OpenBSD: doas.conf.5,v 1.31 2016/12/05 10:58:07 schwarze Exp $
|
|
.\"
|
|
.\"Copyright (c) 2015 Ted Unangst <tedu@openbsd.org>
|
|
.\"
|
|
.\"Permission to use, copy, modify, and distribute this software for any
|
|
.\"purpose with or without fee is hereby granted, provided that the above
|
|
.\"copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\"THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\"WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\"MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\"ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\"WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\"ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\"OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.Dd $Mdocdate: December 5 2016 $
|
|
.Dt DOAS.CONF 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm doas.conf
|
|
.Nd doas configuration file
|
|
.Sh SYNOPSIS
|
|
.Nm @DOAS_CONF@
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Xr doas 1
|
|
utility executes commands as other users according to the rules
|
|
in the
|
|
.Nm
|
|
configuration file.
|
|
.Pp
|
|
The rules have the following format:
|
|
.Bd -ragged -offset indent
|
|
.Ic permit Ns | Ns Ic deny
|
|
.Op Ar options
|
|
.Ar identity
|
|
.Op Ic as Ar target
|
|
.Op Ic cmd Ar command Op Ic args No ...
|
|
.Ed
|
|
.Pp
|
|
Rules consist of the following parts:
|
|
.Bl -tag -width 11n
|
|
.It Ic permit Ns | Ns Ic deny
|
|
The action to be taken if this rule matches.
|
|
.It Ar options
|
|
Options are:
|
|
.Bl -tag -width keepenv
|
|
.It Ic nopass
|
|
The user is not required to enter a password.
|
|
.It Ic persist
|
|
After the user successfully authenticates, do not ask for a password
|
|
again for some time. Works on OpenBSD only, persist is not available on Linux or FreeBSD.
|
|
.It Ic keepenv
|
|
The user's environment is maintained.
|
|
The default is to reset the environment, except for the variables
|
|
.Ev DISPLAY
|
|
and
|
|
.Ev TERM .
|
|
|
|
Note: In order to be able to run most desktop (GUI) applications, the user needs to
|
|
have the keepenv keyword specified. If keepenv is not specified then key elements, like
|
|
the user's $HOME variable, will be reset and cause the GUI application to crash.
|
|
Users who only need to run command line applications can usually get away without
|
|
keepenv. When in doubt, try to avoid using keepenv as it is less secure to have
|
|
environment variables passed to privileged users.
|
|
|
|
Note: The target user's PATH variable can be set at compile time by adjusting the
|
|
GLOBAL_PATH variable in doas's Makefile. By default, the target user's path will
|
|
be set to "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:"
|
|
.It Ic setenv { Oo Ar variable ... Oc Oo Ar variable=value ... Oc Ic }
|
|
In addition to the variables mentioned above, keep the space-separated
|
|
specified variables.
|
|
Variables may also be removed with a leading
|
|
.Sq -
|
|
or set using the latter syntax.
|
|
If the first character of
|
|
.Ar value
|
|
is a
|
|
.Ql $
|
|
then the value to be set is taken from the existing environment
|
|
variable of the same name.
|
|
.El
|
|
.It Ar identity
|
|
The username to match.
|
|
Groups may be specified by prepending a colon
|
|
.Pq Sq \&: .
|
|
Numeric IDs are also accepted.
|
|
.It Ic as Ar target
|
|
The target user the running user is allowed to run the command as.
|
|
The default is all users.
|
|
.It Ic cmd Ar command
|
|
The command the user is allowed or denied to run.
|
|
The default is all commands.
|
|
Be advised that it is best to specify absolute paths.
|
|
If a relative path is specified, only a restricted
|
|
.Ev PATH
|
|
will be searched.
|
|
.It Ic args Op Ar argument ...
|
|
Arguments to command.
|
|
The command arguments provided by the user need to match those specified.
|
|
The keyword
|
|
.Ic args
|
|
alone means that command must be run without any arguments.
|
|
.El
|
|
.Pp
|
|
The last matching rule determines the action taken.
|
|
If no rule matches, the action is denied.
|
|
.Pp
|
|
Comments can be put anywhere in the file using a hash mark
|
|
.Pq Sq # ,
|
|
and extend to the end of the current line.
|
|
.Pp
|
|
The following quoting rules apply:
|
|
.Bl -dash
|
|
.It
|
|
The text between a pair of double quotes
|
|
.Pq Sq \&"
|
|
is taken as is.
|
|
.It
|
|
The backslash character
|
|
.Pq Sq \e
|
|
escapes the next character, including new line characters, outside comments;
|
|
as a result, comments may not be extended over multiple lines.
|
|
.It
|
|
If quotes or backslashes are used in a word,
|
|
it is not considered a keyword.
|
|
.El
|
|
.Sh NOTES
|
|
To make editing the doas.conf file safer, a convenience script called
|
|
vidoas is included with the doas software. This script can be run as
|
|
a regular user and automatically checks the syntax of the doas.conf file
|
|
before installing it on the system.
|
|
|
|
Please take note that it is a bad idea to assign permission to users
|
|
implicitly, even if blocking/denying exceptions are made. For instance, try
|
|
to avoid using rules like
|
|
.Bd -literal -offset indent
|
|
permit susan as
|
|
deny susan as root
|
|
|
|
.Ed
|
|
The above example uses two rules to permit Susan to switch to any user, except
|
|
root. This is dangerous for two reasons. First, it means if new users,
|
|
including ones with admin access, are added to the system later then
|
|
Susan can use their accounts. It also means if the file is truncated or
|
|
accessed while being updated the doas program may read the first rule
|
|
before the second has been written, giving Susan access to everything,
|
|
including the root account. The better approach to is explicity allow Susan
|
|
to access only specific accounts she needs to use.
|
|
|
|
.Sh EXAMPLES
|
|
The following example permits users in group wsrc to build ports;
|
|
wheel to execute commands as any user while keeping the environment
|
|
variables
|
|
.Ev PS1
|
|
and
|
|
.Ev SSH_AUTH_SOCK
|
|
and
|
|
unsetting
|
|
.Ev ENV ;
|
|
permits tedu to run procmap as root without a password;
|
|
and additionally permits root to run unrestricted commands as itself.
|
|
.Bd -literal -offset indent
|
|
# Non-exhaustive list of variables needed to
|
|
# build release(8) and ports(7)
|
|
permit nopass setenv { \e
|
|
FTPMODE PKG_CACHE PKG_PATH SM_PATH SSH_AUTH_SOCK \e
|
|
DESTDIR DISTDIR FETCH_CMD FLAVOR GROUP MAKE MAKECONF \e
|
|
MULTI_PACKAGES NOMAN OKAY_FILES OWNER PKG_DBDIR \e
|
|
PKG_DESTDIR PKG_TMPDIR PORTSDIR RELEASEDIR SHARED_ONLY \e
|
|
SUBPACKAGE WRKOBJDIR SUDO_PORT_V1 } :wsrc
|
|
permit setenv { -ENV PS1=$DOAS_PS1 SSH_AUTH_SOCK } :wheel
|
|
permit nopass tedu as root cmd /usr/sbin/procmap
|
|
permit nopass keepenv root as root
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr doas 1
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
configuration file first appeared in
|
|
.Ox 5.8 .
|
|
.Sh AUTHORS
|
|
.An Ted Unangst Aq Mt tedu@openbsd.org
|