Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DOAS.CONF(5)		  FreeBSD File Formats Manual		  DOAS.CONF(5)

     doas.conf -- doas configuration file


     The doas(1) utility executes commands as other users according to the
     rules in the doas.conf configuration file.

     The rules have the	following format:

	   permit|deny [options] identity [as target] [cmd command [args ...]]

     Rules consist of the following parts:

     permit|deny  The action to	be taken if this rule matches.

     options	  Options are:

		  nopass   The user is not required to enter a password.

		  nolog	   Do not log successful command execution to syslogd.

		  persist  After the user successfully authenticates, do not
			   ask for a password again for	some time. Works on
			   OpenBSD only, persist is not	available on Linux or

		  keepenv  The user's environment is maintained.  The default
			   is to reset the environment,	except for the vari-
			   ables DISPLAY and TERM.

			   Note: In order to be	able to	run most desktop (GUI)
			   applications, the user needs	to have	the keepenv
			   keyword specified. If keepenv is not	specified then
			   key elements, like the user's $HOME variable, will
			   be reset and	cause the GUI application to crash.
			   Users who only need to run command line applica-
			   tions can usually get away without keepenv. When in
			   doubt, try to avoid using keepenv as	it is less se-
			   cure	to have	environment variables passed to	privi-
			   leged users.

			   Note: The target user's PATH	variable can be	set at
			   compile time	by adjusting the GLOBAL_PATH variable
			   in doas's Makefile. By default, the target user's
			   path	will be	set to "/usr/local/sbin:/usr/lo-

		  setenv { [variable ...] [variable=value ...] }
			   In addition to the variables	mentioned above, keep
			   the space-separated specified variables.  Variables
			   may also be removed with a leading `-' or set using
			   the latter syntax.  If the first character of value
			   is a	`$' then the value to be set is	taken from the
			   existing environment	variable of the	same name.

     identity	  The username to match.  Groups may be	specified by prepend-
		  ing a	colon (`:').  Numeric IDs are also accepted.

     as	target	  The target user the running user is allowed to run the com-
		  mand as.  The	default	is all users.  Please be aware that on
		  some systems multiple	usernames can resolve to the same UID.
		  For example, on FreeBSD it is	common to have both toor and
		  root resolve to UID 0. The doas utility will allow any user-
		  name that matches a shared UID to match when the -u flag is
		  invoked. This	means if you have the rule

			permit alice as	toor

		  in your doas.conf file, the command "doas -u root" can be
		  successfully run from	Alice's	account	in situations where
		  both root and	toor share the same UID. In short, doas	cares
		  about	the UID	behind the username, not the specific username
		  given	on the command line.

     cmd command  The command the user is allowed or denied to run.  The de-
		  fault	is all commands.  Be advised that it is	best to	spec-
		  ify absolute paths.  If a relative path is specified,	only a
		  restricted PATH will be searched.

     args [argument ...]
		  Arguments to command.	 The command arguments provided	by the
		  user need to match those specified.  The keyword args	alone
		  means	that command must be run without any arguments.

     The last matching rule determines the action taken.  If no	rule matches,
     the action	is denied.

     Comments can be put anywhere in the file using a hash mark	(`#'), and ex-
     tend to the end of	the current line.

     The following quoting rules apply:

     -	 The text between a pair of double quotes (`"')	is taken as is.

     -	 The backslash character (`\') escapes the next	character, including
	 new line characters, outside comments;	as a result, comments may not
	 be extended over multiple lines.

     -	 If quotes or backslashes are used in a	word, it is not	considered a

     To	make editing the doas.conf file	safer, a convenience script called vi-
     doas is included with the doas software. This script can be run as	the
     root user (or via doas or sudo) and automatically checks the syntax of
     the doas.conf file	before installing it on	the system.

     Please take note that it is a bad idea to assign permission to users im-
     plicitly, even if blocking/denying	exceptions are made. For instance, try
     to	avoid using rules like

	   permit susan	as
	   deny	susan as root

     The above example uses two	rules to permit	Susan to switch	to any user,
     except root. This is dangerous for	two reasons. First, it means if	new
     users, including ones with	admin access, are added	to the system later
     then Susan	can use	their accounts.	It also	means if the file is truncated
     or	accessed while being updated the doas program may read the first rule
     before the	second has been	written, giving	Susan access to	everything,
     including the root	account. The better approach to	is explicity allow Su-
     san to access only	specific accounts she needs to use.

     Entries in	the doas.conf file must	end with a newline character to	indi-
     cate where	a rule ends. Most text editors will add	a newline or end of
     line character for	you, however not all tools do. Please make sure	each
     rule in your doas.conf file ends with a newline (Enter) character.	Other-
     wise syntax checks	will fail with an error	"syntax	error at line..."

     The following example permits users in group wsrc to build	ports; wheel
     to	execute	commands as any	user while keeping the environment variables
     PS1 and SSH_AUTH_SOCK and unsetting ENV; permits tedu to run procmap as
     root without a password; and additionally permits root to run unre-
     stricted commands as itself.

	   # Non-exhaustive list of variables needed to
	   # build release(8) and ports(7)
	   permit nopass setenv	{ \
	   permit setenv { -ENV	PS1=$DOAS_PS1 SSH_AUTH_SOCK } :wheel
	   permit nopass tedu as root cmd /usr/sbin/procmap
	   permit nopass keepenv root as root


     The doas.conf configuration file first appeared in	OpenBSD	5.8.

     Ted Unangst <>

FreeBSD	13.0		       December	5, 2016			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help