doas.conf.5

   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: @ATIME@ $
  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
  25 The
  26 .Xr doas 1
  27 utility executes commands as other users according to the rules
  28 in the
  29 .Nm
  30 configuration file.
  31 .Pp
  32 The rules have the following format:
  33 .Bd -ragged -offset indent
  34 .Ic permit Ns | Ns Ic deny
  35 .Op Ar options
  36 .Ar identity as target
  37 .Op Ic execute { Ar command line Oc Ic }
  38 .Ed
  39 .Pp
  40 Rules consist of the following parts:
  41 .Bl -tag -width 11n
  42 .It Ic permit Ns | Ns Ic deny
  43 The action to be taken if this rule matches.
  44 .It Ar options
  45 Options are:
  46 .Bl -tag -width keepenv
  47 .It Ic nopass
  48 The user is not required to enter a password.
  49 .It Ic nolog
  50 Do not log successful command execution to
  51 .Xr syslogd.
  52 .It Ic persist
  53 After the user successfully authenticates, do not ask for a password
  54 again for some time. Works on Linux, FreeBSD and OpenBSD only.
  55 .It Ic inheritenv
  56 The user's environment is maintained.
  57 The default is to reset the environment, except for the variables
  58 .Ev DISPLAY
  59 and
  60 .Ev TERM .
  61
  62 Note: In order to be able to run most desktop (GUI) applications, the user needs to
  63 have the inheritenv keyword specified. If inheritenv is not specified then key elements, like
  64 the user's $HOME variable, will be reset and cause the GUI application to crash.
  65 Users who only need to run command line applications can usually get away without
  66 inheritenv. When in doubt, try to avoid using inheritenv as it is less secure to have
  67 environment variables passed to privileged users.
  68
  69 Note: The target user's PATH variable can be set at compile time by adjusting the
  70 GLOBAL_PATH variable in doas's Makefile. By default, the target user's path will
  71 be set to "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:"
  72 .It Ic setenv { Oo Ar variable=value ... Oc Ic }
  73 In addition to the variables mentioned above, keep the space-separated
  74 specified variables.
  75 .It Ic keepenv { Oo Ar variable ... Oc Ic }
  76 Keeps the variables in environ.
  77 .It Ic unsetenv { Oo Ar variable ... Oc Ic }
  78 Remove the variables from environ.
  79 .El
  80 .It Ar identity
  81 It identitificates the user this rule can be applied by. User can be
  82 identitificated by its username (or uid), or groupname (or gid), or all together:
  83
  84 .Bl -tag -width keepenv
  85 .It Ar uid
  86 .It Ar 'username'
  87 The user with specified uid or username can apply this rule.
  88 The user do not have to belong any special group.
  89
  90 .It Ic from Ar gid
  91 .It Ic from Ar 'groupname'
  92 Any user from the group with specified gid or groupname can apply this rule.
  93
  94 .It Ar uid Ic from Ar gid
  95 .It Ar 'username' Ic from Ar gid
  96 .It Ar uid Ic from Ar 'groupname'
  97 The user with specified uid or username and belonging to specified group with gid or groupname
  98 can apply this rule.
  99 .El
 100
 101 .It Ic as Ar target
 102 The target user the running user is allowed to run the command as.
 103 The default is all users.
 104 .It Ic execute { Ar [ command-list ] [argument1-list] ... Ic }
 105 The command(s) the user is allowed or denied to run.
 106 The default is all commands.
 107 Be advised that it is best to specify absolute paths.
 108 If a relative path is specified, only a restricted
 109 .Ev PATH
 110 will be searched.
 111
 112 Arguments lists are arguments to command.
 113 The command arguments provided by the user need to match those specified.
 114
 115 Also, instead of any of the lists, the ellepsis
 116 .Pq Sq \...
 117 can be specified, which means that anything can be inthere.
 118
 119 The
 120 .Ar list
 121 is either just
 122 .Ic "string"
 123 or
 124 .Ic [ "string", "list" ].
 125 .El
 126 .Pp
 127 The last matching rule determines the action taken.
 128 If no rule matches, the action is denied.
 129 .Pp
 130 Comments can be put anywhere in the file using a hash mark
 131 .Pq Sq # ,
 132 and extend to the end of the current line.
 133 .Pp
 134 The following quoting rules apply:
 135 .Bl -dash
 136 .It
 137 The text between a pair of double quotes
 138 .Pq Sq \&"
 139 is taken as is.
 140 .It
 141 The backslash character
 142 .Pq Sq \e
 143 escapes the next character, including new line characters, outside comments;
 144 as a result, comments may not be extended over multiple lines.
 145 .It
 146 If quotes or backslashes are used in a word,
 147 it is not considered a keyword.
 148 .El
 149 .Sh NOTES
 150
 151 Usernames and groupnames must match
 152 .Ar [a-z_][a-z0-9_\-]{0,30}[a-z0-9_\-$\]?
 153 pattern and must be enclosed in single
 154 .Pq Sq \&'
 155 quotes.
 156
 157 To make editing the doas.conf file safer, a convenience script called
 158 vidoas is included with the doas software. This script can be run as
 159 the root user (or via doas or sudo) and automatically checks the syntax of the doas.conf file
 160 before installing it on the system.
 161
 162 Please take note that it is a bad idea to assign permission to users
 163 implicitly, even if blocking/denying exceptions are made.
 164
 165 .Sh EXAMPLES
 166 The following example permits users in group wsrc to build ports;
 167 wheel to execute commands as any user while keeping the environment
 168 variables
 169 .Ev PS1
 170 and
 171 .Ev SSH_AUTH_SOCK
 172 and
 173 unsetting
 174 .Ev ENV ;
 175 permits tedu to run procmap as root without a password;
 176 and additionally permits root to run unrestricted commands as itself.
 177 .Bd -literal -offset indent
 178 # Non-exhaustive list of variables needed to
 179 # build release(8) and ports(7)
 180 permit nopass keepenv { \e
 181         "FTPMODE", "PKG_CACHE", "PKG_PATH", "SM_PATH", "SSH_AUTH_SOCK", \e
 182         "DESTDIR", "DISTDIR", "FETCH_CMD", "FLAVOR", "GROUP", "MAKE", \e
 183         "MAKECONF", "MULTI_PACKAGES", "NOMAN", "OKAY_FILES", "OWNER", \e
 184         "PKG_DBDIR", "PKG_DESTDIR", "PKG_TMPDIR", "PORTSDIR", "RELEASEDIR", \e
 185         "SHARED_ONLY", "SUBPACKAGE", "WRKOBJDIR", "SUDO_PORT_V1" } from 'wsrc'
 186 permit unsetenv { "ENV" } keepenv { "PS1=$DOAS_PS1", "SSH_AUTH_SOCK" } from 'wheel'
 187 permit nopass 'tedu' as 'root' execute { "/usr/sbin/procmap" ... }
 188 permit nopass inheritenv 'root' as 'root'
 189
 190 .Ed
 191 Let us clearify the meaning and usage of string lists:
 192 .Bd -literal -offset indent
 193 permit 'serge' as 'michael' execute { [ "/usr/bin/ls", "/usr/bin/cat" ] }
 194 .Ed
 195 Following this rule, Serge can execute as Michael two programs: /usr/bin/ls and /usr/bin/cat. This rule actually equal to rule below:
 196 .Bd -literal -offset indent
 197 permit 'serge' as 'michael' execute { "/usr/bin/ls" }
 198 permit 'serge' as 'michael' execute { "/usr/bin/cat" }
 199 .Ed
 200
 201 Keep in mind, that rules
 202 .Bd -literal -offset indent
 203 permit 'serge' as 'michael' execute { "/usr/bin/ls" }
 204 .Ed
 205 and
 206 .Bd -literal -offset indent
 207 permit 'serge' as 'michael' execute { [ "/usr/bin/ls" ] }
 208 .Ed
 209 are
 210 .Ic absolutely equal .
 211
 212 .Sh SEE ALSO
 213 .Xr doas 1
 214 .Sh HISTORY
 215 The
 216 .Nm
 217 configuration file first appeared in
 218 .Ox 5.8 .
 219 .Sh AUTHORS
 220 .An Sergey Sushilin Aq Mt sergeysushilin@protonmail.com
 221 .An Ted Unangst Aq Mt tedu@openbsd.org