Annotation of src/usr.bin/doas/doas.conf.5, Revision 1.46
1.46 ! kn 1: .\" $OpenBSD: doas.conf.5,v 1.45 2020/10/09 10:24:33 jmc 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.45 jmc 16: .Dd $Mdocdate: October 9 2020 $
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
1.18 jmc 26: in the
27: .Nm
1.1 tedu 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.31 schwarze 36: .Op Ic cmd Ar command Op Ic args No ...
1.1 tedu 37: .Ed
38: .Pp
39: Rules consist of the following parts:
1.3 schwarze 40: .Bl -tag -width 11n
41: .It Ic permit Ns | Ns Ic deny
1.1 tedu 42: The action to be taken if this rule matches.
1.3 schwarze 43: .It Ar options
1.1 tedu 44: Options are:
1.3 schwarze 45: .Bl -tag -width keepenv
46: .It Ic nopass
1.1 tedu 47: The user is not required to enter a password.
1.44 kn 48: .It Ic nolog
49: Do not log successful command execution to
50: .Xr syslogd 8 .
1.30 tedu 51: .It Ic persist
52: After the user successfully authenticates, do not ask for a password
53: again for some time.
1.3 schwarze 54: .It Ic keepenv
1.39 tedu 55: Environment variables other than those listed in
56: .Xr doas 1
57: are retained when creating the environment for the new process.
1.46 ! kn 58: .It Ic setenv Brq Oo Ar variable ... Oc Oo Ar variable Ns = Ns Ar value ... Oc
1.39 tedu 59: Keep or set the space-separated specified variables.
1.29 jmc 60: Variables may also be removed with a leading
61: .Sq -
62: or set using the latter syntax.
1.27 tedu 63: If the first character of
64: .Ar value
65: is a
66: .Ql $
67: then the value to be set is taken from the existing environment
1.34 tedu 68: variable of the indicated name.
1.39 tedu 69: This option is processed after the default environment has been created.
1.1 tedu 70: .El
1.3 schwarze 71: .It Ar identity
1.1 tedu 72: The username to match.
1.12 jmc 73: Groups may be specified by prepending a colon
74: .Pq Sq \&: .
1.1 tedu 75: Numeric IDs are also accepted.
1.3 schwarze 76: .It Ic as Ar target
1.1 tedu 77: The target user the running user is allowed to run the command as.
1.13 tedu 78: The default is all users.
1.3 schwarze 79: .It Ic cmd Ar command
1.1 tedu 80: The command the user is allowed or denied to run.
81: The default is all commands.
1.23 tedu 82: Be advised that it is best to specify absolute paths.
1.25 tedu 83: If a relative path is specified, only a restricted
1.16 tedu 84: .Ev PATH
85: will be searched.
1.31 schwarze 86: .It Ic args Op Ar argument ...
1.8 zhuk 87: Arguments to command.
1.26 tedu 88: The command arguments provided by the user need to match those specified.
1.25 tedu 89: The keyword
1.8 zhuk 90: .Ic args
1.25 tedu 91: alone means that command must be run without any arguments.
1.1 tedu 92: .El
93: .Pp
94: The last matching rule determines the action taken.
1.24 tedu 95: If no rule matches, the action is denied.
1.5 benno 96: .Pp
97: Comments can be put anywhere in the file using a hash mark
98: .Pq Sq # ,
99: and extend to the end of the current line.
1.10 zhuk 100: .Pp
101: The following quoting rules apply:
102: .Bl -dash
103: .It
104: The text between a pair of double quotes
105: .Pq Sq \&"
106: is taken as is.
107: .It
1.11 jmc 108: The backslash character
1.10 zhuk 109: .Pq Sq \e
1.11 jmc 110: escapes the next character, including new line characters, outside comments;
1.10 zhuk 111: as a result, comments may not be extended over multiple lines.
112: .It
1.11 jmc 113: If quotes or backslashes are used in a word,
1.23 tedu 114: it is not considered a keyword.
1.33 jmc 115: .El
116: .Sh FILES
1.42 schwarze 117: .Bl -tag -width /etc/examples/doas.conf -compact
1.33 jmc 118: .It Pa /etc/doas.conf
1.42 schwarze 119: .Xr doas 1
1.43 jmc 120: configuration file.
1.42 schwarze 121: .It Pa /etc/examples/doas.conf
1.43 jmc 122: Example configuration file.
1.10 zhuk 123: .El
1.1 tedu 124: .Sh EXAMPLES
1.32 tedu 125: The following example permits user aja to install packages
126: from a preferred mirror;
127: group wheel to execute commands as any user while keeping the environment
1.5 benno 128: variables
1.27 tedu 129: .Ev PS1
130: and
131: .Ev SSH_AUTH_SOCK
132: and
133: unsetting
1.29 jmc 134: .Ev ENV ;
135: permits tedu to run procmap as root without a password;
1.40 tedu 136: and additionally permits root to run unrestricted commands as itself
137: while retaining the original PATH.
1.1 tedu 138: .Bd -literal -offset indent
1.32 tedu 139: permit persist setenv { PKG_CACHE PKG_PATH } aja cmd pkg_add
1.28 tedu 140: permit setenv { -ENV PS1=$DOAS_PS1 SSH_AUTH_SOCK } :wheel
1.14 zhuk 141: permit nopass tedu as root cmd /usr/sbin/procmap
1.41 tedu 142: permit nopass keepenv setenv { PATH } root as root
1.1 tedu 143: .Ed
1.3 schwarze 144: .Sh SEE ALSO
1.45 jmc 145: .Xr doas 1 ,
1.44 kn 146: .Xr syslogd 8
1.3 schwarze 147: .Sh HISTORY
148: The
149: .Nm
150: configuration file first appeared in
151: .Ox 5.8 .
152: .Sh AUTHORS
153: .An Ted Unangst Aq Mt tedu@openbsd.org
![[BACK]](/icons/back.gif){kind=icon}
Return to doas.conf.5 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / doas