Annotation of src/usr.bin/doas/doas.conf.5, Revision 1.8
1.8 ! zhuk 1: .\" $OpenBSD: doas.conf.5,v 1.7 2015/07/20 20:18:45 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.7 tedu 16: .Dd $Mdocdate: July 20 2015 $
1.1 tedu 17: .Dt DOAS.CONF 5
18: .Os
19: .Sh NAME
20: .Nm doas.conf
21: .Nd doas configuration file
22: .Sh DESCRIPTION
23: The
24: .Xr doas 1
25: utility executes commands as other users according to the rules
26: in the
27: .Nm
28: configuration file.
29: .Pp
30: The rules have the following format:
1.3 schwarze 31: .Bd -ragged -offset indent
32: .Ic permit Ns | Ns Ic deny
33: .Op Ar options
1.4 bentley 34: .Ar identity
1.3 schwarze 35: .Op Ic as Ar target
1.8 ! zhuk 36: .Oo
! 37: .Ic cmd Ar command Op Ic args ...
! 38: .Oc
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.3 schwarze 62: .It Ic keepenv { Oo variable names Oc Ic }
1.5 benno 63: Reset the environment, but keep the space-separated specified variables.
1.1 tedu 64: .El
1.3 schwarze 65: .It Ar identity
1.1 tedu 66: The username to match.
67: Groups may be specified by prepending a colon (:).
68: Numeric IDs are also accepted.
1.3 schwarze 69: .It Ic as Ar target
1.1 tedu 70: The target user the running user is allowed to run the command as.
71: The default is root.
1.3 schwarze 72: .It Ic cmd Ar command
1.1 tedu 73: The command the user is allowed or denied to run.
74: The default is all commands.
75: Be advised that it's best to specify absolute paths.
1.8 ! zhuk 76: .It Ic args Op ...
! 77: Arguments to command.
! 78: If specified, the command arguments set provided by user and
! 79: the command arguments set in rule should be the same for successful
! 80: rule match.
! 81: Specifying
! 82: .Ic args
! 83: alone means that command should be run without any arguments.
1.1 tedu 84: .El
85: .Pp
86: The last matching rule determines the action taken.
1.5 benno 87: .Pp
88: The current line can be extended over multiple lines using a backslash
89: .Pq Sq \e .
90: Comments can be put anywhere in the file using a hash mark
91: .Pq Sq # ,
92: and extend to the end of the current line.
1.1 tedu 93: .Sh EXAMPLES
1.5 benno 94: The following example permits users in group wsrc to build ports,
95: wheel to execute commands as root while keeping the environment
96: variables
97: .Ev ENV ,
98: .Ev PS1 ,
99: and
100: .Ev SSH_AUTH_SOCK ,
1.1 tedu 101: and additionally permits tedu to run procmap as root without a password.
102: .Bd -literal -offset indent
1.6 jmc 103: # Non-exhaustive list of variables needed to
1.5 benno 104: # build release(8) and ports(7)
105: permit nopass keepenv { \e
106: FTPMODE PKG_CACHE PKG_PATH SM_PATH SSH_AUTH_SOCK \e
107: DESTDIR DISTDIR FETCH_CMD FLAVOR GROUP MAKE MAKECONF \e
108: MULTI_PACKAGES NOMAN OKAY_FILES OWNER PKG_DBDIR \e
109: PKG_DESTDIR PKG_TMPDIR PORTSDIR RELEASEDIR SHARED_ONLY \e
110: SUBPACKAGE WRKOBJDIR SUDO_PORT_V1 } :wsrc
111: permit nopass keepenv { ENV PS1 SSH_AUTH_SOCK } :wheel
1.1 tedu 112: permit nopass tedu cmd /usr/sbin/procmap
113: .Ed
1.3 schwarze 114: .Sh SEE ALSO
115: .Xr doas 1
116: .Sh HISTORY
117: The
118: .Nm
119: configuration file first appeared in
120: .Ox 5.8 .
121: .Sh AUTHORS
122: .An Ted Unangst Aq Mt tedu@openbsd.org