1.\" $OpenBSD: doas.conf.5,v 1.31 2016/12/05 10:58:07 schwarze Exp $ 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. 16.Dd $Mdocdate: December 5 2016 $ 17.Dt DOAS.CONF 5 18.Os 19.Sh NAME 20.Nm doas.conf 21.Nd doas configuration file 22.Sh SYNOPSIS 23.Nm @DOAS_CONF@ 24.Sh DESCRIPTION 25The 26.Xr doas 1 27utility executes commands as other users according to the rules 28in the 29.Nm 30configuration file. 31.Pp 32The rules have the following format: 33.Bd -ragged -offset indent 34.Ic permit Ns | Ns Ic deny 35.Op Ar options 36.Ar identity 37.Op Ic as Ar target 38.Op Ic cmd Ar command Op Ic args No ... 39.Ed 40.Pp 41Rules consist of the following parts: 42.Bl -tag -width 11n 43.It Ic permit Ns | Ns Ic deny 44The action to be taken if this rule matches. 45.It Ar options 46Options are: 47.Bl -tag -width keepenv 48.It Ic nopass 49The user is not required to enter a password. 50.It Ic nolog 51Do not log successful command execution to 52.Xr syslogd. 53.It Ic persist 54After the user successfully authenticates, do not ask for a password 55again for some time. Works on OpenBSD only, persist is not available on Linux or FreeBSD. 56.It Ic keepenv 57The user's environment is maintained. 58The default is to reset the environment, except for the variables 59.Ev DISPLAY 60and 61.Ev TERM . 62 63Note: In order to be able to run most desktop (GUI) applications, the user needs to 64have the keepenv keyword specified. If keepenv is not specified then key elements, like 65the user's $HOME variable, will be reset and cause the GUI application to crash. 66Users who only need to run command line applications can usually get away without 67keepenv. When in doubt, try to avoid using keepenv as it is less secure to have 68environment variables passed to privileged users. 69 70Note: The target user's PATH variable can be set at compile time by adjusting the 71GLOBAL_PATH variable in doas's Makefile. By default, the target user's path will 72be set to "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:" 73.It Ic setenv { Oo Ar variable ... Oc Oo Ar variable=value ... Oc Ic } 74In addition to the variables mentioned above, keep the space-separated 75specified variables. 76Variables may also be removed with a leading 77.Sq - 78or set using the latter syntax. 79If the first character of 80.Ar value 81is a 82.Ql $ 83then the value to be set is taken from the existing environment 84variable of the same name. 85.El 86.It Ar identity 87The username to match. 88Groups may be specified by prepending a colon 89.Pq Sq \&: . 90Numeric IDs are also accepted. 91.It Ic as Ar target 92The target user the running user is allowed to run the command as. 93The default is all users. 94.It Ic cmd Ar command 95The command the user is allowed or denied to run. 96The default is all commands. 97Be advised that it is best to specify absolute paths. 98If a relative path is specified, only a restricted 99.Ev PATH 100will be searched. 101.It Ic args Op Ar argument ... 102Arguments to command. 103The command arguments provided by the user need to match those specified. 104The keyword 105.Ic args 106alone means that command must be run without any arguments. 107.El 108.Pp 109The last matching rule determines the action taken. 110If no rule matches, the action is denied. 111.Pp 112Comments can be put anywhere in the file using a hash mark 113.Pq Sq # , 114and extend to the end of the current line. 115.Pp 116The following quoting rules apply: 117.Bl -dash 118.It 119The text between a pair of double quotes 120.Pq Sq \&" 121is taken as is. 122.It 123The backslash character 124.Pq Sq \e 125escapes the next character, including new line characters, outside comments; 126as a result, comments may not be extended over multiple lines. 127.It 128If quotes or backslashes are used in a word, 129it is not considered a keyword. 130.El 131.Sh NOTES 132To make editing the doas.conf file safer, a convenience script called 133vidoas is included with the doas software. This script can be run as 134the root user (or via doas or sudo) and automatically checks the syntax of the doas.conf file 135before installing it on the system. 136 137Please take note that it is a bad idea to assign permission to users 138implicitly, even if blocking/denying exceptions are made. For instance, try 139to avoid using rules like 140.Bd -literal -offset indent 141permit susan as 142deny susan as root 143 144.Ed 145The above example uses two rules to permit Susan to switch to any user, except 146root. This is dangerous for two reasons. First, it means if new users, 147including ones with admin access, are added to the system later then 148Susan can use their accounts. It also means if the file is truncated or 149accessed while being updated the doas program may read the first rule 150before the second has been written, giving Susan access to everything, 151including the root account. The better approach to is explicity allow Susan 152to access only specific accounts she needs to use. 153 154Entries in the doas.conf file must end with a newline character to 155indicate where a rule ends. Most text editors will add a newline or 156end of line character for you, however not all tools do. Please make 157sure each rule in your doas.conf file ends with a newline (Enter) 158character. Otherwise syntax checks will fail with an error 159"syntax error at line..." 160 161.Sh EXAMPLES 162The following example permits users in group wsrc to build ports; 163wheel to execute commands as any user while keeping the environment 164variables 165.Ev PS1 166and 167.Ev SSH_AUTH_SOCK 168and 169unsetting 170.Ev ENV ; 171permits tedu to run procmap as root without a password; 172and additionally permits root to run unrestricted commands as itself. 173.Bd -literal -offset indent 174# Non-exhaustive list of variables needed to 175# build release(8) and ports(7) 176permit nopass setenv { \e 177 FTPMODE PKG_CACHE PKG_PATH SM_PATH SSH_AUTH_SOCK \e 178 DESTDIR DISTDIR FETCH_CMD FLAVOR GROUP MAKE MAKECONF \e 179 MULTI_PACKAGES NOMAN OKAY_FILES OWNER PKG_DBDIR \e 180 PKG_DESTDIR PKG_TMPDIR PORTSDIR RELEASEDIR SHARED_ONLY \e 181 SUBPACKAGE WRKOBJDIR SUDO_PORT_V1 } :wsrc 182permit setenv { -ENV PS1=$DOAS_PS1 SSH_AUTH_SOCK } :wheel 183permit nopass tedu as root cmd /usr/sbin/procmap 184permit nopass keepenv root as root 185.Ed 186.Sh SEE ALSO 187.Xr doas 1 188.Sh HISTORY 189The 190.Nm 191configuration file first appeared in 192.Ox 5.8 . 193.Sh AUTHORS 194.An Ted Unangst Aq Mt tedu@openbsd.org 195