Annotation of src/usr.bin/doas/doas.conf.5, Revision 1.27
1.27 ! tedu 1: .\" $OpenBSD: doas.conf.5,v 1.26 2016/06/11 17:17:10 tedu Exp $
1.1 tedu 2: .\"
3: .\"Copyright (c) 2015 Ted Unangst <tedu@openbsd.org>
4: .\"
5: .\"Permission to use, copy, modify, and distribute this software for any
6: .\"purpose with or without fee is hereby granted, provided that the above
7: .\"copyright notice and this permission notice appear in all copies.
8: .\"
9: .\"THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\"WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\"MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\"ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\"WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\"ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\"OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.24 tedu 16: .Dd $Mdocdate: June 11 2016 $
1.1 tedu 17: .Dt DOAS.CONF 5
18: .Os
19: .Sh NAME
20: .Nm doas.conf
21: .Nd doas configuration file
1.17 tedu 22: .Sh SYNOPSIS
23: .Nm /etc/doas.conf
1.1 tedu 24: .Sh DESCRIPTION
25: The
26: .Xr doas 1
27: utility executes commands as other users according to the rules
1.18 jmc 28: in the
29: .Nm
1.1 tedu 30: configuration file.
31: .Pp
32: The rules have the following format:
1.3 schwarze 33: .Bd -ragged -offset indent
34: .Ic permit Ns | Ns Ic deny
35: .Op Ar options
1.4 bentley 36: .Ar identity
1.3 schwarze 37: .Op Ic as Ar target
1.9 jmc 38: .Op Ic cmd Ar command Op Ic args ...
1.1 tedu 39: .Ed
40: .Pp
41: Rules consist of the following parts:
1.3 schwarze 42: .Bl -tag -width 11n
43: .It Ic permit Ns | Ns Ic deny
1.1 tedu 44: The action to be taken if this rule matches.
1.3 schwarze 45: .It Ar options
1.1 tedu 46: Options are:
1.3 schwarze 47: .Bl -tag -width keepenv
48: .It Ic nopass
1.1 tedu 49: The user is not required to enter a password.
1.3 schwarze 50: .It Ic keepenv
1.1 tedu 51: The user's environment is maintained.
1.5 benno 52: The default is to reset the environment, except for the variables
53: .Ev DISPLAY ,
54: .Ev HOME ,
55: .Ev LOGNAME ,
56: .Ev MAIL ,
57: .Ev PATH ,
58: .Ev TERM ,
59: .Ev USER
60: and
61: .Ev USERNAME .
1.27 ! tedu 62: .It Ic setenv { Oo Ar variable ... Oc Ic Oo Ar variable=value ... Oc Ic }
1.12 jmc 63: In addition to the variables mentioned above, keep the space-separated
64: specified variables.
1.27 ! tedu 65: Variables may also be removed with a leading - or set using the latter syntax.
! 66: If the first character of
! 67: .Ar value
! 68: is a
! 69: .Ql $
! 70: then the value to be set is taken from the existing environment
! 71: variable of the same name.
1.1 tedu 72: .El
1.3 schwarze 73: .It Ar identity
1.1 tedu 74: The username to match.
1.12 jmc 75: Groups may be specified by prepending a colon
76: .Pq Sq \&: .
1.1 tedu 77: Numeric IDs are also accepted.
1.3 schwarze 78: .It Ic as Ar target
1.1 tedu 79: The target user the running user is allowed to run the command as.
1.13 tedu 80: The default is all users.
1.3 schwarze 81: .It Ic cmd Ar command
1.1 tedu 82: The command the user is allowed or denied to run.
83: The default is all commands.
1.23 tedu 84: Be advised that it is best to specify absolute paths.
1.25 tedu 85: If a relative path is specified, only a restricted
1.16 tedu 86: .Ev PATH
87: will be searched.
1.9 jmc 88: .It Ic args ...
1.8 zhuk 89: Arguments to command.
1.26 tedu 90: The command arguments provided by the user need to match those specified.
1.25 tedu 91: The keyword
1.8 zhuk 92: .Ic args
1.25 tedu 93: alone means that command must be run without any arguments.
1.1 tedu 94: .El
95: .Pp
96: The last matching rule determines the action taken.
1.24 tedu 97: If no rule matches, the action is denied.
1.5 benno 98: .Pp
99: Comments can be put anywhere in the file using a hash mark
100: .Pq Sq # ,
101: and extend to the end of the current line.
1.10 zhuk 102: .Pp
103: The following quoting rules apply:
104: .Bl -dash
105: .It
106: The text between a pair of double quotes
107: .Pq Sq \&"
108: is taken as is.
109: .It
1.11 jmc 110: The backslash character
1.10 zhuk 111: .Pq Sq \e
1.11 jmc 112: escapes the next character, including new line characters, outside comments;
1.10 zhuk 113: as a result, comments may not be extended over multiple lines.
114: .It
1.11 jmc 115: If quotes or backslashes are used in a word,
1.23 tedu 116: it is not considered a keyword.
1.10 zhuk 117: .El
1.1 tedu 118: .Sh EXAMPLES
1.5 benno 119: The following example permits users in group wsrc to build ports,
1.14 zhuk 120: wheel to execute commands as any user while keeping the environment
1.5 benno 121: variables
1.27 ! tedu 122: .Ev PS1
! 123: and
! 124: .Ev SSH_AUTH_SOCK
! 125: and
! 126: unsetting
1.5 benno 127: .Ev ENV ,
1.15 reyk 128: permits tedu to run procmap as root without a password,
129: and additionally permits root to run unrestricted commands as itself.
1.1 tedu 130: .Bd -literal -offset indent
1.6 jmc 131: # Non-exhaustive list of variables needed to
1.5 benno 132: # build release(8) and ports(7)
1.27 ! tedu 133: permit nopass setenv { \e
1.5 benno 134: FTPMODE PKG_CACHE PKG_PATH SM_PATH SSH_AUTH_SOCK \e
135: DESTDIR DISTDIR FETCH_CMD FLAVOR GROUP MAKE MAKECONF \e
136: MULTI_PACKAGES NOMAN OKAY_FILES OWNER PKG_DBDIR \e
137: PKG_DESTDIR PKG_TMPDIR PORTSDIR RELEASEDIR SHARED_ONLY \e
138: SUBPACKAGE WRKOBJDIR SUDO_PORT_V1 } :wsrc
1.27 ! tedu 139: permit nopass setenv { -ENV PS1=$DOAS_PS1 SSH_AUTH_SOCK } :wheel
1.14 zhuk 140: permit nopass tedu as root cmd /usr/sbin/procmap
1.15 reyk 141: permit nopass keepenv root as root
1.1 tedu 142: .Ed
1.3 schwarze 143: .Sh SEE ALSO
144: .Xr doas 1
145: .Sh HISTORY
146: The
147: .Nm
148: configuration file first appeared in
149: .Ox 5.8 .
150: .Sh AUTHORS
151: .An Ted Unangst Aq Mt tedu@openbsd.org