diff --git a/doc/sudo.mdoc.in b/doc/sudo.mdoc.in new file mode 100644 index 000000000..14ddbaaaa --- /dev/null +++ b/doc/sudo.mdoc.in @@ -0,0 +1,1211 @@ +.\" +.\" Copyright (c) 1994-1996, 1998-2005, 2007-2012 +.\" Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.Dd July 10, 2012 +.Dt SUDO 8 +.Os +.Sh NAME +.Nm sudo , +.Nm sudoedit +.Nd execute a command as another user +.Sh SYNOPSIS +.Nm sudo +.Fl h No | Fl K No | Fl k No | Fl V +.Nm sudo +.Fl v +.Op Fl AknS +.Bk -words +.Op Fl a Ar auth_type +.Ek +.Bk -words +.Op Fl g Ar group name No | Ar #gid +.Ek +.Bk -words +.Op Fl p Ar prompt +.Ek +.Bk -words +.Op Fl u Ar user name No | Ar #uid +.Ek +.Nm sudo +.Fl l Ns Op Ar l +.Op Fl AknS +.Bk -words +.Op Fl a Ar auth_type +.Ek +.Bk -words +.Op Fl g Ar group name No | Ar #gid +.Ek +.Bk -words +.Op Fl p Ar prompt +.Ek +.Bk -words +.Op Fl U Ar user name +.Ek +.Bk -words +.Op Fl u Ar user name No | Ar #uid +.Ek +.Op Ar command +.Nm sudo +.Op Fl AbEHnPS +.Bk -words +.Op Fl a Ar auth_type +.Ek +.Bk -words +.Op Fl C Ar fd +.Ek +.Bk -words +.Op Fl c Ar class No | Ar - +.Ek +.Bk -words +.Op Fl g Ar group name No | Ar #gid +.Ek +.Bk -words +.Op Fl p Ar prompt +.Ek +.Bk -words +.Op Fl r Ar role +.Ek +.Bk -words +.Op Fl t Ar type +.Ek +.Bk -words +.Op Fl u Ar user name No | Ar #uid +.Ek +.Bk -words +.Op Sy VAR Ns = Ns Ar value +.Ek +.Bk -words +.Fl i No | Fl s +.Ek +.Op Ar command +.Nm sudoedit +.Op Fl AnS +.Bk -words +.Op Fl a Ar auth_type +.Ek +.Bk -words +.Op Fl C Ar fd +.Ek +.Bk -words +.Op Fl c Ar class No | Ar - +.Ek +.Bk -words +.Op Fl g Ar group name No | Ar #gid +.Ek +.Bk -words +.Op Fl p Ar prompt +.Ek +.Bk -words +.Op Fl u Ar user name No | Ar #uid +.Ek +.Bk -words +file ... +.Ek +.Sh DESCRIPTION +.Nm sudo +allows a permitted user to execute a +.Ar command +as the superuser or another user, as specified by the security +policy. +The real and effective uid and gid are set to match those of the +target user, as specified in the password database, and the group +vector is initialized based on the group database (unless the +.Fl P +option was specified). +.Pp +.Nm sudo +supports a plugin architecture for security policies and input/output +logging. +Third parties can develop and distribute their own policy and I/O +logging modules to work seamlessly with the +.Nm sudo +front end. +The default security policy is +.Em sudoers , +which is configured via the file +.Pa @sysconfdir@/sudoers , +or via LDAP. +See the +.Sx PLUGINS +section for more information. +.Pp +The security policy determines what privileges, if any, a user has +to run +.Nm sudo . +The policy may require that users authenticate themselves with a +password or another authentication mechanism. +If authentication is required, +.Nm sudo +will exit if the user's password is not entered within a configurable +time limit. +This limit is policy-specific; the default password prompt timeout +for the +.Em sudoers +security policy is +.Li @password_timeout@ +minutes. +.Pp +Security policies may support credential caching to allow the user +to run +.Nm sudo +again for a period of time without requiring authentication. +The +.Em sudoers +policy caches credentials for +.Li @timeout@ +minutes, unless overridden in +.Xr sudoers 5 . +By running +.Nm sudo +with the +.Fl v +option, a user can update the cached credentials without running a +.Ar command . +.Pp +When invoked as +.Nm sudoedit , +the +.Fl e +option (described below), is implied. +.Pp +Security policies may log successful and failed attempts to use +.Nm sudo . +If an I/O plugin is configured, the running command's input and +output may be logged as well. +.Sh OPTIONS +.Nm sudo +accepts the following command line options: +.Bl -tag -width Fl +.It Fl A +Normally, if +.Nm sudo +requires a password, it will read it from the user's terminal. +If the +.Fl A No ( Em askpass Ns No ) +option is specified, a (possibly graphical) helper program is +executed to read the user's password and output the password to the +standard output. +If the +.Ev SUDO_ASKPASS +environment variable is set, it specifies the path to the helper +program. +Otherwise, if +.Pa @sysconfdir@/sudo.conf +contains a line specifying the askpass program, that value will be +used. +For example: +.Bd -literal -offset 4 + # Path to askpass helper program + Path askpass /usr/X11R6/bin/ssh-askpass +.Ed +.Pp +If no askpass program is available, +.Nm sudo +will exit with an error. +.It Fl a Ar type +The +.Fl a No ( Em "authentication type" Ns No ) +option causes +.Nm sudo +to use the specified authentication type when validating the user, +as allowed by +.Pa /etc/login.conf . +The system administrator may specify a list of sudo-specific +authentication methods by adding an +.Dq auth-sudo +entry in +.Pa /etc/login.conf . +This option is only available on systems that support BSD authentication. +.It Fl b +The +.Fl b No ( Em background Ns No ) +option tells +.Nm sudo +to run the given command in the background. +Note that if you use the +.Fl b +option you cannot use shell job control to manipulate the process. +Most interactive commands will fail to work properly in background +mode. +.It Fl C Ar fd +Normally, +.Nm sudo +will close all open file descriptors other than standard input, +standard output and standard error. +The +.Fl C No ( Em close from Ns No ) +option allows the user to specify a starting point above the standard +error (file descriptor three). +Values less than three are not permitted. +The security policy may restrict the user's ability to use the +.Fl C +option. +The +.Em sudoers +policy only permits use of the +.Fl C +option when the administrator has enabled the +.Em closefrom_override +option. +.It Fl c Ar class +The +.Fl c No ( Em class Ns No ) +option causes +.Nm sudo +to run the specified command with resources limited by the specified +login class. +The +.Em class +argument can be either a class name as defined in +.Pa /etc/login.conf , +or a single +.Ql \- +character. +Specifying a +.Ar class +of +.Li - +indicates that the command should be run restricted by the default +login capabilities for the user the command is run as. +If the +.Ar class +argument specifies an existing user class, the command must be run +as root, or the +.Nm sudo +command must be run from a shell that is already root. +This option is only available on systems with BSD login classes. +.It Fl E +The +.Fl E No ( Em preserve environment Ns No ) +option indicates to the security policy that the user wishes to +preserve their existing environment variables. +The security policy may return an error if the +.Fl E +option is specified and the user does not have permission to preserve +the environment. +.It Fl e +The +.Fl e No ( Em edit Ns No ) +option indicates that, instead of running a command, the user wishes +to edit one or more files. +In lieu of a command, the string "sudoedit" is used when consulting +the security policy. +If the user is authorized by the policy, the following steps are +taken: +.Bl -enum -offset 4 +.It +Temporary copies are made of the files to be edited with the owner +set to the invoking user. +.It +The editor specified by the policy is run to edit the temporary +files. +The +.Em sudoers +policy uses the +.Ev SUDO_EDITOR , +.Ev VISUAL +and +.Ev EDITOR +environment variables (in that order). +If none of +.Ev SUDO_EDITOR , +.Ev VISUAL +or +.Ev EDITOR +are set, the first program listed in the +.Em editor +.Xr sudoers 5 +option is used. +.It +If they have been modified, the temporary files are copied back to +their original location and the temporary versions are removed. +.El +.Pp +If the specified file does not exist, it will be created. +Note that unlike most commands run by +.Em sudo , +the editor is run with the invoking user's environment unmodified. +If, for some reason, +.Nm sudo +is unable to update a file with its edited version, the user will +receive a warning and the edited copy will remain in a temporary +file. +.It Fl g Ar group +Normally, +.Nm sudo +runs a command with the primary group set to the one specified by +the password database for the user the command is being run as (by +default, root). +The +.Fl g No ( Em group Ns No ) +option causes +.Nm sudo +to run the command with the primary group set to +.Ar group +instead. +To specify a +.Em gid +instead of a +.Em "group name" , +use +.Em #gid . +When running commands as a +.Em gid , +many shells require that the +.Ql # +be escaped with a backslash +.Pq Ql \e . +If no +.Fl u +option is specified, the command will be run as the invoking user +(not root). +In either case, the primary group will be set to +.Em group . +.It Fl H +The +.Fl H No ( Em HOME Ns No ) +option requests that the security policy set the +.Ev HOME +environment variable to the home directory of the target user (root +by default) as specified by the password database. +Depending on the policy, this may be the default behavior. +.It Fl h +The +.Fl h No ( Em help Ns No ) +option causes +.Nm sudo +to print a short help message to the standard output and exit. +.It Fl i Op Ar command +The +.Fl i No ( Em simulate initial login Ns No ) +option runs the shell specified by the password database entry of +the target user as a login shell. +This means that login-specific resource files such as +.Pa .profile +or +.Pa .login +will be read by the shell. +If a command is specified, it is passed to the shell for execution +via the shell's +.Fl c +option. +If no command is specified, an interactive shell is executed. +.Nm sudo +attempts to change to that user's home directory before running the +shell. +The security policy shall initialize the environment to a minimal +set of variables, similar to what is present when a user logs in. +The +.Em Command Environment +section in the +.Xr sudoers 5 +manual documents how the +.Fl i +option affects the environment in which a command is run when the +.Em sudoers +policy is in use. +.It Fl K +The +.Fl K No ( sure Em kill Ns No ) +option is like +.Fl k +except that it removes the user's cached credentials entirely and +may not be used in conjunction with a command or other option. +This option does not require a password. +Not all security policies support credential caching. +.It Fl k Op Ar command +When used alone, the +.Fl k No ( Em kill Ns No ) +option to +.Nm sudo +invalidates the user's cached credentials. +The next time +.Nm sudo +is run a password will be required. +This option does not require a password and was added to allow a +user to revoke +.Nm sudo +permissions from a +.Pa .logout +file. +Not all security policies support credential caching. +.Pp +When used in conjunction with a command or an option that may require +a password, the +.Fl k +option will cause +.Nm sudo +to ignore the user's cached credentials. +As a result, +.Nm sudo +will prompt for a password (if one is required by the security +policy) and will not update the user's cached credentials. +.It Fl l Ns Oo Sy l Oc Op Ar command +If no +.Ar command +is specified, the +.Fl l No ( Em list Ns No ) +option will list the allowed (and forbidden) commands for the +invoking user (or the user specified by the +.Fl U +option) on the current host. +If a +.Ar command +is specified and is permitted by the security policy, the fully-qualified +path to the command is displayed along with any command line +arguments. +If +.Ar command +is specified but not allowed, +.Nm sudo +will exit with a status value of 1. +If the +.Fl l +option is specified with an +.Ar l +argument +.Pq i.e.\& Fl ll , +or if +.Fl l +is specified multiple times, a longer list format is used. +.It Fl n +The +.Fl n No ( Em non-interactive Ns No ) +option prevents +.Nm sudo +from prompting the user for a password. +If a password is required for the command to run, +.Nm sudo +will display an error message and exit. +.It Fl P +The +.Fl P No ( Em preserve group vector Ns No ) +option causes +.Nm sudo +to preserve the invoking user's group vector unaltered. +By default, the +.Em sudoers +policy will initialize the group vector to the list of groups the +target user is in. +The real and effective group IDs, however, are still set to match +the target user. +.It Fl p Ar prompt +The +.Fl p No ( Em prompt Ns No ) +option allows you to override the default password prompt and use +a custom one. +The following percent +.Pq Ql % +escapes are supported by the +.Em sudoers +policy: +.Bl -tag -width 2n +.It Li %H +expanded to the host name including the domain name (on if the +machine's host name is fully qualified or the +.Em fqdn +option is set in +.Xr sudoers 5 ) +.It Li %h +expanded to the local host name without the domain name +.It Li %p +expanded to the name of the user whose password is being requested +(respects the +.Em rootpw , +.Em targetpw , +and +.Em runaspw +flags in +.Xr sudoers 5 ) +.It Li %U +expanded to the login name of the user the command will be run as +(defaults to root unless the +.Fl u +option is also specified) +.It Li %u +expanded to the invoking user's login name +.It Li %% +two consecutive +.Li % +characters are collapsed into a single +.Li % +character +.El +.Pp +The prompt specified by the +.Fl p +option will override the system password prompt on systems that +support PAM unless the +.Em passprompt_override +flag is disabled in +.Em sudoers . +.It Fl r Ar role +The +.Fl r No ( Em role Ns No ) +option causes the new (SELinux) security context to have the role +specified by +.Ar role . +.It Fl S +The +.Fl S ( Em stdin Ns No ) +option causes +.Nm sudo +to read the password from the standard input instead of the terminal +device. +The password must be followed by a newline character. +.It Fl s Op Ar command +The +.Fl s ( Em shell Ns No ) +option runs the shell specified by the +.Ev SHELL +environment variable if it is set or the shell as specified in the +password database. +If a command is specified, it is passed to the shell for execution +via the shell's +.Fl c +option. +If no command is specified, an interactive shell is executed. +.It Fl t Ar type +The +.Fl t ( Em type Ns No ) +option causes the new (SELinux) security context to have the type +specified by +.Ar type . +If no type is specified, the default type is derived from the +specified role. +.It Fl U Ar user +The +.Fl U ( Em other user Ns No ) +option is used in conjunction with the +.Fl l +option to specify the user whose privileges should be listed. +The security policy may restrict listing other users' privileges. +The +.Em sudoers +policy only allows root or a user with the +.Li ALL +privilege on the current host to use this option. +.It Fl u Ar user +The +.Fl u ( Em user Ns No ) +option causes +.Nm sudo +to run the specified command as a user other than +.Em root . +To specify a +.Em uid +instead of a +.Em user name , +.Em #uid . +When running commands as a +.Em uid , +many shells require that the +.Ql # +be escaped with a backslash +.Pq Ql \e . +Security policies may restrict +.Em uid No Ns s +to those listed in the password database. +The +.Em sudoers +policy allows +.Em uid No Ns s +that are not in the password database as long as the +.Em targetpw +option is not set. +Other security policies may not support this. +.It Fl V +The +.Fl V ( Em version Ns No ) +option causes +.Nm sudo +to print its version string and the version string of the security +policy plugin and any I/O plugins. +If the invoking user is already root the +.Fl V +option will display the arguments passed to configure when +.Nm sudo +was built and plugins may display more verbose information such as +default options. +.It Fl v +When given the +.Fl v ( Em validate Ns No ) +option, +.Nm sudo +will update the user's cached credentials, authenticating the user's +password if necessary. +For the +.Em sudoers +plugin, this extends the +.Nm sudo +timeout for another +.Li @timeout@ +minutes (or whatever the timeout is set to by the security policy) +but does not run a command. +Not all security policies support cached credentials. +.It Fl - +The +.Fl - +option indicates that +.Nm sudo +should stop processing command line arguments. +.El +.Pp +Environment variables to be set for the command may also be passed +on the command line in the form of +.Sy VAR No Ns = Ns Em value , +e.g.\& +.Sy LD_LIBRARY_PATH No Ns = Ns Em /usr/local/pkg/lib . +Variables passed on the command line are subject to the same +restrictions as normal environment variables with one important +exception. +If the +.Em setenv +option is set in +.Em sudoers , +the command to be run has the +.Li SETENV +tag set or the command matched is +.Li ALL , +the user may set variables that would otherwise be forbidden. +See +.Xr sudoers 5 +for more information. +.Sh PLUGINS +Plugins are dynamically loaded based on the contents of the +.Pa @sysconfdir@/sudo.conf +file. +If no +.Pa @sysconfdir@/sudo.conf +file is present, or it contains no +.Li Plugin +lines, +.Nm sudo +will use the traditional +.Em sudoers +security policy and I/O logging, which corresponds to the following +.Pa @sysconfdir@/sudo.conf +file. +.Bd -literal +# +# Default @sysconfdir@/sudo.conf file +# +# Format: +# Plugin plugin_name plugin_path plugin_options ... +# Path askpass /path/to/askpass +# Path noexec /path/to/sudo_noexec.so +# Debug sudo /var/log/sudo_debug all@warn +# Set disable_coredump true +# +# The plugin_path is relative to @prefix@/libexec unless +# fully qualified. +# The plugin_name corresponds to a global symbol in the plugin +# that contains the plugin interface structure. +# The plugin_options are optional. +# +Plugin policy_plugin sudoers.so +Plugin io_plugin sudoers.so +.Ed +.Pp +A +.Li Plugin +line consists of the +.Li Plugin +keyword, followed by the +.Em symbol_name +and the +.Em path +to the shared object containing the plugin. +The +.Em symbol_name +is the name of the +.Li struct policy_plugin +or +.Li struct io_plugin +in the plugin shared object. +The +.Em path +may be fully qualified or relative. +If not fully qualified it is relative to the +.Pa @prefix@/libexec +directory. +Any additional parameters after the +.Em path +are passed as arguments to the plugin's +.Em open +function. +Lines that don't begin with +.Li Plugin , +.Li Path , +.Li Debug , +or +.Li Set +are silently ignored. +.Pp +For more information, see the +.Xr sudo_plugin 8 +manual. +.Sh PATHS +A +.Li Path +line consists of the +.Li Path +keyword, followed by the name of the path to set and its value. +E.g. +.Bd -literal -offset indent +Path noexec @noexec_file@ +Path askpass /usr/X11R6/bin/ssh-askpass +.Ed +.Pp +The following plugin-agnostic paths may be set in the +.Pa @sysconfdir@/sudo.conf +file: +.Bl -tag -width 8n +.It askpass +The fully qualified path to a helper program used to read the user's +password when no terminal is available. +This may be the case when +.Nm sudo +is executed from a graphical (as opposed to text-based) application. +The program specified by +.Em askpass +should display the argument passed to it as the prompt and write +the user's password to the standard output. +The value of +.Em askpass +may be overridden by the +.Ev SUDO_ASKPASS +environment variable. +.It noexec +The fully-qualified path to a shared library containing dummy +versions of the +.Fn execv , +.Fn execve +and +.Fn fexecve +library functions that just return an error. +This is used to implement the +.Em noexec +functionality on systems that support +.Ev LD_PRELOAD +or its equivalent. +Defaults to +.Pa @noexec_file@ . +.El +.Sh DEBUG FLAGS +.Nm sudo +versions 1.8.4 and higher support a flexible debugging framework +that can help track down what +.Nm sudo +is doing internally if there is a problem. +.Pp +A +.Li Debug +line consists of the +.Li Debug +keyword, followed by the name of the program to debug +.Pq Nm sudo , Nm visudo , Nm sudoreplay , +the debug file name and a comma-separated list of debug flags. +The debug flag syntax used by +.Nm sudo +and the +.Em sudoers +plugin is +.Em subsystem No Ns @ Ns Em priority +but the plugin is free to use a different format so long as it does +not include a comma +.Pq Ql \&, . +.Pp +For instance: +.Bd -literal -offset indent +Debug sudo /var/log/sudo_debug all@warn,plugin@info +.Ed +.Pp +would log all debugging statements at the +.Em warn +level and higher in addition to those at the +.Em info +level for the plugin subsystem. +.Pp +Currently, only one +.Li Debug +entry per program is supported. +The +.Nm sudo +.Li Debug +entry is shared by the +.Nm sudo +front end, +.Nm sudoedit +and the plugins. +A future release may add support for per-plugin +.Li Debug +lines and/or support for multiple debugging files for a single +program. +.Pp +The priorities used by the +.Nm sudo +front end, in order of decreasing severity, are: +.Em crit , err , warn , notice , diag , info , trace +and +.Em debug . +Each priority, when specified, also includes all priorities higher +than it. +For example, a priority of +.Em notice +would include debug messages logged at +.Em notice +and higher. +.Pp +The following subsystems are used by the +.Nm sudo +front-end: +.Bl -tag -width Fl +.It Em all +matches every subsystem +.It Em args +command line argument processing +.It Em conv +user conversation +.It Em edit +sudoedit +.It Em exec +command execution +.It Em main +.Nm sudo +main function +.It Em netif +network interface handling +.It Em pcomm +communication with the plugin +.It Em plugin +plugin configuration +.It Em pty +pseudo-tty related code +.It Em selinux +SELinux-specific handling +.It Em util +utility functions +.It Em utmp +utmp handling +.El +.Sh EXIT VALUE +Upon successful execution of a program, the exit status from +.Em sudo +will simply be the exit status of the program that was executed. +.Pp +Otherwise, +.Nm sudo +exits with a value of 1 if there is a configuration/permission +problem or if +.Nm sudo +cannot execute the given command. +In the latter case the error string is printed to the standard error. +If +.Nm sudo +cannot +.Xr stat 2 +one or more entries in the user's +.Ev PATH , +an error is printed on stderr. +(If the directory does not exist or if it is not really a directory, +the entry is ignored and no error is printed.) +This should not happen under normal circumstances. +The most common reason for +.Xr stat 2 +to return +.Dq permission denied +is if you are running an automounter and one of the directories in +your +.Ev PATH +is on a machine that is currently unreachable. +.Sh SECURITY NOTES +.Nm sudo +tries to be safe when executing external commands. +.Pp +To prevent command spoofing, +.Nm sudo +checks "." and "" (both denoting current directory) last when +searching for a command in the user's +.Ev PATH (if one or both are in the +.Ev PATH ) . +Note, however, that the actual +.Ev PATH +environment variable is +.Em not +modified and is passed unchanged to the program that +.Nm sudo +executes. +.Pp +Please note that +.Nm sudo +will normally only log the command it explicitly runs. +If a user runs a command such as +.Li sudo su +or +.Li sudo sh , +subsequent commands run from that shell are not subject to +.Nm sudo No Ns 's +security policy. +The same is true for commands that offer shell escapes (including +most editors). +If I/O logging is enabled, subsequent commands will have their input and/or +output logged, but there will not be traditional logs for those commands. +Because of this, care must be taken when giving users access to commands via +.Nm sudo +to verify that the command does not inadvertently give the user an +effective root shell. +For more information, please see the +.Em PREVENTING SHELL ESCAPES +section in +.Xr sudoers 5 . +.Pp +To prevent the disclosure of potentially sensitive information, +.Nm sudo +disables core dumps by default while it is executing (they are +re-enabled for the command that is run). +To aid in debugging +.Nm sudo +crashes, you may wish to re-enable core dumps by setting +.Dq disable_coredump +to false in the +.Pa @sysconfdir@/sudo.conf +file as follows: +.Bd -literal -offset indent +Set disable_coredump false +.Ed +.Pp +Note that by default, most operating systems disable core dumps +from setuid programs, which includes +.Nm sudo . +To actually get a +.Nm sudo +core file you may need to enable core dumps for setuid processes. +On BSD and Linux systems this is accomplished via the sysctl command, +on Solaris the coreadm command can be used. +.Sh ENVIRONMENT +.Nm sudo +utilizes the following environment variables. +The security policy has control over the actual content of the command's +environment. +.Bl -tag -width 15n +.It Ev EDITOR +Default editor to use in +.Fl e +(sudoedit) mode if neither +.Ev SUDO_EDITOR +nor +.Ev VISUAL +is set. +.It Ev MAIL +In +.Fl i +mode or when +.Em env_reset +is enabled in +.Em sudoers , +set to the mail spool of the target user. +.It Ev HOME +Set to the home directory of the target user if +.Fl i +or +.Fl H +are specified, +.Em env_reset +or +.Em always_set_home +are set in +.Em sudoers , +or when the +.Fl s +option is specified and +.Em set_home +is set in +.Em sudoers . +.It Ev PATH +May be overridden by the security policy. +.It Ev SHELL +Used to determine shell to run with +.Fl s +option. +.It Ev SUDO_ASKPASS +Specifies the path to a helper program used to read the password +if no terminal is available or if the +.Fl A +option is specified. +.It Ev SUDO_COMMAND +Set to the command run by sudo. +.It Ev SUDO_EDITOR +Default editor to use in +.Fl e +(sudoedit) mode. +.It Ev SUDO_GID +Set to the group ID of the user who invoked sudo. +.It Ev SUDO_PROMPT +Used as the default password prompt. +.It Ev SUDO_PS1 +If set, +.Ev PS1 +will be set to its value for the program being run. +.It Ev SUDO_UID +Set to the user ID of the user who invoked sudo. +.It Ev SUDO_USER +Set to the login name of the user who invoked sudo. +.It Ev USER +Set to the target user (root unless the +.Fl u +option is specified). +.It Ev VISUAL +Default editor to use in +.Fl e +(sudoedit) mode if +.Ev SUDO_EDITOR +is not set. +.El +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +.Nm sudo +front end configuration +.El +.Sh EXAMPLES +Note: the following examples assume a properly configured security +policy. +.Pp +To get a file listing of an unreadable directory: +.Bd -literal -offset indent +$ sudo ls /usr/local/protected +.Ed +.Pp +To list the home directory of user yaz on a machine where the file +system holding ~yaz is not exported as root: +.Bd -literal -offset indent +$ sudo -u yaz ls ~yaz +.Ed +.Pp +To edit the +.Pa index.html +file as user www: +.Bd -literal -offset indent +$ sudo -u www vi ~www/htdocs/index.html +.Ed +.Pp +To view system logs only accessible to root and users in the adm +group: +.Bd -literal -offset indent +$ sudo -g adm view /var/log/syslog +.Ed +.Pp +To run an editor as jim with a different primary group: +.Bd -literal -offset indent +$ sudo -u jim -g audio vi ~jim/sound.txt +.Ed +.Pp +To shut down a machine: +.Bd -literal -offset indent +$ sudo shutdown -r +15 "quick reboot" +.Ed +.Pp +To make a usage listing of the directories in the /home partition. +Note that this runs the commands in a sub-shell to make the +.Li cd +and file redirection work. +.Bd -literal -offset indent +$ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE" +.Ed +.Sh SEE ALSO +.Xr grep 1 , +.Xr su 1 , +.Xr stat 2 , +.Xr login_cap 3 , +.Xr passwd 5 , +.Xr sudoers 5 , +.Xr sudo_plugin 8 , +.Xr sudoreplay 8 , +.Xr visudo 8 +.Sh HISTORY +See the HISTORY file in the +.Nm sudo +distribution (http://www.sudo.ws/sudo/history.html) for a brief +history of sudo. +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (http://www.sudo.ws/sudo/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh CAVEATS +There is no easy way to prevent a user from gaining a root shell +if that user is allowed to run arbitrary commands via +.Nm sudo . +Also, many programs (such as editors) allow the user to run commands +via shell escapes, thus avoiding +.Nm sudo No Ns 's +checks. +However, on most systems it is possible to prevent shell escapes with the +.Xr sudoers 5 +module's +.Em noexec +functionality. +.Pp +It is not meaningful to run the +.Li cd +command directly via sudo, e.g., +.Bd -literal -offset indent +$ sudo cd /usr/local/protected +.Ed +.Pp +since when the command exits the parent process (your shell) will +still be the same. +Please see the +.Sx EXAMPLES +section for more information. +.Pp +Running shell scripts via +.Nm sudo +can expose the same kernel bugs that make setuid shell scripts +unsafe on some operating systems (if your OS has a /dev/fd/ directory, +setuid shell scripts are generally safe). +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at http://www.sudo.ws/sudo/bugs/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or http://www.sudo.ws/sudo/license.html for complete details. diff --git a/doc/sudo_plugin.mdoc.in b/doc/sudo_plugin.mdoc.in new file mode 100644 index 000000000..323386b00 --- /dev/null +++ b/doc/sudo_plugin.mdoc.in @@ -0,0 +1,2155 @@ +.\" +.\" Copyright (c) 2009-2012 Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 16, 2012 +.Dt SUDO_PLUGIN 5 +.Os +.Sh NAME +.Nm sudo_plugin +.Nd Sudo Plugin API +.Sh DESCRIPTION +Starting with version 1.8, +.Nm sudo +supports a plugin API +for policy and session logging. +By default, the +.Em sudoers +policy plugin and an associated I/O logging plugin are used. +Via the plugin API, +.Nm sudo +can be configured to use alternate policy and/or I/O logging plugins +provided by third parties. +The plugins to be used are specified via the +.Pa @sysconfdir@/sudo.conf +file. +.Pp +The API is versioned with a major and minor number. +The minor version number is incremented when additions are made. +The major number is incremented when incompatible changes are made. +A plugin should be check the version passed to it and make sure that the +major version matches. +.Pp +The plugin API is defined by the +.Li sudo_plugin.h +header file. +.Ss The sudo.conf File +The +.Pa @sysconfdir@/sudo.conf +file contains plugin configuration directives. +The primary keyword is the +.Li Plugin +directive, which causes a plugin to be loaded. +.Pp +A +.Li Plugin +line consists of the +.Li Plugin +keyword, followed by the +.Em symbol_name +and the +.Em path +to the shared object containing the plugin. +The +.Em symbol_name +is the name of the +.Li struct policy_plugin +or +.Li struct io_plugin +in the plugin shared object. +The +.Em path +may be fully qualified or relative. +If not fully qualified it is relative to the +.Pa @prefix@/libexec +directory. +Any additional parameters after the +.Em path +are passed as options to the plugin's +.Fn open +function. +Lines that don't begin with +.Li Plugin , +.Li Path , +.Li Debug +or +.Li Set +are silently ignored. +.Pp +The same shared object may contain multiple plugins, each with a +different symbol name. +The shared object file must be owned by uid 0 and only writable by its owner. +Because of ambiguities that arise from composite policies, only a single +policy plugin may be specified. +This limitation does not apply to I/O plugins. +.Bd -literal +# +# Default @sysconfdir@/sudo.conf file +# +# Format: +# Plugin plugin_name plugin_path plugin_options ... +# Path askpass /path/to/askpass +# Path noexec /path/to/sudo_noexec.so +# Debug sudo /var/log/sudo_debug all@warn +# Set disable_coredump true +# +# The plugin_path is relative to @prefix@/libexec unless +# fully qualified. +# The plugin_name corresponds to a global symbol in the plugin +# that contains the plugin interface structure. +# The plugin_options are optional. +# +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so +.Ed +.Ss Policy Plugin API +A policy plugin must declare and populate a +.Li policy_plugin +struct in the global scope. +This structure contains pointers to the functions that implement the +.Nm sudo +policy checks. +The name of the symbol should be specified in +.Pa @sysconfdir@/sudo.conf +along with a path to the plugin so that +.Nm sudo +can load it. +.Bd -literal +struct policy_plugin { +#define SUDO_POLICY_PLUGIN 1 + unsigned int type; /* always SUDO_POLICY_PLUGIN */ + unsigned int version; /* always SUDO_API_VERSION */ + int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const user_env[], + char * const plugin_options[]); + void (*close)(int exit_status, int error); + int (*show_version)(int verbose); + int (*check_policy)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); + int (*list)(int argc, char * const argv[], int verbose, + const char *list_user); + int (*validate)(void); + void (*invalidate)(int remove); + int (*init_session)(struct passwd *pwd, char **user_env[]); + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); +}; +.Ed +.Pp +The policy_plugin struct has the following fields: +.Bl -tag -width 4n +.It type +The +.Li type +field should always be set to SUDO_POLICY_PLUGIN. +.It version +The +.Li version +field should be set to +.Dv SUDO_API_VERSION . +.Pp +This allows +.Nm sudo +to determine the API version the plugin was +built against. +.It open +.Bd -literal -compact +int (*open)(unsigned int version, sudo_conv_t conversation, + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], char * const user_env[], + char * const plugin_options[]); +.Ed +.Pp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error. +In the latter case, +.Nm sudo +will print a usage message before it exits. +If an error occurs, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional error information to the user. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It version +The version passed in by +.Nm sudo +allows the plugin to determine the +major and minor version number of the plugin API supported by +.Nm sudo . +.It conversation +A pointer to the +.Fn conversation +function that can be used by the plugin to interact with the user (see below). +Returns 0 on success and \-1 on failure. +.It plugin_printf +A pointer to a +.Fn printf Ns No -style +function that may be used to display informational or error messages +(see below). +Returns the number of characters printed on success and \-1 on failure. +.It settings +A vector of user-supplied +.Nm sudo +settings in the form of +.Dq name=value +strings. +The vector is terminated by a +.Dv NULL +pointer. +These settings correspond to flags the user specified when running +.Nm sudo . +As such, they will only be present when the corresponding flag has +been specified on the command line. +.Pp +When parsing +.Em settings , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.Bl -tag -width 4n +.It debug_flags=string +A comma-separated list of debug flags that correspond to +.Nm sudo Ns No 's +.Li Debug +entry in +.Pa @sysconfdir@/sudo.conf , +if there is one. +The flags are passed to the plugin as they appear in +.Pa @sysconfdir@/sudo.conf . +The syntax used by +.Nm sudo +and the +.Em sudoers +plugin is +.Em subsystem Ns No @ Ns Em priority +but the plugin is free to use a different +format so long as it does not include a comma +.Pq Ql ,\& . +.Pp +For reference, the priorities supported by the +.Nm sudo +front end and +.Em sudoers +are: +.Em crit , +.Em err , +.Em warn , +.Em notice , +.Em diag , +.Em info , +.Em trace +and +.Em debug . +.Pp +The following subsystems are defined: +.Em main , +.Em memory , +.Em args , +.Em exec , +.Em pty , +.Em utmp , +.Em conv , +.Em pcomm , +.Em util , +.Em list , +.Em netif , +.Em audit , +.Em edit , +.Em selinux , +.Em ldap , +.Em match , +.Em parser , +.Em alias , +.Em defaults , +.Em auth , +.Em env , +.Em logging , +.Em nss , +.Em rbtree , +.Em perms , +.Em plugin . +The subsystem +.Em all +includes every subsystem. +.Pp +There is not currently a way to specify a set of debug flags specific +to the plugin--the flags are shared by +.Nm sudo +and the plugin. +.It debug_level=number +This setting has been deprecated in favor of +.Em debug_flags . +.It runas_user=string +The user name or uid to to run the command as, if specified via the +.Fl u +flag. +.It runas_group=string +The group name or gid to to run the command as, if specified via +the +.Fl g +flag. +.It prompt=string +The prompt to use when requesting a password, if specified via +the +.Fl p +flag. +.It set_home=bool +Set to true if the user specified the +.Fl H +flag. +If true, set the +.Li HOME +environment variable to the target user's home directory. +.It preserve_environment=bool +Set to true if the user specified the +.Fl E +flag, indicating that +the user wishes to preserve the environment. +.It run_shell=bool +Set to true if the user specified the +.Fl s +flag, indicating that +the user wishes to run a shell. +.It login_shell=bool +Set to true if the user specified the +.Fl i +flag, indicating that +the user wishes to run a login shell. +.It implied_shell=bool +If the user does not specify a program on the command line, +.Nm sudo +will pass the plugin the path to the user's shell and set +.Em implied_shell +to true. +This allows +.Nm sudo +with no arguments +to be used similarly to +.Xr su 1 . +If the plugin does not to support this usage, it may return a value of \-2 +from the +.Fn check_policy +function, which will cause +.Nm sudo +to print a usage message and +exit. +.It preserve_groups=bool +Set to true if the user specified the +.Fl P +flag, indicating that +the user wishes to preserve the group vector instead of setting it +based on the runas user. +.It ignore_ticket=bool +Set to true if the user specified the +.Fl k +flag along with a +command, indicating that the user wishes to ignore any cached +authentication credentials. +.It noninteractive=bool +Set to true if the user specified the +.Fl n +flag, indicating that +.Nm sudo +should operate in non-interactive mode. +The plugin may reject a command run in non-interactive mode if user +interaction is required. +.It login_class=string +BSD login class to use when setting resource limits and nice value, +if specified by the +.Fl c +flag. +.It selinux_role=string +SELinux role to use when executing the command, if specified by +the +.Fl r +flag. +.It selinux_type=string +SELinux type to use when executing the command, if specified by +the +.Fl t +flag. +.It bsdauth_type=string +Authentication type, if specified by the +.Fl a +flag, to use on +systems where BSD authentication is supported. +.It network_addrs=list +A space-separated list of IP network addresses and netmasks in the +form +.Dq addr/netmask , +e.g.\& +.Dq 192.168.1.2/255.255.255.0 . +The address and netmask pairs may be either IPv4 or IPv6, depending on +what the operating system supports. +If the address contains a colon +.Pq Ql :\& , +it is an IPv6 address, else it is IPv4. +.It progname=string +The command name that sudo was run as, typically +.Dq sudo +or +.Dq sudoedit . +.It sudoedit=bool +Set to true when the +.Fl e +flag is is specified or if invoked as +.Nm sudoedit . +The plugin shall substitute an editor into +.Em argv +in the +.Fn check_policy +function or return \-2 with a usage error +if the plugin does not support +.Em sudoedit . +For more information, see the +.Em check_policy +section. +.It closefrom=number +If specified, the user has requested via the +.Fl C +flag that +.Nm sudo +close all files descriptors with a value of +.Em number +or higher. +The plugin may optionally pass this, or another value, back in the +.Em command_info +list. +.El +.Pp +Additional settings may be added in the future so the plugin should +silently ignore settings that it does not recognize. +.It user_info +A vector of information about the user running the command in the form of +.Dq name=value +strings. +The vector is terminated by a +.Dv NULL +pointer. +.Pp +When parsing +.Em user_info , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.Bl -tag -width 4n +.It pid=int +The process ID of the running +.Nm sudo +process. +Only available starting with API version 1.2 +.It ppid=int +The parent process ID of the running +.Nm sudo +process. +Only available starting with API version 1.2 +.It sid=int +The session ID of the running +.Nm sudo +process or 0 if +.Nm sudo +is +not part of a POSIX job control session. +Only available starting with API version 1.2 +.It pgid=int +The ID of the process group that the running +.Nm sudo +process belongs +to. +Only available starting with API version 1.2 +.It tcpgid=int +The ID of the forground process group associated with the terminal +device associcated with the +.Nm sudo +process or \-1 if there is no +terminal present. +Only available starting with API version 1.2 +.It user=string +The name of the user invoking +.Nm sudo . +.It euid=uid_t +The effective user ID of the user invoking +.Nm sudo . +.It uid=uid_t +The real user ID of the user invoking +.Nm sudo . +.It egid=gid_t +The effective group ID of the user invoking +.Nm sudo . +.It gid=gid_t +The real group ID of the user invoking +.Nm sudo . +.It groups=list +The user's supplementary group list formatted as a string of +comma-separated group IDs. +.It cwd=string +The user's current working directory. +.It tty=string +The path to the user's terminal device. +If the user has no terminal device associated with the session, +the value will be empty, as in +.Dq Li tty= . +.It host=string +The local machine's hostname as returned by the +.Xr gethostname 2 +system call. +.It lines=int +The number of lines the user's terminal supports. +If there is +no terminal device available, a default value of 24 is used. +.It cols=int +The number of columns the user's terminal supports. +If there is no terminal device available, a default value of 80 is used. +.El +.It user_env +The user's environment in the form of a +.Dv NULL Ns No -terminated vector of +.Dq name=value +strings. +.Pp +When parsing +.Em user_env , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.It plugin_options +Any (non-comment) strings immediately after the plugin path are +treated as arguments to the plugin. +These arguments are split on a white space boundary and are passed to +the plugin in the form of a +.Dv NULL Ns No -terminated +array of strings. +If no arguments were +specified, +.Em plugin_options +will be the +.Dv NULL +pointer. +.Pp +NOTE: the +.Em plugin_options +parameter is only available starting with +API version 1.2. +A plugin +.Sy must +check the API version specified +by the +.Nm sudo +front end before using +.Em plugin_options . +Failure to do so may result in a crash. +.El +.It close +.Bd -literal -compact +void (*close)(int exit_status, int error); +.Ed +.Pp +The +.Fn close +function is called when the command being run by +.Nm sudo +finishes. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It exit_status +The command's exit status, as returned by the +.Xr wait 2 +system call. +The value of +.Li exit_status +is undefined if +.Li error +is non-zero. +.It error +If the command could not be executed, this is set to the value of +.Li errno +set by the +.Xr execve 2 +system call. +The plugin is responsible for displaying error information via the +.Fn conversation +or +.Fn plugin_printf +function. +If the command was successfully executed, the value of +.Li error +is 0. +.El +.It show_version +.Bd -literal -compact +int (*show_version)(int verbose); +.Ed +.Pp +The +.Fn show_version +function is called by +.Nm sudo +when the user specifies +the +.Fl V +option. +The plugin may display its version information to the user via the +.Fn conversation +or +.Fn plugin_printf +function using +.Dv SUDO_CONV_INFO_MSG . +If the user requests detailed version information, the verbose flag will be set. +.It check_policy +.Bd -literal -compact +int (*check_policy)(int argc, char * const argv[] + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); +.Ed +.Pp +The +.Fn check_policy +function is called by +.Nm sudo +to determine +whether the user is allowed to run the specified commands. +.Pp +If the +.Em sudoedit +option was enabled in the +.Em settings +array +passed to the +.Fn open +function, the user has requested +.Em sudoedit +mode. +.Em sudoedit +is a mechanism for editing one or more files +where an editor is run with the user's credentials instead of with +elevated privileges. +.Nm sudo +achieves this by creating user-writable +temporary copies of the files to be edited and then overwriting the +originals with the temporary copies after editing is complete. +If the plugin supports +.Em sudoedit , +it should choose the editor to be used, potentially from a variable +in the user's environment, such as +.Li EDITOR , +and include it in +.Em argv_out +(note that environment +variables may include command line flags). +The files to be edited should be copied from +.Em argv +into +.Em argv_out , +separated from the +editor and its arguments by a +.Dq Li -- +element. +The +.Dq Li -- +will +be removed by +.Nm sudo +before the editor is executed. +The plugin should also set +.Em sudoedit=true +in the +.Em command_info +list. +.Pp +The +.Fn check_policy +function returns 1 if the command is allowed, +0 if not allowed, \-1 for a general error, or \-2 for a usage error +or if +.Em sudoedit +was specified but is unsupported by the plugin. +In the latter case, +.Nm sudo +will print a usage message before it +exits. +If an error occurs, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional error information to the user. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It argc +The number of elements in +.Em argv , +not counting the final +.Dv NULL +pointer. +.It argv +The argument vector describing the command the user wishes to run, +in the same form as what would be passed to the +.Xr execve 2 +system call. +The vector is terminated by a +.Dv NULL +pointer. +.It env_add +Additional environment variables specified by the user on the command +line in the form of a +.Dv NULL Ns No -terminated +vector of +.Dq name=value +strings. +The plugin may reject the command if one or more variables +are not allowed to be set, or it may silently ignore such variables. +.Pp +When parsing +.Em env_add , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.It command_info +Information about the command being run in the form of +.Dq name=value +strings. +These values are used by +.Nm sudo +to set the execution +environment when running a command. +The plugin is responsible for creating and populating the vector, +which must be terminated with a +.Dv NULL +pointer. +The following values are recognized by +.Nm sudo : +.Bl -tag -width 4n +.It command=string +Fully qualified path to the command to be executed. +.It runas_uid=uid +User ID to run the command as. +.It runas_euid=uid +Effective user ID to run the command as. +If not specified, the value of +.Em runas_uid +is used. +.It runas_gid=gid +Group ID to run the command as. +.It runas_egid=gid +Effective group ID to run the command as. +If not specified, the value of +.Em runas_gid +is used. +.It runas_groups=list +The supplementary group vector to use for the command in the form +of a comma-separated list of group IDs. +If +.Em preserve_groups +is set, this option is ignored. +.It login_class=string +BSD login class to use when setting resource limits and nice value +(optional). +This option is only set on systems that support login classes. +.It preserve_groups=bool +If set, +.Nm sudo +will preserve the user's group vector instead of +initializing the group vector based on +.Li runas_user . +.It cwd=string +The current working directory to change to when executing the command. +.It noexec=bool +If set, prevent the command from executing other programs. +.It chroot=string +The root directory to use when running the command. +.It nice=int +Nice value (priority) to use when executing the command. +The nice value, if specified, overrides the priority associated with the +.Em login_class +on BSD systems. +.It umask=octal +The file creation mask to use when executing the command. +.It selinux_role=string +SELinux role to use when executing the command. +.It selinux_type=string +SELinux type to use when executing the command. +.It timeout=int +Command timeout. +If non-zero then when the timeout expires the command will be killed. +.It sudoedit=bool +Set to true when in +.Em sudoedit +mode. +The plugin may enable +.Em sudoedit +mode even if +.Nm sudo +was not invoked as +.Nm sudoedit . +This allows the plugin to perform command substitution and transparently +enable +.Em sudoedit +when the user attempts to run an editor. +.It closefrom=number +If specified, +.Nm sudo +will close all files descriptors with a value +of +.Em number +or higher. +.It iolog_compress=bool +Set to true if the I/O logging plugins, if any, should compress the +log data. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_path=string +Fully qualified path to the file or directory in which I/O log is +to be stored. +This is a hint to the I/O logging plugin which may choose to ignore it. +If no I/O logging plugin is loaded, this setting has no effect. +.It iolog_stdin=bool +Set to true if the I/O logging plugins, if any, should log the +standard input if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_stdout=bool +Set to true if the I/O logging plugins, if any, should log the +standard output if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_stderr=bool +Set to true if the I/O logging plugins, if any, should log the +standard error if it is not connected to a terminal device. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_ttyin=bool +Set to true if the I/O logging plugins, if any, should log all +terminal input. +This only includes input typed by the user and not from a pipe or +redirected from a file. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It iolog_ttyout=bool +Set to true if the I/O logging plugins, if any, should log all +terminal output. +This only includes output to the screen, not output to a pipe or file. +This is a hint to the I/O logging plugin which may choose to ignore it. +.It use_pty=bool +Allocate a pseudo-tty to run the command in, regardless of whether +or not I/O logging is in use. +By default, +.Nm sudo +will only run +the command in a pty when an I/O log plugin is loaded. +.It set_utmp=bool +Create a utmp (or utmpx) entry when a pseudo-tty is allocated. +By default, the new entry will be a copy of the user's existing utmp +entry (if any), with the tty, time, type and pid fields updated. +.It utmp_user=string +User name to use when constructing a new utmp (or utmpx) entry when +.Em set_utmp +is enabled. +This option can be used to set the user field in the utmp entry to +the user the command runs as rather than the invoking user. +If not set, +.Nm sudo +will base the new entry on +the invoking user's existing entry. +.El +.Pp +Unsupported values will be ignored. +.It argv_out +The +.Dv NULL Ns No -terminated +argument vector to pass to the +.Xr execve 2 +system call when executing the command. +The plugin is responsible for allocating and populating the vector. +.It user_env_out +The +.Dv NULL Ns No -terminated +environment vector to use when executing the command. +The plugin is responsible for allocating and populating the vector. +.El +.It list +.Bd -literal -compact +int (*list)(int verbose, const char *list_user, + int argc, char * const argv[]); +.Ed +.Pp +List available privileges for the invoking user. +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional error information to +the user. +.Pp +Privileges should be output via the +.Fn conversation +or +.Fn plugin_printf +function using +.Dv SUDO_CONV_INFO_MSG , +.Bl -tag -width 4n +.It verbose +Flag indicating whether to list in verbose mode or not. +.It list_user +The name of a different user to list privileges for if the policy +allows it. +If +.Dv NULL , +the plugin should list the privileges of the invoking user. +.It argc +The number of elements in +.Em argv , +not counting the final +.Dv NULL +pointer. +.It argv +If +.No non- Ns Dv NULL , +an argument vector describing a command the user +wishes to check against the policy in the same form as what would +be passed to the +.Xr execve 2 +system call. +If the command is permitted by the policy, the fully-qualified path +to the command should be displayed along with any command line arguments. +.El +.It validate +.Bd -literal -compact +int (*validate)(void); +.Ed +.Pp +The +.Fn validate +function is called when +.Nm sudo +is run with the +.Fl v +flag. +For policy plugins such as +.Em sudoers +that cache +authentication credentials, this function will validate and cache +the credentials. +.Pp +The +.Fn validate +function should be +.Dv NULL +if the plugin does not support credential caching. +.Pp +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional +error information to the user. +.It invalidate +.Bd -literal -compact +void (*invalidate)(int remove); +.Ed +.Pp +The +.Fn invalidate +function is called when +.Nm sudo +is called with +the +.Fl k +or +.Fl K +flag. +For policy plugins such as +.Em sudoers +that +cache authentication credentials, this function will invalidate the +credentials. +If the +.Em remove +flag is set, the plugin may remove +the credentials instead of simply invalidating them. +.Pp +The +.Fn invalidate +function should be +.Dv NULL +if the plugin does not support credential caching. +.It init_session +.Bd -literal -compact +int (*init_session)(struct passwd *pwd, char **user_envp[); +.Ed +.Pp +The +.Fn init_session +function is called before +.Nm sudo +sets up the +execution environment for the command. +It is run in the parent +.Nm sudo +process and before any uid or gid changes. +This can be used to perform session setup that is not supported by +.Em command_info , +such as opening the PAM session. +The +.Fn close +function can be +used to tear down the session that was opened by +.Li init_session . +.Pp +The +.Em pwd +argument points to a passwd struct for the user the +command will be run as if the uid the command will run as was found +in the password database, otherwise it will be +.Dv NULL . +.Pp +The +.Em user_env +argument points to the environment the command will +run in, in the form of a +.Dv NULL Ns No -terminated +vector of +.Dq name=value +strings. +This is the same string passed back to the front end via +the Policy Plugin's +.Em user_env_out +parameter. +If the +.Fn init_session +function needs to modify the user environment, it should update the +pointer stored in +.Em user_env . +The expected use case is to merge the contents of the PAM environment +(if any) with the contents of +.Em user_env . +NOTE: the +.Em user_env +parameter is only available +starting with API version 1.2. +A plugin +.Sy must +check the API +version specified by the +.Nm sudo +front end before using +.Em user_env . +Failure to do so may result in a crash. +.Pp +Returns 1 on success, 0 on failure and \-1 on error. +On error, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional +error information to the user. +.It register_hooks +.Bd -literal -compact +void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); +.Ed +.Pp +The +.Fn register_hooks +function is called by the sudo front end to +register any hooks the plugin needs. +If the plugin does not support hooks, +.Li register_hooks +should be set to the +.Dv NULL +pointer. +.Pp +The +.Em version +argument describes the version of the hooks API +supported by the +.Nm sudo +front end. +.Pp +The +.Fn register_hook +function should be used to register any supported +hooks the plugin needs. +It returns 0 on success, 1 if the hook type is not supported and \-1 +if the major version in +.Li struct hook +does not match the front end's major hook API version. +.Pp +See the +.Sx Hook Function API +section below for more information +about hooks. +.Pp +NOTE: the +.Fn register_hooks +function is only available starting +with API version 1.2. +If the +.Nm sudo +front end doesn't support API +version 1.2 or higher, +.Li register_hooks +will not be called. +.It deregister_hooks +.Bd -literal -compact +void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); +.Ed +.Pp +The +.Fn deregister_hooks +function is called by the sudo front end +to deregister any hooks the plugin has registered. +If the plugin does not support hooks, +.Li deregister_hooks +should be set to the +.Dv NULL +pointer. +.Pp +The +.Em version +argument describes the version of the hooks API +supported by the +.Nm sudo +front end. +.Pp +The +.Fn deregister_hook +function should be used to deregister any +hooks that were put in place by the +.Fn register_hook +function. +If the plugin tries to deregister a hook that the front end does not support, +.Li deregister_hook +will return an error. +.Pp +See the +.Sx Hook Function API +section below for more information +about hooks. +.Pp +NOTE: the +.Fn deregister_hooks +function is only available starting +with API version 1.2. +If the +.Nm sudo +front end doesn't support API +version 1.2 or higher, +.Li deregister_hooks +will not be called. +.El +.Pp +.Em Policy Plugin Version Macros +.Bd -literal +/* Plugin API version major/minor. */ +#define SUDO_API_VERSION_MAJOR 1 +#define SUDO_API_VERSION_MINOR 2 +#define SUDO_API_MKVERSION(x, y) ((x << 16) | y) +#define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e + SUDO_API_VERSION_MINOR) + +/* Getters and setters for API version */ +#define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16) +#define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff) +#define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e + *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e +} while(0) +#define SUDO_VERSION_SET_MINOR(vp, n) do { \e + *(vp) = (*(vp) & 0xffff0000) | (n); \e +} while(0) +.Ed +.Ss I/O Plugin API +.Bd -literal +struct io_plugin { +#define SUDO_IO_PLUGIN 2 + unsigned int type; /* always SUDO_IO_PLUGIN */ + unsigned int version; /* always SUDO_API_VERSION */ + int (*open)(unsigned int version, sudo_conv_t conversation + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], int argc, char * const argv[], + char * const user_env[], char * const plugin_options[]); + void (*close)(int exit_status, int error); /* wait status or error */ + int (*show_version)(int verbose); + int (*log_ttyin)(const char *buf, unsigned int len); + int (*log_ttyout)(const char *buf, unsigned int len); + int (*log_stdin)(const char *buf, unsigned int len); + int (*log_stdout)(const char *buf, unsigned int len); + int (*log_stderr)(const char *buf, unsigned int len); + void (*register_hooks)(int version, + int (*register_hook)(struct sudo_hook *hook)); + void (*deregister_hooks)(int version, + int (*deregister_hook)(struct sudo_hook *hook)); +}; +.Ed +.Pp +When an I/O plugin is loaded, +.Nm sudo +runs the command in a pseudo-tty. +This makes it possible to log the input and output from the user's +session. +If any of the standard input, standard output or standard error do not +correspond to a tty, +.Nm sudo +will open a pipe to capture +the I/O for logging before passing it on. +.Pp +The log_ttyin function receives the raw user input from the terminal +device (note that this will include input even when echo is disabled, +such as when a password is read). +The log_ttyout function receives output from the pseudo-tty that is +suitable for replaying the user's session at a later time. +The +.Fn log_stdin , +.Fn log_stdout +and +.Fn log_stderr +functions are only called if the standard input, standard output +or standard error respectively correspond to something other than +a tty. +.Pp +Any of the logging functions may be set to the +.Dv NULL +pointer if no logging is to be performed. +If the open function returns 0, no I/O will be sent to the plugin. +.Pp +The io_plugin struct has the following fields: +.Bl -tag -width 4n +.It type +The +.Li type +field should always be set to +.Dv SUDO_IO_PLUGIN . +.It version +The +.Li version +field should be set to +.Dv SUDO_API_VERSION . +.Pp +This allows +.Nm sudo +to determine the API version the plugin was +built against. +.It open +.Bd -literal -compact +int (*open)(unsigned int version, sudo_conv_t conversation + sudo_printf_t plugin_printf, char * const settings[], + char * const user_info[], int argc, char * const argv[], + char * const user_env[], char * const plugin_options[]); +.Ed +.Pp +The +.Fn open +function is run before the +.Fn log_input , +.Fn log_output +or +.Fn show_version +functions are called. +It is only called if the version is being requested or the +.Fn check_policy +function has +returned successfully. +It returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error. +In the latter case, +.Nm sudo +will print a usage message before it exits. +If an error occurs, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present +additional error information to the user. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It version +The version passed in by +.Nm sudo +allows the plugin to determine the +major and minor version number of the plugin API supported by +.Nm sudo . +.It conversation +A pointer to the +.Fn conversation +function that may be used by the +.Fn show_version +function to display version information (see +.Fn show_version +below). +The +.Fn conversation +function may also be used to display additional error message to the user. +The +.Fn conversation +function returns 0 on success and \-1 on failure. +.It plugin_printf +A pointer to a +.Fn printf Ns No -style +function that may be used by the +.Fn show_version +function to display version information (see +show_version below). +The +.Fn plugin_printf +function may also be used to display additional error message to the user. +The +.Fn plugin_printf +function returns number of characters printed on success and \-1 on failure. +.It settings +A vector of user-supplied +.Nm sudo +settings in the form of +.Dq name=value +strings. +The vector is terminated by a +.Dv NULL +pointer. +These settings correspond to flags the user specified when running +.Nm sudo . +As such, they will only be present when the corresponding flag has +been specified on the command line. +.Pp +When parsing +.Em settings , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.Pp +See the +.Sx Policy Plugin API +section for a list of all possible settings. +.It user_info +A vector of information about the user running the command in the form of +.Dq name=value +strings. +The vector is terminated by a +.Dv NULL +pointer. +.Pp +When parsing +.Em user_info , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.Pp +See the +.Sx Policy Plugin API +section for a list of all possible strings. +.It argc +The number of elements in +.Em argv , +not counting the final +.Dv NULL +pointer. +.It argv +If +.No non- Ns Dv NULL , +an argument vector describing a command the user +wishes to run in the same form as what would be passed to the +.Xr execve 2 +system call. +.It user_env +The user's environment in the form of a +.Dv NULL Ns No -terminated +vector of +.Dq name=value +strings. +.Pp +When parsing +.Em user_env , +the plugin should split on the +.Sy first +equal sign +.Pq Ql = +since the +.Em name +field will never include one +itself but the +.Em value +might. +.It plugin_options +Any (non-comment) strings immediately after the plugin path are +treated as arguments to the plugin. +These arguments are split on a white space boundary and are passed to +the plugin in the form of a +.Dv NULL Ns No -terminated +array of strings. +If no arguments were specified, +.Em plugin_options +will be the +.Dv NULL +pointer. +.Pp +NOTE: the +.Em plugin_options +parameter is only available starting with +API version 1.2. +A plugin +.Sy must +check the API version specified +by the +.Nm sudo +front end before using +.Em plugin_options . +Failure to do so may result in a crash. +.El +.It close +.Bd -literal -compact +void (*close)(int exit_status, int error); +.Ed +.Pp +The +.Fn close +function is called when the command being run by +.Nm sudo +finishes. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It exit_status +The command's exit status, as returned by the +.Xr wait 2 +system call. +The value of +.Li exit_status +is undefined if +.Li error +is non-zero. +.It error +If the command could not be executed, this is set to the value of +.Li errno +set by the +.Xr execve 2 +system call. +If the command was successfully executed, the value of +.Li error +is 0. +.El +.It show_version +.Bd -literal -compact +int (*show_version)(int verbose); +.Ed +.Pp +The +.Fn show_version +function is called by +.Nm sudo +when the user specifies +the +.Fl V +option. +The plugin may display its version information to the user via the +.Fn conversation +or +.Fn plugin_printf +function using +.Dv SUDO_CONV_INFO_MSG . +If the user requests detailed version information, the verbose flag will be set. +.It log_ttyin +.Bd -literal -compact +int (*log_ttyin)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_ttyin +function is called whenever data can be read from +the user but before it is passed to the running command. +This allows the plugin to reject data if it chooses to (for instance +if the input contains banned content). +Returns 1 if the data should be passed to the command, 0 if the data +is rejected (which will terminate the command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing user input. +.It len +The length of +.Em buf +in bytes. +.El +.It log_ttyout +.Bd -literal -compact +int (*log_ttyout)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_ttyout +function is called whenever data can be read from +the command but before it is written to the user's terminal. +This allows the plugin to reject data if it chooses to (for instance +if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is rejected +(which will terminate the command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing command output. +.It len +The length of +.Em buf +in bytes. +.El +.It log_stdin +.Bd -literal -compact +int (*log_stdin)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_stdin +function is only used if the standard input does +not correspond to a tty device. +It is called whenever data can be read from the standard input but +before it is passed to the running command. +This allows the plugin to reject data if it chooses to +(for instance if the input contains banned content). +Returns 1 if the data should be passed to the command, 0 if the data is +rejected (which will terminate the command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing user input. +.It len +The length of +.Em buf +in bytes. +.El +.It log_stdout +.Bd -literal -compact +int (*log_stdout)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_stdout +function is only used if the standard output does not correspond +to a tty device. +It is called whenever data can be read from the command but before +it is written to the standard output. +This allows the plugin to reject data if it chooses to +(for instance if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is +rejected (which will terminate the command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing command output. +.It len +The length of +.Em buf +in bytes. +.El +.It log_stderr +.Bd -literal -compact +int (*log_stderr)(const char *buf, unsigned int len); +.Ed +.Pp +The +.Fn log_stderr +function is only used if the standard error does +not correspond to a tty device. +It is called whenever data can be read from the command but before it +is written to the standard error. +This allows the plugin to reject data if it chooses to +(for instance if the output contains banned content). +Returns 1 if the data should be passed to the user, 0 if the data is +rejected (which will terminate the command) or \-1 if an error occurred. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It buf +The buffer containing command output. +.It len +The length of +.Em buf +in bytes. +.El +.It register_hooks +See the +.Sx Policy Plugin API +section for a description of +.Li register_hooks . +.It deregister_hooks +See the +.Sx Policy Plugin API +section for a description of +.Li deregister_hooks. +.El +.Pp +.Em I/O Plugin Version Macros +.Pp +Same as for the +.Sx Policy Plugin API . +.Ss Hook Function API +Beginning with plugin API version 1.2, it is possible to install +hooks for certain functions called by the +.Nm sudo +front end. +.Pp +Currently, the only supported hooks relate to the handling of +environment variables. +Hooks can be used to intercept attempts to get, set, or remove +environment variables so that these changes can be reflected in +the version of the environment that is used to execute a command. +A future version of the API will support hooking internal +.Nm sudo +front end functions as well. +.Pp +.Em Hook structure +.Pp +Hooks in +.Nm sudo +are described by the following structure: +.Bd -literal +typedef int (*sudo_hook_fn_t)(); + +struct sudo_hook { + int hook_version; + int hook_type; + sudo_hook_fn_t hook_fn; + void *closure; +}; +.Ed +.Pp +The +.Li sudo_hook +structure has the following fields: +.Bl -tag -width 4n +.It hook_version +The +.Li hook_version +field should be set to +.Dv SUDO_HOOK_VERSION . +.It hook_type +The +.Li hook_type +field may be one of the following supported hook types: +.Bl -tag -width 4n +.It Dv SUDO_HOOK_SETENV +The C library +.Xr setenv 3 +function. +Any registered hooks will run before the C library implementation. +The +.Li hook_fn +field should +be a function that matches the following typedef: +.Bd -literal +typedef int (*sudo_hook_fn_setenv_t)(const char *name, + const char *value, int overwrite, void *closure); +.Ed +.Pp +If the registered hook does not match the typedef the results are +unspecified. +.It Dv SUDO_HOOK_UNSETENV +The C library +.Xr unsetenv 3 +function. +Any registered hooks will run before the C library implementation. +The +.Li hook_fn +field should +be a function that matches the following typedef: +.Bd -literal +typedef int (*sudo_hook_fn_unsetenv_t)(const char *name, + void *closure); +.Ed +.It Dv SUDO_HOOK_GETENV +The C library +.Xr getenv 3 +function. +Any registered hooks will run before the C library implementation. +The +.Li hook_fn +field should +be a function that matches the following typedef: +.Bd -literal +typedef int (*sudo_hook_fn_getenv_t)(const char *name, + char **value, void *closure); +.Ed +.Pp +If the registered hook does not match the typedef the results are +unspecified. +.It Dv SUDO_HOOK_PUTENV +The C library +.Xr putenv 3 +function. +Any registered hooks will run before the C library implementation. +The +.Li hook_fn +field should +be a function that matches the following typedef: +.Bd -literal +typedef int (*sudo_hook_fn_putenv_t)(char *string, + void *closure); +.Ed +.Pp +If the registered hook does not match the typedef the results are +unspecified. +.El +.It hook_fn +sudo_hook_fn_t hook_fn; +.Pp +The +.Li hook_fn +field should be set to the plugin's hook implementation. +The actual function arguments will vary depending on the +.Li hook_type +(see +.Li hook_type +above). +In all cases, the +.Li closure +field of +.Li struct sudo_hook +is passed as the last function parameter. +This can be used to pass arbitrary data to the plugin's hook implementation. +.Pp +The function return value may be one of the following: +.Bl -tag -width 4n +.It Dv SUDO_HOOK_RET_ERROR +The hook function encountered an error. +.It Dv SUDO_HOOK_RET_NEXT +The hook completed without error, go on to the next hook (including +the native implementation if applicable). +For example, a +.Xr getenv 3 +hook might return +.Dv SUDO_HOOK_RET_NEXT +if the specified variable was not found in the private copy of the environment. +.It Dv SUDO_HOOK_RET_STOP +The hook completed without error, stop processing hooks for this invocation. +This can be used to replace the native implementation. +For example, a +.Li setenv +hook that operates on a private copy of +the environment but leaves +.Li environ +unchanged. +.El +.El +.Pp +Note that it is very easy to create an infinite loop when hooking +C library functions. +For example, a +.Xr getenv 3 +hook that calls the +.Xr snprintf 3 +function may create a loop if the +.Xr snprintf 3 +implementation calls +.Xr getenv 3 +to check the locale. +To prevent this, you may wish to use a static variable in the hook +function to guard against nested calls. +For example: +.Bd -literal +static int in_progress = 0; /* avoid recursion */ +if (in_progress) + return SUDO_HOOK_RET_NEXT; +in_progress = 1; +\&... +in_progress = 0; +return SUDO_HOOK_RET_STOP; +.Ed +.Pp +.Em Hook API Version Macros +.Bd -literal +/* Hook API version major/minor */ +#define SUDO_HOOK_VERSION_MAJOR 1 +#define SUDO_HOOK_VERSION_MINOR 0 +#define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y) +#define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e + SUDO_HOOK_VERSION_MINOR) + +/* Getters and setters for hook API version */ +#define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16) +#define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff) +#define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \e + *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e +} while(0) +#define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \e + *(vp) = (*(vp) & 0xffff0000) | (n); \e +} while(0) +.Ed +.Ss Conversation API +If the plugin needs to interact with the user, it may do so via the +.Fn conversation +function. +A plugin should not attempt to read directly from the standard input +or the user's tty (neither of which are guaranteed to exist). +The caller must include a trailing newline in +.Li msg +if one is to be printed. +.Pp +A +.Fn printf Ns No -style +function is also available that can be used to display informational +or error messages to the user, which is usually more convenient for +simple messages where no use input is required. +.Bd -literal +struct sudo_conv_message { +#define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */ +#define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */ +#define SUDO_CONV_ERROR_MSG 0x0003 /* error message */ +#define SUDO_CONV_INFO_MSG 0x0004 /* informational message */ +#define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */ +#define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */ +#define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */ + int msg_type; + int timeout; + const char *msg; +}; + +struct sudo_conv_reply { + char *reply; +}; + +typedef int (*sudo_conv_t)(int num_msgs, + const struct sudo_conv_message msgs[], + struct sudo_conv_reply replies[]); + +typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...); +.Ed +.Pp +Pointers to the +.Fn conversation +and +.Fn printf Ns No -style +functions are passed +in to the plugin's +.Fn open +function when the plugin is initialized. +.Pp +To use the +.Fn conversation +function, the plugin must pass an array of +.Li sudo_conv_message +and +.Li sudo_conv_reply +structures. +There must be a +.Li struct sudo_conv_message +and +.Li struct sudo_conv_reply +for +each message in the conversation. +The plugin is responsible for freeing the reply buffer filled in to the +.Li struct sudo_conv_reply , +if any. +.Pp +The +.Fn printf Ns No -style +function uses the same underlying mechanism as the +.Fn conversation +function but only supports +.Dv SUDO_CONV_INFO_MSG , +.Dv SUDO_CONV_ERROR_MSG +and +.Dv SUDO_CONV_DEBUG_MSG +for the +.Em msg_type +parameter. +It can be more convenient than using the +.Fn conversation +function if no user reply is needed and supports standard +.Fn printf +escape sequences. +.Pp +Unlike, +.Dv SUDO_CONV_INFO_MSG +and +Dv SUDO_CONV_ERROR_MSG , +messages +sent with the +.Dv SUDO_CONV_DEBUG_MSG +.Em msg_type +are not directly +user-visible. +Instead, they are logged to the file specified in the +.Li Debug +statement (if any) in the +.Pa @sysconfdir@/sudo.conf +.Pp +file. +This allows a plugin to log debugging information and is intended +to be used in conjunction with the +.Em debug_flags +setting. +.Pp +See the sample plugin for an example of the +.Fn conversation +function usage. +.Ss Sudoers Group Plugin API +The +.Em sudoers +module supports a plugin interface to allow non-Unix +group lookups. +This can be used to query a group source other than the standard Unix +group database. +A sample group plugin is bundled with +.Nm sudo +that implements file-based lookups. +Third party group plugins include a QAS AD plugin available from Quest Software. +.Pp +A group plugin must declare and populate a +.Li sudoers_group_plugin +struct in the global scope. +This structure contains pointers to the functions that implement plugin +initialization, cleanup and group lookup. +.Bd -literal +struct sudoers_group_plugin { + unsigned int version; + int (*init)(int version, sudo_printf_t sudo_printf, + char *const argv[]); + void (*cleanup)(void); + int (*query)(const char *user, const char *group, + const struct passwd *pwd); +}; +.Ed +.Pp +The +.Li sudoers_group_plugin +struct has the following fields: +.Bl -tag -width 4n +.It version +The +.Li version +field should be set to GROUP_API_VERSION. +.Pp +This allows +.Em sudoers +to determine the API version the group plugin +was built against. +.It init +.Bd -literal -compact +int (*init)(int version, sudo_printf_t plugin_printf, + char *const argv[]); +.Ed +.Pp +The +.Fn init +function is called after +.Em sudoers +has been parsed but +before any policy checks. +It returns 1 on success, 0 on failure (or if the plugin is not configured), +and \-1 if a error occurred. +If an error occurs, the plugin may call the +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional error information +to the user. +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It version +The version passed in by +.Em sudoers +allows the plugin to determine the +major and minor version number of the group plugin API supported by +.Em sudoers . +.It plugin_printf +A pointer to a +.Fn printf Ns No -style +function that may be used to display informational or error message to the user. +Returns the number of characters printed on success and \-1 on failure. +.It argv +A +.Dv NULL Ns No -terminated +array of arguments generated from the +.Em group_plugin +option in +.Em sudoers . +If no arguments were given, +.Em argv +will be +.Dv NULL . +.El +.It cleanup +.Bd -literal -compact +void (*cleanup)(); +.Ed +.Pp +The +.Fn cleanup +function is called when +.Em sudoers +has finished its +group checks. +The plugin should free any memory it has allocated and close open file handles. +.It query +.Bd -literal -compact +int (*query)(const char *user, const char *group, + const struct passwd *pwd); +.Ed +.Pp +The +.Fn query +function is used to ask the group plugin whether +.Em user +is a member of +.Em group . +.Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It user +The name of the user being looked up in the external group database. +.It group +The name of the group being queried. +.It pwd +The password database entry for +.Em user , +if any. +If +.Em user +is not +present in the password database, +.Em pwd +will be +.Dv NULL . +.El +.El +.Pp +.Em Group API Version Macros +.Bd -literal +/* Sudoers group plugin version major/minor */ +#define GROUP_API_VERSION_MAJOR 1 +#define GROUP_API_VERSION_MINOR 0 +#define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e + GROUP_API_VERSION_MINOR) + +/* Getters and setters for group version */ +#define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16) +#define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff) +#define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \e + *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e +} while(0) +#define GROUP_API_VERSION_SET_MINOR(vp, n) do { \e + *(vp) = (*(vp) & 0xffff0000) | (n); \e +} while(0) +.Ed +.Sh PLUGIN API CHANGELOG +The following revisions have been made to the Sudo Plugin API. +.Bl -tag -width 4n +.It Version 1.0 +Initial API version. +.It Version 1.1 +The I/O logging plugin's +.Fn open +function was modified to take the +.Li command_info +list as an argument. +.It Version 1.2 +The Policy and I/O logging plugins' +.Fn open +functions are now passed +a list of plugin options if any are specified in +.Pa @sysconfdir@/sudo.conf . +.Pp +A simple hooks API has been introduced to allow plugins to hook in to the +system's environment handling functions. +.Pp +The +.Li init_session +Policy plugin function is now passed a pointer +to the user environment which can be updated as needed. +This can be used to merge in environment variables stored in the PAM +handle before a command is run. +.El +.Sh SEE ALSO +.Xr sudoers 5 , +.Xr sudo 8 +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at http://www.sudo.ws/sudo/bugs/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or http://www.sudo.ws/sudo/license.html for complete details. diff --git a/doc/sudoers.ldap.mdoc.in b/doc/sudoers.ldap.mdoc.in new file mode 100644 index 000000000..73b014b5a --- /dev/null +++ b/doc/sudoers.ldap.mdoc.in @@ -0,0 +1,1103 @@ +.\" +.\" Copyright (c) 2003-2012 Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 12, 2012 +.Dt SUDOERS.LDAP 5 +.Os +.Sh NAME +.Nm sudoers.ldap +.Nd sudo LDAP configuration +.Sh DESCRIPTION +In addition to the standard +.Em sudoers +file, +.Nm sudo +may be configured +via LDAP. +This can be especially useful for synchronizing +.Em sudoers +in a large, distributed environment. +.Pp +Using LDAP for +.Em sudoers +has several benefits: +.Bl -bullet +.It +.Nm sudo +no longer needs to read +.Em sudoers +in its entirety. +When LDAP is used, there are only two or three LDAP queries per invocation. +This makes it especially fast and particularly usable in LDAP environments. +.It +.Nm sudo +no longer exits if there is a typo in +.Em sudoers . +It is not possible to load LDAP data into the server that does +not conform to the sudoers schema, so proper syntax is guaranteed. +It is still possible to have typos in a user or host name, but +this will not prevent +.Nm sudo +from running. +.It +It is possible to specify per-entry options that override the global +default options. +.Pa @sysconfdir@/sudoers +only supports default options and limited options associated with +user/host/commands/aliases. +The syntax is complicated and can be difficult for users to understand. +Placing the options directly in the entry is more natural. +.It +The +.Nm visudo +program is no longer needed. +.Nm visudo +provides locking and syntax checking of the +.Pa @sysconfdir@/sudoers +file. +Since LDAP updates are atomic, locking is no longer necessary. +Because syntax is checked when the data is inserted into LDAP, there +is no need for a specialized tool to check syntax. +.El +.Pp +Another major difference between LDAP and file-based +.Em sudoers +is that in LDAP, +.Nm sudo Ns No -specific +Aliases are not supported. +.Pp +For the most part, there is really no need for +.Nm sudo Ns No -specific +Aliases. +Unix groups or user netgroups can be used in place of User_Aliases and +Runas_Aliases. +Host netgroups can be used in place of Host_Aliases. +Since Unix groups and netgroups can also be stored in LDAP there is no +real need for +.Nm sudo Ns No -specific +aliases. +.Pp +Cmnd_Aliases are not really required either since it is possible +to have multiple users listed in a +.Li sudoRole . +Instead of defining a Cmnd_Alias that is referenced by multiple users, +one can create a +.Li sudoRole +that contains the commands and assign multiple users to it. +.Ss SUDOers LDAP container +The +.Em sudoers +configuration is contained in the +.Li ou=SUDOers +LDAP container. +.Pp +Sudo first looks for the +.Li cn=default +entry in the SUDOers container. +If found, the multi-valued +.Li sudoOption +attribute is parsed in the same manner as a global +.Li Defaults +line in +.Pa @sysconfdir@/sudoers . +In the following example, the +.Ev SSH_AUTH_SOCK +variable will be preserved in the environment for all users. +.Bd -literal -offset 4n +dn: cn=defaults,ou=SUDOers,dc=example,dc=com +objectClass: top +objectClass: sudoRole +cn: defaults +description: Default sudoOption's go here +sudoOption: env_keep+=SSH_AUTH_SOCK +.Ed +.Pp +The equivalent of a sudoer in LDAP is a +.Li sudoRole . +It consists of the following attributes: +.Bl -tag -width 4n +.It Sy sudoUser +A user name, user ID (prefixed with +.Ql # ) , +Unix group (prefixed with +.Ql % ) , +Unix group ID (prefixed with +.Ql %# ) , +or user netgroup (prefixed with +.Ql + ) . +.It Sy sudoHost +A host name, IP address, IP network, or host netgroup (prefixed with a +.Ql + ) . +The special value +.Li ALL +will match any host. +.It Sy sudoCommand +A Unix command with optional command line arguments, potentially +including globbing characters (aka wild cards). +The special value +.Li ALL +will match any command. +If a command is prefixed with an exclamation point +.Ql \&! , +the user will be prohibited from running that command. +.It Sy sudoOption +Identical in function to the global options described above, but +specific to the +.Li sudoRole +in which it resides. +.It Sy sudoRunAsUser +A user name or uid (prefixed with +.Ql # ) +that commands may be run as or a Unix group (prefixed with a +.Ql % ) +or user netgroup (prefixed with a +.Ql + ) +that contains a list of users that commands may be run as. +The special value +.Li ALL +will match any user. +.Pp +The +.Li sudoRunAsUser +attribute is only available in +.Nm sudo +versions +1.7.0 and higher. +Older versions of +.Nm sudo +use the +.Li sudoRunAs +attribute instead. +.It Sy sudoRunAsGroup +A Unix group or gid (prefixed with +.Ql # ) +that commands may be run as. +The special value +.Li ALL +will match any group. +.Pp +The +.Li sudoRunAsGroup +attribute is only available in +.Nm sudo +versions +1.7.0 and higher. +.It Sy sudoNotBefore +A timestamp in the form +.Li yyyymmddHHMMSSZ +that can be used to provide a start date/time for when the +.Li sudoRole +will be valid. +If multiple +.Li sudoNotBefore +entries are present, the earliest is used. +Note that timestamps must be in Coordinated Universal Time (UTC), +not the local timezone. +The minute and seconds portions are optional, but some LDAP servers +require that they be present (contrary to the RFC). +.Pp +The +.Li sudoNotBefore +attribute is only available in +.Nm sudo +versions 1.7.5 and higher and must be explicitly enabled via the +.Sy SUDOERS_TIMED +option in +.Pa @ldap_conf@ . +.It Sy sudoNotAfter +A timestamp in the form +.Li yyyymmddHHMMSSZ +that indicates an expiration date/time, after which the +.Li sudoRole +will no longer be valid. +If multiple +.Li sudoNotBefore +entries are present, the last one is used. +Note that timestamps must be in Coordinated Universal Time (UTC), +not the local timezone. +The minute and seconds portions are optional, but some LDAP servers +require that they be present (contrary to the RFC). +.Pp +The +.Li sudoNotAfter +attribute is only available in +.Nm sudo +versions +1.7.5 and higher and must be explicitly enabled via the +.Sy SUDOERS_TIMED +option in +.Pa @ldap_conf@ . +.It Sy sudoOrder +The +.Li sudoRole +entries retrieved from the LDAP directory have no inherent order. +The +.Li sudoOrder +attribute is an integer (or floating point value for LDAP servers +that support it) that is used to sort the matching entries. +This allows LDAP-based sudoers entries to more closely mimic the behaviour +of the sudoers file, where the of the entries influences the result. +If multiple entries match, the entry with the highest +.Li sudoOrder +attribute is chosen. +This corresponds to the +.Dq last match +behavior of the sudoers file. +If the +.Li sudoOrder +attribute is not present, a value of 0 is assumed. +.Pp +The +.Li sudoOrder +attribute is only available in +.Nm sudo +versions 1.7.5 and higher. +.El +.Pp +Each attribute listed above should contain a single value, but there +may be multiple instances of each attribute type. +A +.Li sudoRole +must contain at least one +.Li sudoUser , +.Li sudoHost +and +.Li sudoCommand . +.Pp +The following example allows users in group wheel to run any command +on any host via +.Nm sudo : +.Bd -literal -offset 4n +dn: cn=%wheel,ou=SUDOers,dc=example,dc=com +objectClass: top +objectClass: sudoRole +cn: %wheel +sudoUser: %wheel +sudoHost: ALL +sudoCommand: ALL +.Ed +.Ss Anatomy of LDAP sudoers lookup +When looking up a sudoer using LDAP there are only two or three +LDAP queries per invocation. +The first query is to parse the global options. +The second is to match against the user's name and the groups that +the user belongs to. +(The special +.Li ALL +tag is matched in this query too.) +If no match is returned for the user's name and groups, a third +query returns all entries containing user netgroups and checks +to see if the user belongs to any of them. +.Pp +If timed entries are enabled with the +.Sy SUDOERS_TIMED +configuration directive, the LDAP queries include a subfilter that +limits retrieval to entries that satisfy the time constraints, if any. +.Ss Differences between LDAP and non-LDAP sudoers +There are some subtle differences in the way sudoers is handled +once in LDAP. +Probably the biggest is that according to the RFC, LDAP ordering +is arbitrary and you cannot expect that Attributes and Entries are +returned in any specific order. +.Pp +The order in which different entries are applied can be controlled +using the +.Li sudoOrder +attribute, but there is no way to guarantee the order of attributes +within a specific entry. +If there are conflicting command rules in an entry, the negative +takes precedence. +This is called paranoid behavior (not necessarily the most specific +match). +.Pp +Here is an example: +.Bd -literal -offset 4n +# /etc/sudoers: +# Allow all commands except shell +johnny ALL=(root) ALL,!/bin/sh +# Always allows all commands because ALL is matched last +puddles ALL=(root) !/bin/sh,ALL + +# LDAP equivalent of johnny +# Allows all commands except shell +dn: cn=role1,ou=Sudoers,dc=my-domain,dc=com +objectClass: sudoRole +objectClass: top +cn: role1 +sudoUser: johnny +sudoHost: ALL +sudoCommand: ALL +sudoCommand: !/bin/sh + +# LDAP equivalent of puddles +# Notice that even though ALL comes last, it still behaves like +# role1 since the LDAP code assumes the more paranoid configuration +dn: cn=role2,ou=Sudoers,dc=my-domain,dc=com +objectClass: sudoRole +objectClass: top +cn: role2 +sudoUser: puddles +sudoHost: ALL +sudoCommand: !/bin/sh +sudoCommand: ALL +.Ed +.Pp +Another difference is that negations on the Host, User or Runas are +currently ignored. +For example, the following attributes do not behave the way one might expect. +.Bd -literal -offset 4n +# does not match all but joe +# rather, does not match anyone +sudoUser: !joe + +# does not match all but joe +# rather, matches everyone including Joe +sudoUser: ALL +sudoUser: !joe + +# does not match all but web01 +# rather, matches all hosts including web01 +sudoHost: ALL +sudoHost: !web01 +.Ed +.Ss Sudoers Schema +In order to use +.Nm sudo Ns No 's +LDAP support, the +.Nm sudo +schema must be +installed on your LDAP server. +In addition, be sure to index the +.Li sudoUser +attribute. +.Pp +Three versions of the schema: one for OpenLDAP servers +.Pq Pa schema.OpenLDAP , +one for Netscape-derived servers +.Pq Pa schema.iPlanet , +and one for Microsoft Active Directory +.Pq Pa schema.ActiveDirectory +may be found in the +.Nm sudo +distribution. +.Pp +The schema for +.Nm sudo +in OpenLDAP form is also included in the +.Sx EXAMPLES +section. +.Ss Configuring ldap.conf +Sudo reads the +.Pa @ldap_conf@ +file for LDAP-specific configuration. +Typically, this file is shared amongst different LDAP-aware clients. +As such, most of the settings are not +.Nm sudo Ns No -specific. +Note that +.Nm sudo +parses +.Pa @ldap_conf@ +itself and may support options that differ from those described in the +system's +.Xr ldap.conf 5 +manual. +.Pp +Also note that on systems using the OpenLDAP libraries, default +values specified in +.Pa /etc/openldap/ldap.conf +or the user's +.Pa .ldaprc +files are not used. +.Pp +Only those options explicitly listed in +.Pa @ldap_conf@ +as being supported by +.Nm sudo +are honored. +Configuration options are listed below in upper case but are parsed +in a case-independent manner. +.Bl -tag -width 4n +.It Sy URI Ar ldap[s]://[hostname[:port]] ... +Specifies a whitespace-delimited list of one or more URIs describing +the LDAP server(s) to connect to. +The +.Em protocol +may be either +.Em ldap +.Em ldaps , +the latter being for servers that support TLS (SSL) encryption. +If no +.Em port +is specified, the default is port 389 for +.Li ldap:// +or port 636 for +.Li ldaps:// . +If no +.Em hostname +is specified, +.Nm sudo +will connect to +.Em localhost . +Multiple +.Sy URI +lines are treated identically to a +.Sy URI +line containing multiple entries. +Only systems using the OpenSSL libraries support the mixing of +.Li ldap:// +and +.Li ldaps:// +URIs. +Both the Netscape-derived and Tivoli LDAP libraries used on most commercial +versions of Unix are only capable of supporting one or the other. +.It Sy HOST Ar name[:port] ... +If no +.Sy URI +is specified, the +.Sy HOST +parameter specifies a whitespace-delimited list of LDAP servers to connect to. +Each host may include an optional +.Em port +separated by a colon +.Pq Ql :\& . +The +.Sy HOST +parameter is deprecated in favor of the +.Sy URI +specification and is included for backwards compatibility. +.It Sy PORT Ar port_number +If no +.Sy URI +is specified, the +.Sy PORT +parameter specifies the default port to connect to on the LDAP server if a +.Sy HOST +parameter does not specify the port itself. +If no +.Sy PORT +parameter is used, the default is port 389 for LDAP and port 636 for LDAP +over TLS (SSL). +The +.Sy PORT +parameter is deprecated in favor of the +.Sy URI +specification and is included for backwards compatibility. +.It Sy BIND_TIMELIMIT Ar seconds +The +.Sy BIND_TIMELIMIT +parameter specifies the amount of time, in seconds, to wait while trying +to connect to an LDAP server. +If multiple +.Sy URI Ns No s +or +.Sy HOST Ns No s +are specified, this is the amount of time to wait before trying +the next one in the list. +.It Sy NETWORK_TIMEOUT Ar seconds +An alias for +.Sy BIND_TIMELIMIT +for OpenLDAP compatibility. +.It Sy TIMELIMIT Ar seconds +The +.Sy TIMELIMIT +parameter specifies the amount of time, in seconds, to wait for a +response to an LDAP query. +.It Sy TIMEOUT Ar seconds +The +.Sy TIMEOUT +parameter specifies the amount of time, in seconds, to wait for a +response from the various LDAP APIs. +.It Sy SUDOERS_BASE Ar base +The base DN to use when performing +.Nm sudo +LDAP queries. +Typically this is of the form +.Li ou=SUDOers,dc=example,dc=com +for the domain +.Li example.com . +Multiple +.Sy SUDOERS_BASE +lines may be specified, in which case they are queried in the order specified. +.It Sy SUDOERS_SEARCH_FILTER Ar ldap_filter +An LDAP filter which is used to restrict the set of records returned +when performing a +.Nm sudo +LDAP query. +Typically, this is of the +form +.Li attribute=value +or +.Li (&(attribute=value)(attribute2=value2)) . +.It Sy SUDOERS_TIMED Ar on/true/yes/off/false/no +Whether or not to evaluate the +.Li sudoNotBefore +and +.Li sudoNotAfter +attributes that implement time-dependent sudoers entries. +.It Sy SUDOERS_DEBUG Ar debug_level +This sets the debug level for +.Nm sudo +LDAP queries. +Debugging information is printed to the standard error. +A value of 1 results in a moderate amount of debugging information. +A value of 2 shows the results of the matches themselves. +This parameter should not be set in a production environment as the +extra information is likely to confuse users. +.It Sy BINDDN Ar DN +The +.Sy BINDDN +parameter specifies the identity, in the form of a Distinguished Name (DN), +to use when performing LDAP operations. +If not specified, LDAP operations are performed with an anonymous identity. +By default, most LDAP servers will allow anonymous access. +.It Sy BINDPW Ar secret +The +.Sy BINDPW +parameter specifies the password to use when performing LDAP operations. +This is typically used in conjunction with the +.Sy BINDDN +parameter. +.It Sy ROOTBINDDN Ar DN +The +.Sy ROOTBINDDN +parameter specifies the identity, in the form of a Distinguished Name (DN), +to use when performing privileged LDAP operations, such as +.Em sudoers +queries. +The password corresponding +to the identity should be stored in +.Pa @ldap_secret@ . +If not specified, the +.Sy BINDDN +identity is used (if any). +.It Sy LDAP_VERSION Ar number +The version of the LDAP protocol to use when connecting to the server. +The default value is protocol version 3. +.It Sy SSL Ar on/true/yes/off/false/no +If the +.Sy SSL +parameter is set to +.Li on , +.Li true +.Li or +.Li yes , +TLS (SSL) encryption is always used when communicating with the LDAP server. +Typically, this involves connecting to the server on port 636 (ldaps). +.It Sy SSL Ar start_tls +If the +.Sy SSL +parameter is set to +.Li start_tls , +the LDAP server connection is initiated normally and TLS encryption is +begun before the bind credentials are sent. +This has the advantage of not requiring a dedicated port for encrypted +communications. +This parameter is only supported by LDAP servers that honor the +.Em start_tls +extension, such as the OpenLDAP and Tivoli Directory servers. +.It Sy TLS_CHECKPEER Ar on/true/yes/off/false/no +If enabled, +.Sy TLS_CHECKPEER +will cause the LDAP server's TLS certificated to be verified. +If the server's TLS certificate cannot be verified (usually because it +is signed by an unknown certificate authority), +.Nm sudo +will be unable to connect to it. +If +.Sy TLS_CHECKPEER +is disabled, no check is made. +Note that disabling the check creates an opportunity for man-in-the-middle +attacks since the server's identity will not be authenticated. +If possible, the CA's certificate should be installed locally so it can +be verified. +This option is not supported by the Tivoli Directory Server LDAP libraries. +.It Sy TLS_CACERT Ar file name +An alias for +.Sy TLS_CACERTFILE +for OpenLDAP compatibility. +.It Sy TLS_CACERTFILE Ar file name +The path to a certificate authority bundle which contains the certificates +for all the Certificate Authorities the client knows to be valid, e.g.\& +.Pa /etc/ssl/ca-bundle.pem . +This option is only supported by the OpenLDAP libraries. +Netscape-derived LDAP libraries use the same certificate +database for CA and client certificates (see +.Sy TLS_CERT ) . +.It Sy TLS_CACERTDIR Ar directory +Similar to +.Sy TLS_CACERTFILE +but instead of a file, it is a directory containing individual +Certificate Authority certificates, e.g.\& +.Pa /etc/ssl/certs . +The directory specified by +.Sy TLS_CACERTDIR +is checked after +.Sy TLS_CACERTFILE . +This option is only supported by the OpenLDAP libraries. +.It Sy TLS_CERT Ar file name +The path to a file containing the client certificate which can +be used to authenticate the client to the LDAP server. +The certificate type depends on the LDAP libraries used. +.Bl -tag -width 4n +.It OpenLDAP: +.Li tls_cert /etc/ssl/client_cert.pem +.It Netscape-derived: +.Li tls_cert /var/ldap/cert7.db +.It Tivoli Directory Server: +Unused, the key database specified by +.Sy TLS_KEY +contains both keys and certificates. +.Pp +When using Netscape-derived libraries, this file may also contain +Certificate Authority certificates. +.El +.It Sy TLS_KEY Ar file name +The path to a file containing the private key which matches the +certificate specified by +.Sy TLS_CERT . +The private key must not be password-protected. +The key type depends on the LDAP libraries used. +.Bl -tag -width 4n +.It OpenLDAP: +.Li tls_key /etc/ssl/client_key.pem +.It Netscape-derived: +.Li tls_key /var/ldap/key3.db +.It Tivoli Directory Server: +.Li tls_cert /usr/ldap/ldapkey.kdb +.El +When using Tivoli LDAP libraries, this file may also contain +Certificate Authority and client certificates and may be encrypted. +.It Sy TLS_KEYPW Ar secret +The +.Sy TLS_KEYPW +contains the password used to decrypt the key database on clients +using the Tivoli Directory Server LDAP library. +If no +.Sy TLS_KEYPW +is specified, a +.Em stash file +will be used if it exists. +The +.Em stash file +must have the same path as the file specified by +.Sy TLS_KEY , +but use a +.Li .sth +file extension instead of +.Li .kdb , +e.g.\& +.Li ldapkey.sth . +The default +.Li ldapkey.kdb +that ships with Tivoli Directory Server is encrypted with the password +.Li ssl_password . +This option is only supported by the Tivoli LDAP libraries. +.It Sy TLS_RANDFILE Ar file name +The +.Sy TLS_RANDFILE +parameter specifies the path to an entropy source for systems that lack +a random device. +It is generally used in conjunction with +.Em prngd +or +.Em egd . +This option is only supported by the OpenLDAP libraries. +.It Sy TLS_CIPHERS Ar cipher list +The +.Sy TLS_CIPHERS +parameter allows the administer to restrict which encryption algorithms +may be used for TLS (SSL) connections. +See the OpenLDAP or Tivoli Directory Server manual for a list of valid +ciphers. +This option is not supported by Netscape-derived libraries. +.It Sy USE_SASL Ar on/true/yes/off/false/no +Enable +.Sy USE_SASL +for LDAP servers that support SASL authentication. +.It Sy SASL_AUTH_ID Ar identity +The SASL user name to use when connecting to the LDAP server. +By default, +.Nm sudo +will use an anonymous connection. +.It Sy ROOTUSE_SASL Ar on/true/yes/off/false/no +Enable +.Sy ROOTUSE_SASL +to enable SASL authentication when connecting +to an LDAP server from a privileged process, such as +.Nm sudo . +.It Sy ROOTSASL_AUTH_ID Ar identity +The SASL user name to use when +.Sy ROOTUSE_SASL +is enabled. +.It Sy SASL_SECPROPS Ar none/properties +SASL security properties or +.Em none +for no properties. +See the SASL programmer's manual for details. +.It Sy KRB5_CCNAME Ar file name +The path to the Kerberos 5 credential cache to use when authenticating +with the remote server. +.It Sy DEREF Ar never/searching/finding/always +How alias dereferencing is to be performed when searching. +See the +.Xr ldap.conf 5 +manual for a full description of this option. +.El +.Pp +See the +.Pa ldap.conf +entry in the +.Sx EXAMPLES +section. +.Ss Configuring nsswitch.conf +Unless it is disabled at build time, +.Nm sudo +consults the Name Service Switch file, +.Pa @nsswitch_conf@ , +to specify the +.Em sudoers +search order. +Sudo looks for a line beginning with +.Li sudoers : +and uses this to determine the search order. +Note that +.Nm sudo +does +not stop searching after the first match and later matches take +precedence over earlier ones. +The following sources are recognized: +.Pp +.Bl -tag -width 8n -offset 4n -compact +.It files +read sudoers from +.Pa @sysconfdir@/sudoers +.It ldap +read sudoers from LDAP +.El +.Pp +In addition, the entry +.Li [NOTFOUND=return] +will short-circuit the search if the user was not found in the +preceding source. +.Pp +To consult LDAP first followed by the local sudoers file (if it +exists), use: +.Bd -literal -offset 4n +sudoers: ldap files +.Ed +.Pp +The local +.Em sudoers +file can be ignored completely by using: +.Bd -literal -offset 4n +sudoers: ldap +.Ed +.Pp +If the +.Pa @nsswitch_conf@ +file is not present or there is no sudoers line, the following +default is assumed: +.Bd -literal -offset 4n +sudoers: files +.Ed +.Pp +Note that +.Pa @nsswitch_conf@ +is supported even when the underlying operating system does not use +an nsswitch.conf file, except on AIX (see below). +.Ss Configuring netsvc.conf +On AIX systems, the +.Pa @netsvc_conf@ +file is consulted instead of +.Pa @nsswitch_conf@ . +.Nm sudo +simply treats +.Pa netsvc.conf +as a variant of +.Pa nsswitch.conf ; +information in the previous section unrelated to the file format +itself still applies. +.Pp +To consult LDAP first followed by the local sudoers file (if it +exists), use: +.Bd -literal -offset 4n +sudoers = ldap, files +.Ed +.Pp +The local +.Em sudoers +file can be ignored completely by using: +.Bd -literal -offset 4n +sudoers = ldap +.Ed +.Pp +To treat LDAP as authoratative and only use the local sudoers file +if the user is not present in LDAP, use: +.Bd -literal -offset 4n +sudoers = ldap = auth, files +.Ed +.Pp +Note that in the above example, the +.Li auth +qualfier only affects user lookups; both LDAP and +.Em sudoers +will be queried for +.Li Defaults +entries. +.Pp +If the +.Pa @netsvc_conf@ +file is not present or there is no sudoers line, the following +default is assumed: +.Bd -literal -offset 4n +sudoers = files +.Ed +.Sh FILES +.Bl -tag -width 24n +.It Pa @ldap_conf@ +LDAP configuration file +.It Pa @nsswitch_conf@ +determines sudoers source order +.It Pa @netsvc_conf@ +determines sudoers source order on AIX +.El +.Sh EXAMPLES +.Ss Example ldap.conf +.Bd -literal -offset 2n +# Either specify one or more URIs or one or more host:port pairs. +# If neither is specified sudo will default to localhost, port 389. +# +#host ldapserver +#host ldapserver1 ldapserver2:390 +# +# Default port if host is specified without one, defaults to 389. +#port 389 +# +# URI will override the host and port settings. +uri ldap://ldapserver +#uri ldaps://secureldapserver +#uri ldaps://secureldapserver ldap://ldapserver +# +# The amount of time, in seconds, to wait while trying to connect to +# an LDAP server. +bind_timelimit 30 +# +# The amount of time, in seconds, to wait while performing an LDAP query. +timelimit 30 +# +# Must be set or sudo will ignore LDAP; may be specified multiple times. +sudoers_base ou=SUDOers,dc=example,dc=com +# +# verbose sudoers matching from ldap +#sudoers_debug 2 +# +# Enable support for time-based entries in sudoers. +#sudoers_timed yes +# +# optional proxy credentials +#binddn +#bindpw +#rootbinddn +# +# LDAP protocol version, defaults to 3 +#ldap_version 3 +# +# Define if you want to use an encrypted LDAP connection. +# Typically, you must also set the port to 636 (ldaps). +#ssl on +# +# Define if you want to use port 389 and switch to +# encryption before the bind credentials are sent. +# Only supported by LDAP servers that support the start_tls +# extension such as OpenLDAP. +#ssl start_tls +# +# Additional TLS options follow that allow tweaking of the +# SSL/TLS connection. +# +#tls_checkpeer yes # verify server SSL certificate +#tls_checkpeer no # ignore server SSL certificate +# +# If you enable tls_checkpeer, specify either tls_cacertfile +# or tls_cacertdir. Only supported when using OpenLDAP. +# +#tls_cacertfile /etc/certs/trusted_signers.pem +#tls_cacertdir /etc/certs +# +# For systems that don't have /dev/random +# use this along with PRNGD or EGD.pl to seed the +# random number pool to generate cryptographic session keys. +# Only supported when using OpenLDAP. +# +#tls_randfile /etc/egd-pool +# +# You may restrict which ciphers are used. Consult your SSL +# documentation for which options go here. +# Only supported when using OpenLDAP. +# +#tls_ciphers +# +# Sudo can provide a client certificate when communicating to +# the LDAP server. +# Tips: +# * Enable both lines at the same time. +# * Do not password protect the key file. +# * Ensure the keyfile is only readable by root. +# +# For OpenLDAP: +#tls_cert /etc/certs/client_cert.pem +#tls_key /etc/certs/client_key.pem +# +# For SunONE or iPlanet LDAP, tls_cert and tls_key may specify either +# a directory, in which case the files in the directory must have the +# default names (e.g. cert8.db and key4.db), or the path to the cert +# and key files themselves. However, a bug in version 5.0 of the LDAP +# SDK will prevent specific file names from working. For this reason +# it is suggested that tls_cert and tls_key be set to a directory, +# not a file name. +# +# The certificate database specified by tls_cert may contain CA certs +# and/or the client's cert. If the client's cert is included, tls_key +# should be specified as well. +# For backward compatibility, "sslpath" may be used in place of tls_cert. +#tls_cert /var/ldap +#tls_key /var/ldap +# +# If using SASL authentication for LDAP (OpenSSL) +# use_sasl yes +# sasl_auth_id +# rootuse_sasl yes +# rootsasl_auth_id +# sasl_secprops none +# krb5_ccname /etc/.ldapcache +.Ed +.Ss Sudo schema for OpenLDAP +The following schema, in OpenLDAP format, is included with +.Nm sudo +source and binary distributions as +.Pa schema.OpenLDAP . +Simply copy +it to the schema directory (e.g.\& +.Pa /etc/openldap/schema ) , +add the proper +.Li include +line in +.Pa slapd.conf +and restart +.Nm slapd . +.Bd -literal -offset 2n +attributetype ( 1.3.6.1.4.1.15953.9.1.1 + NAME 'sudoUser' + DESC 'User(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.2 + NAME 'sudoHost' + DESC 'Host(s) who may run sudo' + EQUALITY caseExactIA5Match + SUBSTR caseExactIA5SubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.3 + NAME 'sudoCommand' + DESC 'Command(s) to be executed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.4 + NAME 'sudoRunAs' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.5 + NAME 'sudoOption' + DESC 'Options(s) followed by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.6 + NAME 'sudoRunAsUser' + DESC 'User(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.7 + NAME 'sudoRunAsGroup' + DESC 'Group(s) impersonated by sudo' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.8 + NAME 'sudoNotBefore' + DESC 'Start of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + +attributetype ( 1.3.6.1.4.1.15953.9.1.9 + NAME 'sudoNotAfter' + DESC 'End of time interval for which the entry is valid' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + +attributeTypes ( 1.3.6.1.4.1.15953.9.1.10 + NAME 'sudoOrder' + DESC 'an integer to order the sudoRole entries' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) + +objectclass ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL + DESC 'Sudoer Entries' + MUST ( cn ) + MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $ + sudoRunAsGroup $ sudoOption $ sudoNotBefore $ sudoNotAfter $ + sudoOrder $ description ) + ) +.Ed +.Sh SEE ALSO +.Xr ldap.conf 5 , +.Xr sudoers 5 +.Sh CAVEATS +Note that there are differences in the way that LDAP-based +.Em sudoers +is parsed compared to file-based +.Em sudoers . +See the +.Sx Differences between LDAP and non-LDAP sudoers +section for more information. +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at http://www.sudo.ws/sudo/bugs/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or http://www.sudo.ws/sudo/license.html for complete details. diff --git a/doc/sudoers.mdoc.in b/doc/sudoers.mdoc.in new file mode 100644 index 000000000..72425dc92 --- /dev/null +++ b/doc/sudoers.mdoc.in @@ -0,0 +1,3501 @@ +.\" +.\" Copyright (c) 1994-1996, 1998-2005, 2007-2012 +.\" Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.Dd July 16, 2012 +.Dt SUDOERS 5 +.Os +.Sh NAME +.Nm sudoers +.Nd default sudo security policy module +.Sh DESCRIPTION +The +.Em sudoers +policy module determines a user's +.Nm sudo +privileges. +It is the default +.Nm sudo +policy plugin. +The policy is driven by +the +.Pa @sysconfdir@/sudoers +file or, optionally in LDAP. +The policy format is described in detail in the +.Sx SUDOERS FILE FORMAT +section. +For information on storing +.Em sudoers +policy information +in LDAP, please see +.Xr sudoers.ldap 5 . +.Ss Authentication and Logging +The +.Em sudoers +security policy requires that most users authenticate +themselves before they can use +.Nm sudo . +A password is not required +if the invoking user is root, if the target user is the same as the +invoking user, or if the policy has disabled authentication for the +user or command. +Unlike +.Xr su 1 , +when +.Em sudoers +requires +authentication, it validates the invoking user's credentials, not +the target user's (or root's) credentials. +This can be changed via +the +.Em rootpw , +.Em targetpw +and +.Em runaspw +flags, described later. +.Pp +If a user who is not listed in the policy tries to run a command +via +.Nm sudo , +mail is sent to the proper authorities. +The address +used for such mail is configurable via the +.Em mailto +Defaults entry +(described later) and defaults to +.Li @mailto@ . +.Pp +Note that mail will not be sent if an unauthorized user tries to +run +.Nm sudo +with the +.Fl l +or +.Fl v +option. +This allows users to +determine for themselves whether or not they are allowed to use +.Nm sudo . +.Pp +If +.Nm sudo +is run by root and the +.Ev SUDO_USER +environment variable +is set, the +.Em sudoers +policy will use this value to determine who +the actual user is. +This can be used by a user to log commands +through sudo even when a root shell has been invoked. +It also +allows the +.Fl e +option to remain useful even when invoked via a +sudo-run script or program. +Note, however, that the +.Em sudoers +lookup is still done for root, not the user specified by +.Ev SUDO_USER . +.Pp +.Em sudoers +uses time stamp files for credential caching. +Once a +user has been authenticated, the time stamp is updated and the user +may then use sudo without a password for a short period of time +.Po +.Li @timeout@ +minutes unless overridden by the +.Em timeout +option +.Pc . +By default, +.Em sudoers +uses a tty-based time stamp which means that +there is a separate time stamp for each of a user's login sessions. +The +.Em tty_tickets +option can be disabled to force the use of a +single time stamp for all of a user's sessions. +.Pp +.Em sudoers +can log both successful and unsuccessful attempts (as well +as errors) to +.Xr syslog 3 , +a log file, or both. +By default, +.Em sudoers +will log via +.Xr syslog 3 +but this is changeable via the +.Em syslog +and +.Em logfile +Defaults settings. +.Pp +.Em sudoers +also supports logging a command's input and output +streams. +I/O logging is not on by default but can be enabled using +the +.Em log_input +and +.Em log_output +Defaults flags as well as the +.Li LOG_INPUT +and +.Li LOG_OUTPUT +command tags. +.Ss Command Environment +Since environment variables can influence program behavior, +.Em sudoers +provides a means to restrict which variables from the user's +environment are inherited by the command to be run. +There are two +distinct ways +.Em sudoers +can deal with environment variables. +.Pp +By default, the +.Em env_reset +option is enabled. +This causes commands +to be executed with a new, minimal environment. +On AIX (and Linux +systems without PAM), the environment is initialized with the +contents of the +.Pa /etc/environment +file. +On BSD systems, if the +.Em use_loginclass +option is enabled, the environment is initialized +based on the +.Em path +and +.Em setenv +settings in +.Pa /etc/login.conf . +The new environment contains the +.Ev TERM , +.Ev PATH , +.Ev HOME , +.Ev MAIL , +.Ev SHELL , +.Ev LOGNAME , +.Ev USER , +.Ev USERNAME +and +.Ev SUDO_* +variables +in addition to variables from the invoking process permitted by the +.Em env_check +and +.Em env_keep +options. +This is effectively a whitelist +for environment variables. +.Pp +If, however, the +.Em env_reset +option is disabled, any variables not +explicitly denied by the +.Em env_check +and +.Em env_delete +options are +inherited from the invoking process. +In this case, +.Em env_check +and +.Em env_delete +behave like a blacklist. +Since it is not possible +to blacklist all potentially dangerous environment variables, use +of the default +.Em env_reset +behavior is encouraged. +.Pp +In all cases, environment variables with a value beginning with +.Li () +are removed as they could be interpreted as +.Sy bash +functions. +The list of environment variables that +.Nm sudo +allows or denies is +contained in the output of +.Dq Li sudo -V +when run as root. +.Pp +Note that the dynamic linker on most operating systems will remove +variables that can control dynamic linking from the environment of +setuid executables, including +.Nm sudo . +Depending on the operating +system this may include +.Ev _RLD* , +.Ev DYLD_* , +.Ev LD_* , +.Ev LDR_* , +.Ev LIBPATH , +.Ev SHLIB_PATH , +and others. +These type of variables are +removed from the environment before +.Nm sudo +even begins execution +and, as such, it is not possible for +.Nm sudo +to preserve them. +.Pp +As a special case, if +.Nm sudo Ns No 's +.Fl i +option (initial login) is +specified, +.Em sudoers +will initialize the environment regardless +of the value of +.Em env_reset . +The +.Ev DISPLAY , +.Ev PATH +and +.Ev TERM +variables remain unchanged; +.Ev HOME , +.Ev MAIL , +.Ev SHELL , +.Ev USER , +and +.Ev LOGNAME +are set based on the target user. +On AIX (and Linux +systems without PAM), the contents of +.Pa /etc/environment +are also +included. +On BSD systems, if the +.Em use_loginclass +option is +enabled, the +.Em path +and +.Em setenv +variables in +.Pa /etc/login.conf +are also applied. +All other environment variables are removed. +.Pp +Finally, if the +.Em env_file +option is defined, any variables present +in that file will be set to their specified values as long as they +would not conflict with an existing environment variable. +.Sh SUDOERS FILE FORMAT +The +.Em sudoers +file is composed of two types of entries: aliases +(basically variables) and user specifications (which specify who +may run what). +.Pp +When multiple entries match for a user, they are applied in order. +Where there are multiple matches, the last match is used (which is +not necessarily the most specific match). +.Pp +The +.Em sudoers +grammar will be described below in Extended Backus-Naur +Form (EBNF). +Don't despair if you are unfamiliar with EBNF; it is fairly simple, +and the definitions below are annotated. +.Ss Quick guide to EBNF +EBNF is a concise and exact way of describing the grammar of a language. +Each EBNF definition is made up of +.Em production rules . +E.g., +.Pp +.Li symbol ::= definition | alternate1 | alternate2 ... +.Pp +Each +.Em production rule +references others and thus makes up a +grammar for the language. +EBNF also contains the following +operators, which many readers will recognize from regular +expressions. +Do not, however, confuse them with +.Dq wildcard +characters, which have different meanings. +.Bl -tag -width 4n +.It Li \&? +Means that the preceding symbol (or group of symbols) is optional. +That is, it may appear once or not at all. +.It Li * +Means that the preceding symbol (or group of symbols) may appear +zero or more times. +.It Li + +Means that the preceding symbol (or group of symbols) may appear +one or more times. +.El +.Pp +Parentheses may be used to group symbols together. +For clarity, +we will use single quotes +.Pq '' +to designate what is a verbatim character string (as opposed to a symbol name). +.Ss Aliases +There are four kinds of aliases: +.Li User_Alias , +.Li Runas_Alias , +.Li Host_Alias +and +.Li Cmnd_Alias . +.Bd -literal +Alias ::= 'User_Alias' User_Alias (':' User_Alias)* | + 'Runas_Alias' Runas_Alias (':' Runas_Alias)* | + 'Host_Alias' Host_Alias (':' Host_Alias)* | + 'Cmnd_Alias' Cmnd_Alias (':' Cmnd_Alias)* + +User_Alias ::= NAME '=' User_List + +Runas_Alias ::= NAME '=' Runas_List + +Host_Alias ::= NAME '=' Host_List + +Cmnd_Alias ::= NAME '=' Cmnd_List + +NAME ::= [A-Z]([A-Z][0-9]_)* +.Ed +.Pp +Each +.Em alias +definition is of the form +.Bd -literal +Alias_Type NAME = item1, item2, ... +.Ed +.Pp +where +.Em Alias_Type +is one of +.Li User_Alias , +.Li Runas_Alias , +.Li Host_Alias , +or +.Li Cmnd_Alias . +A +.Li NAME +is a string of uppercase letters, numbers, +and underscore characters +.Pq Ql _ . +A +.Li NAME +.Sy must +start with an +uppercase letter. +It is possible to put several alias definitions +of the same type on a single line, joined by a colon +.Pq Ql :\& . +E.g., +.Bd -literal +Alias_Type NAME = item1, item2, item3 : NAME = item4, item5 +.Ed +.Pp +The definitions of what constitutes a valid +.Em alias +member follow. +.Bd -literal +User_List ::= User | + User ',' User_List + +User ::= '!'* user name | + '!'* #uid | + '!'* %group | + '!'* %#gid | + '!'* +netgroup | + '!'* %:nonunix_group | + '!'* %:#nonunix_gid | + '!'* User_Alias +.Ed +.Pp +A +.Li User_List +is made up of one or more user names, user ids +(prefixed with +.Ql # ) , +system group names and ids (prefixed with +.Ql % +and +.Ql %# +respectively), netgroups (prefixed with +.Ql + ) , +non-Unix group names and IDs (prefixed with +.Ql %: +and +.Ql %:# +respectively) and +.Li User_Alias Ns No es. +Each list item may be prefixed with zero or more +.Ql \&! +operators. +An odd number of +.Ql \&! +operators negate the value of +the item; an even number just cancel each other out. +.Pp +A +.Li user name , +.Li uid , +.Li group , +.Li gid , +.Li netgroup , +.Li nonunix_group +or +.Li nonunix_gid +may be enclosed in double quotes to avoid the +need for escaping special characters. +Alternately, special characters +may be specified in escaped hex mode, e.g.\& \ex20 for space. +When +using double quotes, any prefix characters must be included inside +the quotes. +.Pp +The actual +.Li nonunix_group +and +.Li nonunix_gid +syntax depends on +the underlying group provider plugin (see the +.Em group_plugin +description below). +For instance, the QAS AD plugin supports the following formats: +.Bl -bullet -width 4n +.It +Group in the same domain: "%:Group Name" +.It +Group in any domain: "%:Group Name@FULLY.QUALIFIED.DOMAIN" +.It +Group SID: "%:S-1-2-34-5678901234-5678901234-5678901234-567" +.El +.Pp +Note that quotes around group names are optional. +Unquoted strings must use a backslash +.Pq Ql \e +to escape spaces and special characters. +See +.Sx Other special characters and reserved words +for a list of +characters that need to be escaped. +.Bd -literal +Runas_List ::= Runas_Member | + Runas_Member ',' Runas_List + +Runas_Member ::= '!'* user name | + '!'* #uid | + '!'* %group | + '!'* %#gid | + '!'* %:nonunix_group | + '!'* %:#nonunix_gid | + '!'* +netgroup | + '!'* Runas_Alias +.Ed +.Pp +A +.Li Runas_List +is similar to a +.Li User_List +except that instead +of +.Li User_Alias Ns No es +it can contain +.Li Runas_Alias Ns No es . +Note that +user names and groups are matched as strings. +In other words, two +users (groups) with the same uid (gid) are considered to be distinct. +If you wish to match all user names with the same uid (e.g.\& +root and toor), you can use a uid instead (#0 in the example given). +.Bd -literal +Host_List ::= Host | + Host ',' Host_List + +Host ::= '!'* host name | + '!'* ip_addr | + '!'* network(/netmask)? | + '!'* +netgroup | + '!'* Host_Alias +.Ed +.Pp +A +.Li Host_List +is made up of one or more host names, IP addresses, +network numbers, netgroups (prefixed with +.Ql + ) +and other aliases. +Again, the value of an item may be negated with the +.Ql \&! +operator. +If you do not specify a netmask along with the network number, +.Nm sudo +will query each of the local host's network interfaces and, +if the network number corresponds to one of the hosts's network +interfaces, the corresponding netmask will be used. +The netmask +may be specified either in standard IP address notation +(e.g.\& 255.255.255.0 or ffff:ffff:ffff:ffff::), +or CIDR notation (number of bits, e.g.\& 24 or 64). +A host name may include shell-style wildcards (see the +.Sx Wildcards +section below), +but unless the +.Li host name +command on your machine returns the fully +qualified host name, you'll need to use the +.Em fqdn +option for wildcards to be useful. +Note that +.Nm sudo +only inspects actual network interfaces; this means that IP address +127.0.0.1 (localhost) will never match. +Also, the host name +.Dq localhost +will only match if that is the actual host name, which is usually +only the case for non-networked systems. +.Bd -literal +Cmnd_List ::= Cmnd | + Cmnd ',' Cmnd_List + +command name ::= file name | + file name args | + file name '""' + +Cmnd ::= '!'* command name | + '!'* directory | + '!'* "sudoedit" | + '!'* Cmnd_Alias +.Ed +.Pp +A +.Li Cmnd_List +is a list of one or more command names, directories, and other aliases. +A command name is a fully qualified file name which may include +shell-style wildcards (see the +.Sx Wildcards +section below). +A simple file name allows the user to run the command with any +arguments he/she wishes. +However, you may also specify command line arguments (including +wildcards). +Alternately, you can specify +.Li \&"" +to indicate that the command +may only be run +.Sy without +command line arguments. +A directory is a +fully qualified path name ending in a +.Ql / . +When you specify a directory in a +.Li Cmnd_List , +the user will be able to run any file within that directory +(but not in any subdirectories therein). +.Pp +If a +.Li Cmnd +has associated command line arguments, then the arguments +in the +.Li Cmnd +must match exactly those given by the user on the command line +(or match the wildcards if there are any). +Note that the following characters must be escaped with a +.Ql \e +if they are used in command arguments: +.Ql ,\& , +.Ql :\& , +.Ql =\& , +.Ql \e . +The special command +.Dq Li sudoedit +is used to permit a user to run +.Nm sudo +with the +.Fl e +option (or as +.Nm sudoedit ) . +It may take command line arguments just as a normal command does. +.Ss Defaults +Certain configuration options may be changed from their default +values at runtime via one or more +.Li Default_Entry +lines. +These may affect all users on any host, all users on a specific host, a +specific user, a specific command, or commands being run as a specific user. +Note that per-command entries may not include command line arguments. +If you need to specify arguments, define a +.Li Cmnd_Alias +and reference +that instead. +.Bd -literal +Default_Type ::= 'Defaults' | + 'Defaults' '@' Host_List | + 'Defaults' ':' User_List | + 'Defaults' '!' Cmnd_List | + 'Defaults' '>' Runas_List + +Default_Entry ::= Default_Type Parameter_List + +Parameter_List ::= Parameter | + Parameter ',' Parameter_List + +Parameter ::= Parameter '=' Value | + Parameter '+=' Value | + Parameter '-=' Value | + '!'* Parameter +.Ed +.Pp +Parameters may be +.Sy flags , +.Sy integer +values, +.Sy strings , +or +.Sy lists . +Flags are implicitly boolean and can be turned off via the +.Ql \&! +operator. +Some integer, string and list parameters may also be +used in a boolean context to disable them. +Values may be enclosed +in double quotes +.Pq \&"" +when they contain multiple words. +Special characters may be escaped with a backslash +.Pq Ql \e . +.Pp +Lists have two additional assignment operators, +.Li += +and +.Li -= . +These operators are used to add to and delete from a list respectively. +It is not an error to use the +.Li -= +operator to remove an element +that does not exist in a list. +.Pp +Defaults entries are parsed in the following order: generic, host +and user Defaults first, then runas Defaults and finally command +defaults. +.Pp +See +.Sx SUDOERS OPTIONS +for a list of supported Defaults parameters. +.Ss User Specification +.Bd -literal +User_Spec ::= User_List Host_List '=' Cmnd_Spec_List \e + (':' Host_List '=' Cmnd_Spec_List)* + +Cmnd_Spec_List ::= Cmnd_Spec | + Cmnd_Spec ',' Cmnd_Spec_List + +Cmnd_Spec ::= Runas_Spec? SELinux_Spec? Tag_Spec* Cmnd + +Runas_Spec ::= '(' Runas_List? (':' Runas_List)? ')' + +SELinux_Spec ::= ('ROLE=role' | 'TYPE=type') + +Tag_Spec ::= ('NOPASSWD:' | 'PASSWD:' | 'NOEXEC:' | 'EXEC:' | + 'SETENV:' | 'NOSETENV:' | 'LOG_INPUT:' | 'NOLOG_INPUT:' | + 'LOG_OUTPUT:' | 'NOLOG_OUTPUT:') +.Ed +.Pp +A +.Sy user specification +determines which commands a user may run +(and as what user) on specified hosts. +By default, commands are +run as +.Sy root , +but this can be changed on a per-command basis. +.Pp +The basic structure of a user specification is +.Dq who where = (as_whom) what . +Let's break that down into its constituent parts: +.Ss Runas_Spec +A +.Li Runas_Spec +determines the user and/or the group that a command +may be run as. +A fully-specified +.Li Runas_Spec +consists of two +.Li Runas_List Ns No s +(as defined above) separated by a colon +.Pq Ql :\& +and enclosed in a set of parentheses. +The first +.Li Runas_List +indicates +which users the command may be run as via +.Nm sudo Ns No 's +.Fl u +option. +The second defines a list of groups that can be specified via +.Nm sudo Ns No 's +.Fl g +option. +If both +.Li Runas_List Ns No s +are specified, the command may be run with any combination of users +and groups listed in their respective +.Li Runas_List Ns No s. +If only the first is specified, the command may be run as any user +in the list but no +.Fl g +option +may be specified. +If the first +.Li Runas_List +is empty but the +second is specified, the command may be run as the invoking user +with the group set to any listed in the +.Li Runas_List . +If no +.Li Runas_Spec +is specified the command may be run as +.Sy root +and +no group may be specified. +.Pp +A +.Li Runas_Spec +sets the default for the commands that follow it. +What this means is that for the entry: +.Bd -literal +dgb boulder = (operator) /bin/ls, /bin/kill, /usr/bin/lprm +.Ed +.Pp +The user +.Sy dgb +may run +.Pa /bin/ls , +.Pa /bin/kill , +and +.Pa /usr/bin/lprm Ns No \(em Ns but +only as +.Sy operator . +E.g., +.Bd -literal +$ sudo -u operator /bin/ls +.Ed +.Pp +It is also possible to override a +.Li Runas_Spec +later on in an entry. +If we modify the entry like so: +.Bd -literal +dgb boulder = (operator) /bin/ls, (root) /bin/kill, /usr/bin/lprm +.Ed +.Pp +Then user +.Sy dgb +is now allowed to run +.Pa /bin/ls +as +.Sy operator , +but +.Pa /bin/kill +and +.Pa /usr/bin/lprm +as +.Sy root . +.Pp +We can extend this to allow +.Sy dgb +to run +.Li /bin/ls +with either +the user or group set to +.Sy operator : +.Bd -literal +dgb boulder = (operator : operator) /bin/ls, (root) /bin/kill,\e + /usr/bin/lprm +.Ed +.Pp +Note that while the group portion of the +.Li Runas_Spec +permits the +user to run as command with that group, it does not force the user +to do so. +If no group is specified on the command line, the command +will run with the group listed in the target user's password database +entry. +The following would all be permitted by the sudoers entry above: +.Bd -literal +$ sudo -u operator /bin/ls +$ sudo -u operator -g operator /bin/ls +$ sudo -g operator /bin/ls +.Ed +.Pp +In the following example, user +.Sy tcm +may run commands that access +a modem device file with the dialer group. +.Bd -literal +tcm boulder = (:dialer) /usr/bin/tip, /usr/bin/cu,\e + /usr/local/bin/minicom +.Ed +.Pp +Note that in this example only the group will be set, the command +still runs as user +.Sy tcm . +E.g.\& +.Bd -literal +$ sudo -g dialer /usr/bin/cu +.Ed +.Pp +Multiple users and groups may be present in a +.Li Runas_Spec , +in which case the user may select any combination of users and groups via the +.Fl u +and +.Fl g +options. +In this example: +.Bd -literal +alan ALL = (root, bin : operator, system) ALL +.Ed +.Pp +user +.Sy alan +may run any command as either user root or bin, +optionally setting the group to operator or system. +.Ss SELinux_Spec +On systems with SELinux support, +.Em sudoers +entries may optionally have an SELinux role and/or type associated +with a command. +If a role or +type is specified with the command it will override any default values +specified in +.Em sudoers . +A role or type specified on the command line, +however, will supercede the values in +.Em sudoers . +.Ss Tag_Spec +A command may have zero or more tags associated with it. +There are +ten possible tag values: +.Li NOPASSWD , +.Li PASSWD , +.Li NOEXEC , +.Li EXEC , +.Li SETENV , +.Li NOSETENV , +.Li LOG_INPUT , +.Li NOLOG_INPUT , +.Li LOG_OUTPUT +and +.Li NOLOG_OUTPUT . +Once a tag is set on a +.Li Cmnd , +subsequent +.Li Cmnd Ns No s +in the +.Li Cmnd_Spec_List , +inherit the tag unless it is overridden by the opposite tag (in other words, +.Li PASSWD +overrides +.Li NOPASSWD +and +.Li NOEXEC +overrides +.Li EXEC ) . +.Pp +.Em NOPASSWD and PASSWD +.Pp +By default, +.Nm sudo +requires that a user authenticate him or herself +before running a command. +This behavior can be modified via the +.Li NOPASSWD +tag. +Like a +.Li Runas_Spec , +the +.Li NOPASSWD +tag sets +a default for the commands that follow it in the +.Li Cmnd_Spec_List . +Conversely, the +.Li PASSWD +tag can be used to reverse things. +For example: +.Bd -literal +ray rushmore = NOPASSWD: /bin/kill, /bin/ls, /usr/bin/lprm +.Ed +.Pp +would allow the user +.Sy ray +to run +.Pa /bin/kill , +.Pa /bin/ls , +and +.Pa /usr/bin/lprm +as +.Sy root +on the machine rushmore without authenticating himself. +If we only want +.Sy ray +to be able to +run +.Pa /bin/kill +without a password the entry would be: +.Bd -literal +ray rushmore = NOPASSWD: /bin/kill, PASSWD: /bin/ls, /usr/bin/lprm +.Ed +.Pp +Note, however, that the +.Li PASSWD +tag has no effect on users who are in the group specified by the +.Em exempt_group +option. +.Pp +By default, if the +.Li NOPASSWD +tag is applied to any of the entries for a user on the current host, +he or she will be able to run +.Dq Li sudo -l +without a password. +Additionally, a user may only run +.Dq Li sudo -v +without a password if the +.Li NOPASSWD +tag is present for all a user's entries that pertain to the current host. +This behavior may be overridden via the verifypw and listpw options. +.Pp +.Em NOEXEC and EXEC +.Pp +If +.Nm sudo +has been compiled with +.Em noexec +support and the underlying operating system supports it, the +.Li NOEXEC +tag can be used to prevent a dynamically-linked executable from +running further commands itself. +.Pp +In the following example, user +.Sy aaron +may run +.Pa /usr/bin/more +and +.Pa /usr/bin/vi +but shell escapes will be disabled. +.Bd -literal +aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi +.Ed +.Pp +See the +.Sx Preventing Shell Escapes +section below for more details on how +.Li NOEXEC +works and whether or not it will work on your system. +.Pp +.Em SETENV and NOSETENV +.Pp +These tags override the value of the +.Em setenv +option on a per-command basis. +Note that if +.Li SETENV +has been set for a command, the user may disable the +.Em env_reset +option from the command line via the +.Fl E +option. +Additionally, environment variables set on the command +line are not subject to the restrictions imposed by +.Em env_check , +.Em env_delete , +or +.Em env_keep . +As such, only trusted users should be allowed to set variables in this manner. +If the command matched is +.Sy ALL , +the +.Li SETENV +tag is implied for that command; this default may be overridden by use of the +.Li NOSETENV +tag. +.Pp +.Em LOG_INPUT and NOLOG_INPUT +.Pp +These tags override the value of the +.Em log_input +option on a per-command basis. +For more information, see the description of +.Em log_input +in the +.Sx SUDOERS OPTIONS +section below. +.Pp +.Em LOG_OUTPUT and NOLOG_OUTPUT +.Pp +These tags override the value of the +.Em log_output +option on a per-command basis. +For more information, see the description of +.Em log_output +in the +.Sx SUDOERS OPTIONS +section below. +.Ss Wildcards +.Nm sudo +allows shell-style +.Em wildcards +(aka meta or glob characters) +to be used in host names, path names and command line arguments in the +.Em sudoers +file. +Wildcard matching is done via the +.Sy POSIX +.Xr glob 3 +and +.Xr fnmatch 3 +routines. +Note that these are +.Em not +regular expressions. +.Bl -tag -width 8n +.It Li * +Matches any set of zero or more characters. +.It Li \? +Matches any single character. +.It Li [...] +Matches any character in the specified range. +.It Li [!...] +Matches any character +.Sy not +in the specified range. +.It Li \ex +For any character +.Sq x , +evaluates to +.Sq x . +This is used to escape special characters such as: +.Ql * , +.Ql \? , +.Ql [\& , +and +.Ql ]\& . +.El +.Pp +POSIX character classes may also be used if your system's +.Xr glob 3 +and +.Xr fnmatch 3 +functions support them. +However, because the +.Ql :\& +character has special meaning in +.Em sudoers , +it must be +escaped. +For example: +.Bd -literal -offset 4n +/bin/ls [[\:alpha\:]]* +.Ed +.Pp +Would match any file name beginning with a letter. +.Pp +Note that a forward slash +.Pq Ql / +will +.Sy not +be matched by +wildcards used in the path name. +When matching the command line arguments, however, a slash +.Sy does +get matched by +wildcards. +This is to make a path like: +.Bd -literal -offset 4n +/usr/bin/* +.Ed +.Pp +match +.Pa /usr/bin/who +but not +.Pa /usr/bin/X11/xterm . +.Ss Exceptions to wildcard rules +The following exceptions apply to the above rules: +.Bl -tag -width 4n +.It Li \&"" +If the empty string +.Li \&"" +is the only command line argument in the +.Em sudoers +entry it means that command is not allowed to be run with +.Sy any +arguments. +.El +.Ss Including other files from within sudoers +It is possible to include other +.Em sudoers +files from within the +.Em sudoers +file currently being parsed using the +.Li #include +and +.Li #includedir +directives. +.Pp +This can be used, for example, to keep a site-wide +.Em sudoers +file in addition to a local, per-machine file. +For the sake of this example the site-wide +.Em sudoers +will be +.Pa /etc/sudoers +and the per-machine one will be +.Pa /etc/sudoers.local . +To include +.Pa /etc/sudoers.local +from within +.Pa /etc/sudoers +we would use the +following line in +.Pa /etc/sudoers : +.Bd -literal -offset 4n +#include /etc/sudoers.local +.Ed +.Pp +When +.Nm sudo +reaches this line it will suspend processing of the current file +.Pq Pa /etc/sudoers +and switch to +.Pa /etc/sudoers.local . +Upon reaching the end of +.Pa /etc/sudoers.local , +the rest of +.Pa /etc/sudoers +will be processed. +Files that are included may themselves include other files. +A hard limit of 128 nested include files is enforced to prevent include +file loops. +.Pp +If the path to the include file is not fully-qualified (does not +begin with a +.Ql / , +it must be located in the same directory as the sudoers file it was +included from. +For example, if +.Pa /etc/sudoers +contains the line: +.Bd -literal -offset 4n +.Li #include sudoers.local +.Ed +.Pp +the file that will be included is +.Pa /etc/sudoers.local . +.Pp +The file name may also include the +.Li %h +escape, signifying the short form of the host name. +In other words, if the machine's host name is +.Dq xerxes , +then +.Bd -literal -offset 4n +#include /etc/sudoers.%h +.Ed +.Pp +will cause +.Nm sudo +to include the file +.Pa /etc/sudoers.xerxes . +.Pp +The +.Li #includedir +directive can be used to create a +.Pa sudo.d +directory that the system package manager can drop +.Em sudoers +rules +into as part of package installation. +For example, given: +.Bd -literal -offset 4n +#includedir /etc/sudoers.d +.Ed +.Pp +.Nm sudo +will read each file in +.Pa /etc/sudoers.d , +skipping file names that end in +.Ql ~ +or contain a +.Ql .\& +character to avoid causing problems with package manager or editor +temporary/backup files. +Files are parsed in sorted lexical order. +That is, +.Pa /etc/sudoers.d/01_first +will be parsed before +.Pa /etc/sudoers.d/10_second . +Be aware that because the sorting is lexical, not numeric, +.Pa /etc/sudoers.d/1_whoops +would be loaded +.Sy after +.Pa /etc/sudoers.d/10_second . +Using a consistent number of leading zeroes in the file names can be used +to avoid such problems. +.Pp +Note that unlike files included via +.Li #include , +.Nm visudo +will not edit the files in a +.Li #includedir +directory unless one of them contains a syntax error. +It is still possible to run +.Nm visudo +with the +.Fl f +flag to edit the files directly. +.Ss Other special characters and reserved words +The pound sign +.Pq Ql # +is used to indicate a comment (unless it is part of a #include +directive or unless it occurs in the context of a user name and is +followed by one or more digits, in which case it is treated as a +uid). +Both the comment character and any text after it, up to the end of +the line, are ignored. +.Pp +The reserved word +.Sy ALL +is a built-in +.Em alias +that always causes a match to succeed. +It can be used wherever one might otherwise use a +.Li Cmnd_Alias , +.Li User_Alias , +.Li Runas_Alias , +or +.Li Host_Alias . +You should not try to define your own +.Em alias +called +.Sy ALL +as the built-in alias will be used in preference to your own. +Please note that using +.Sy ALL +can be dangerous since in a command context, it allows the user to run +.Sy any +command on the system. +.Pp +An exclamation point +.Pq Ql \&! +can be used as a logical +.Em not +operator both in an +.Em alias +and in front of a +.Li Cmnd . +This allows one to exclude certain values. +Note, however, that using a +.Ql \&! +in conjunction with the built-in +.Sy ALL +alias to allow a user to run +.Dq all but a few +commands rarely works as intended (see +.Sx SECURITY NOTES +below). +.Pp +Long lines can be continued with a backslash +.Pq Ql \e +as the last character on the line. +.Pp +Whitespace between elements in a list as well as special syntactic +characters in a +.Em User Specification +.Po +.Ql =\& , +.Ql :\& , +.Ql (\& , +.Ql )\& +.Pc +is optional. +.Pp +The following characters must be escaped with a backslash +.Pq Ql \e +when used as part of a word (e.g.\& a user name or host name): +.Ql \&! , +.Ql =\& , +.Ql :\& , +.Ql ,\& , +.Ql (\& , +.Ql )\& , +.Ql \e . +.Sh SUDOERS OPTIONS +.Nm sudo Ns No 's +behavior can be modified by +.Li Default_Entry +lines, as explained earlier. +A list of all supported Defaults parameters, grouped by type, are listed below. +.Pp +.Sy Boolean Flags : +.Bl -tag -width 16n +.It always_set_home +If enabled, +.Nm sudo +will set the +.Ev HOME +environment variable to the home directory of the target user +(which is root unless the +.Fl u +option is used). +This effectively means that the +.Fl H +option is always implied. +Note that +.Ev HOME +is already set when the the +.Em env_reset +option is enabled, so +.Em always_set_home +is only effective for configurations where either +.Em env_reset +is disabled or +.Ev HOME +is present in the +.Em env_keep +list. +This flag is +.Em off +by default. +.It authenticate +If set, users must authenticate themselves via a password (or other +means of authentication) before they may run commands. +This default may be overridden via the +.Li PASSWD +and +.Li NOPASSWD +tags. +This flag is +.Em on +by default. +.It closefrom_override +If set, the user may use +.Nm sudo Ns No 's +.Fl C +option which overrides the default starting point at which +.Nm sudo +begins closing open file descriptors. +This flag is +.Em off +by default. +.It compress_io +If set, and +.Nm sudo +is configured to log a command's input or output, +the I/O logs will be compressed using +.Sy zlib . +This flag is +.Em on +by default when +.Nm sudo +is compiled with +.Sy zlib +support. +.It env_editor +If set, +.Nm visudo +will use the value of the +.Ev EDITOR +or +.Ev VISUAL +environment variables before falling back on the default editor list. +Note that this may create a security hole as it allows the user to +run any arbitrary command as root without logging. +A safer alternative is to place a colon-separated list of editors +in the +.Li editor +variable. +.Nm visudo +will then only use the +.Ev EDITOR +or +.Ev VISUAL +if they match a value specified in +.Li editor . +This flag is +.Em @env_editor@ +by +default. +.It env_reset +If set, +.Nm sudo +will run the command in a minimal environment containing the +.Ev TERM , +.Ev PATH , +.Ev HOME , +.Ev MAIL , +.Ev SHELL , +.Ev LOGNAME , +.Ev USER , +.Ev USERNAME +and +.Ev SUDO_* +variables. +Any +variables in the caller's environment that match the +.Li env_keep +and +.Li env_check +lists are then added, followed by any variables present in the file +specified by the +.Em env_file +option (if any). +The default contents of the +.Li env_keep +and +.Li env_check +lists are displayed when +.Nm sudo +is run by root with the +.Fl V +option. +If the +.Em secure_path +option is set, its value will be used for the +.Ev PATH +environment variable. +This flag is +.Em @env_reset@ +by default. +.It fast_glob +Normally, +.Nm sudo +uses the +.Xr glob 3 +function to do shell-style globbing when matching path names. +However, since it accesses the file system, +.Xr glob 3 +can take a long time to complete for some patterns, especially +when the pattern references a network file system that is mounted +on demand (automounted). +The +.Em fast_glob +option causes +.Nm sudo +to use the +.Xr fnmatch 3 +function, which does not access the file system to do its matching. +The disadvantage of +.Em fast_glob +is that it is unable to match relative path names such as +.Pa ./ls +or +.Pa ../bin/ls . +This has security implications when path names that include globbing +characters are used with the negation operator, +.Ql !\& , +as such rules can be trivially bypassed. +As such, this option should not be used when +.Em sudoers +contains rules that contain negated path names which include globbing +characters. +This flag is +.Em off +by default. +.It fqdn +Set this flag if you want to put fully qualified host names in the +.Em sudoers +file. +In other words, instead of myhost you would use myhost.mydomain.edu. +You may still use the short form if you wish (and even mix the two). +Beware that turning on +.Em fqdn +requires +.Nm sudo +to make DNS lookups which may make +.Nm sudo +unusable if DNS stops working (for example if the machine is not plugged +into the network). +Also note that you must use the host's official name as DNS knows it. +That is, you may not use a host alias +.Po +.Li CNAME +entry +.Pc +due to performance issues and the fact that there is no way to get all +aliases from DNS. +If your machine's host name (as returned by the +.Li hostname +command) is already fully qualified you shouldn't need to set +.Em fqdn . +This flag is +.Em @fqdn@ +by default. +.It ignore_dot +If set, +.Nm sudo +will ignore "." or "" (both denoting current directory) in the +.Ev PATH +environment variable; the +.Ev PATH +itself is not modified. +This flag is +.Em @ignore_dot@ +by default. +.It ignore_local_sudoers +If set via LDAP, parsing of +.Pa @sysconfdir@/sudoers +will be skipped. +This is intended for Enterprises that wish to prevent the usage of local +sudoers files so that only LDAP is used. +This thwarts the efforts of rogue operators who would attempt to add roles to +.Pa @sysconfdir@/sudoers . +When this option is present, +.Pa @sysconfdir@/sudoers +does not even need to exist. +Since this option tells +.Nm sudo +how to behave when no specific LDAP entries have been matched, this +sudoOption is only meaningful for the +.Li cn=defaults +section. +This flag is +.Em off +by default. +.It insults +If set, +.Nm sudo +will insult users when they enter an incorrect password. +This flag is +.Em @insults@ +by default. +.It log_host +If set, the host name will be logged in the (non-syslog) +.Nm sudo +log file. +This flag is +.Em off +by default. +.It log_input +If set, +.Nm sudo +will run the command in a +.Em pseudo tty +and log all user input. +If the standard input is not connected to the user's tty, due to +I/O redirection or because the command is part of a pipeline, that +input is also captured and stored in a separate log file. +.Pp +Input is logged to the directory specified by the +.Em iolog_dir +option +.Po +.Pa @iolog_dir@ +by default +.Pc +using a unique session ID that is included in the normal +.Nm sudo +log line, prefixed with +.Dq Li TSID= . +The +.Em iolog_file +option may be used to control the format of the session ID. +.Pp +Note that user input may contain sensitive information such as +passwords (even if they are not echoed to the screen), which will +be stored in the log file unencrypted. +In most cases, logging the command output via +.Em log_output +is all that is required. +.It log_output +If set, +.Nm sudo +will run the command in a +.Em pseudo tty +and log all output that is sent to the screen, similar to the +.Xr script 1 +command. +If the standard output or standard error is not connected to the +user's tty, due to I/O redirection or because the command is part +of a pipeline, that output is also captured and stored in separate +log files. +.Pp +Output is logged to the directory specified by the +.Em iolog_dir +option +.Po +.Pa @iolog_dir@ +by default +.Pc +using a unique session ID that is included in the normal +.Nm sudo +log line, prefixed with +.Dq Li TSID= . +The +.Em iolog_file +option may be used to control the format of the session ID. +.Pp +Output logs may be viewed with the +.Xr sudoreplay 8 +utility, which can also be used to list or search the available logs. +.It log_year +If set, the four-digit year will be logged in the (non-syslog) +.Nm sudo +log file. +This flag is +.Em off +by default. +.It long_otp_prompt +When validating with a One Time Password (OTP) scheme such as +.Sy S/Key +or +.Sy OPIE , +a two-line prompt is used to make it easier +to cut and paste the challenge to a local window. +It's not as pretty as the default but some people find it more convenient. +This flag is +.Em @long_otp_prompt@ +by default. +.It mail_always +Send mail to the +.Em mailto +user every time a users runs +.Nm sudo . +This flag is +.Em off +by default. +.It mail_badpass +Send mail to the +.Em mailto +user if the user running +.Nm sudo +does not enter the correct password. +If the command the user is attempting to run is not permitted by +.Em sudoers +and one of the +.Em mail_always , +.Em mail_no_host , +.Em mail_no_perms +or +.Em mail_no_user +flags are set, this flag will have no effect. +This flag is +.Em off +by default. +.It mail_no_host +If set, mail will be sent to the +.Em mailto +user if the invoking user exists in the +.Em sudoers +file, but is not allowed to run commands on the current host. +This flag is +.Em @mail_no_host@ +by default. +.It mail_no_perms +If set, mail will be sent to the +.Em mailto +user if the invoking user is allowed to use +.Nm sudo +but the command they are trying is not listed in their +.Em sudoers +file entry or is explicitly denied. +This flag is +.Em @mail_no_perms@ +by default. +.It mail_no_user +If set, mail will be sent to the +.Em mailto +user if the invoking user is not in the +.Em sudoers +file. +This flag is +.Em @mail_no_user@ +by default. +.It noexec +If set, all commands run via +.Nm sudo +will behave as if the +.Li NOEXEC +tag has been set, unless overridden by a +.Li EXEC +tag. +See the description of +.Em NOEXEC and EXEC +below as well as the +.Sx Preventing Shell Escapes +section at the end of this manual. +This flag is +.Em off +by default. +.It path_info +Normally, +.Nm sudo +will tell the user when a command could not be +found in their +.Ev PATH +environment variable. +Some sites may wish to disable this as it could be used to gather +information on the location of executables that the normal user does +not have access to. +The disadvantage is that if the executable is simply not in the user's +.Ev PATH , +.Nm sudo +will tell the user that they are not allowed to run it, which can be confusing. +This flag is +.Em @path_info@ +by default. +.It passprompt_override +The password prompt specified by +.Em passprompt +will normally only be used if the password prompt provided by systems +such as PAM matches the string +.Dq Password: . +If +.Em passprompt_override +is set, +.Em passprompt +will always be used. +This flag is +.Em off +by default. +.It preserve_groups +By default, +.Nm sudo +will initialize the group vector to the list of groups the target user is in. +When +.Em preserve_groups +is set, the user's existing group vector is left unaltered. +The real and effective group IDs, however, are still set to match the +target user. +This flag is +.Em off +by default. +.It pwfeedback +By default, +.Nm sudo +reads the password like most other Unix programs, +by turning off echo until the user hits the return (or enter) key. +Some users become confused by this as it appears to them that +.Nm sudo +has hung at this point. +When +.Em pwfeedback +is set, +.Nm sudo +will provide visual feedback when the user presses a key. +Note that this does have a security impact as an onlooker may be able to +determine the length of the password being entered. +This flag is +.Em off +by default. +.It requiretty +If set, +.Nm sudo +will only run when the user is logged in to a real tty. +When this flag is set, +.Nm sudo +can only be run from a login session and not via other means such as +.Xr cron 8 +or cgi-bin scripts. +This flag is +.Em off +by default. +.It root_sudo +If set, root is allowed to run +.Nm sudo +too. +Disabling this prevents users from +.Dq chaining +.Nm sudo +commands to get a root shell by doing something like +.Dq Li sudo sudo /bin/sh . +Note, however, that turning off +.Em root_sudo +will also prevent root from running +.Nm sudoedit . +Disabling +.Em root_sudo +provides no real additional security; it exists purely for historical reasons. +This flag is +.Em @root_sudo@ +by default. +.It rootpw +If set, +.Nm sudo +will prompt for the root password instead of the password of the invoking user. +This flag is +.Em off +by default. +.It runaspw +If set, +.Nm sudo +will prompt for the password of the user defined by the +.Em runas_default +option (defaults to +.Li @runas_default@ ) +instead of the password of the invoking user. +This flag is +.Em off +by default. +.It set_home +If enabled and +.Nm sudo +is invoked with the +.Fl s +option the +.Ev HOME +environment variable will be set to the home directory of the target +user (which is root unless the +.Fl u +option is used). +This effectively makes the +.Fl s +option imply +.Fl H . +Note that +.Ev HOME +is already set when the the +.Em env_reset +option is enabled, so +.Em set_home +is only effective for configurations where either +.Em env_reset +is disabled +or +.Ev HOME +is present in the +.Em env_keep +list. +This flag is +.Em off +by default. +.It set_logname +Normally, +.Nm sudo +will set the +.Ev LOGNAME , +.Ev USER +and +.Ev USERNAME +environment variables to the name of the target user (usually root unless the +.Fl u +option is given). +However, since some programs (including the RCS revision control system) use +.Ev LOGNAME +to determine the real identity of the user, it may be desirable to +change this behavior. +This can be done by negating the set_logname option. +Note that if the +.Em env_reset +option has not been disabled, entries in the +.Em env_keep +list will override the value of +.Em set_logname . +This flag is +.Em on +by default. +.It set_utmp +When enabled, +.Nm sudo +will create an entry in the utmp (or utmpx) file when a pseudo-tty +is allocated. +A pseudo-tty is allocated by +.Nm sudo +when the +.Em log_input , +.Em log_output +or +.Em use_pty +flags are enabled. +By default, the new entry will be a copy of the user's existing utmp +entry (if any), with the tty, time, type and pid fields updated. +This flag is +.Em on +by default. +.It setenv +Allow the user to disable the +.Em env_reset +option from the command line via the +.Fl E +option. +Additionally, environment variables set via the command line are +not subject to the restrictions imposed by +.Em env_check , +.Em env_delete , +or +.Em env_keep . +As such, only trusted users should be allowed to set variables in this manner. +This flag is +.Em off +by default. +.It shell_noargs +If set and +.Nm sudo +is invoked with no arguments it acts as if the +.Fl s +option had been given. +That is, it runs a shell as root (the shell is determined by the +.Ev SHELL +environment variable if it is set, falling back on the shell listed +in the invoking user's /etc/passwd entry if not). +This flag is +.Em off +by default. +.It stay_setuid +Normally, when +.Nm sudo +executes a command the real and effective UIDs are set to the target +user (root by default). +This option changes that behavior such that the real UID is left +as the invoking user's UID. +In other words, this makes +.Nm sudo +act as a setuid wrapper. +This can be useful on systems that disable some potentially +dangerous functionality when a program is run setuid. +This option is only effective on systems that support either the +.Xr setreuid 2 +or +.Xr setresuid 2 +system call. +This flag is +.Em off +by default. +.It targetpw +If set, +.Nm sudo +will prompt for the password of the user specified +by the +.Fl u +option (defaults to +.Li root ) +instead of the password of the invoking user. +In addition, the timestamp file name will include the target user's name. +Note that this flag precludes the use of a uid not listed in the passwd +database as an argument to the +.Fl u +option. +This flag is +.Em off +by default. +.It tty_tickets +If set, users must authenticate on a per-tty basis. +With this flag enabled, +.Nm sudo +will use a file named for the tty the user is +logged in on in the user's time stamp directory. +If disabled, the time stamp of the directory is used instead. +This flag is +.Em @tty_tickets@ +by default. +.It umask_override +If set, +.Nm sudo +will set the umask as specified by +.Em sudoers +without modification. +This makes it possible to specify a more permissive umask in +.Em sudoers +than the user's own umask and matches historical behavior. +If +.Em umask_override +is not set, +.Nm sudo +will set the umask to be the union of the user's umask and what is specified in +.Em sudoers . +This flag is +.Em @umask_override@ +by default. +.It use_loginclass +If set, +.Nm sudo +will apply the defaults specified for the target user's login class +if one exists. +Only available if +.Nm sudo +is configured with the +.Li --with-logincap +option. +This flag is +.Em off +by default. +.It use_pty +If set, +.Nm sudo +will run the command in a pseudo-pty even if no I/O logging is being gone. +A malicious program run under +.Nm sudo +could conceivably fork a background process that retains to the user's +terminal device after the main program has finished executing. +Use of this option will make that impossible. +This flag is +.Em off +by default. +.It utmp_runas +If set, +.Nm sudo +will store the name of the runas user when updating the utmp (or utmpx) file. +By default, +.Nm sudo +stores the name of the invoking user. +This flag is +.Em off +by default. +.It visiblepw +By default, +.Nm sudo +will refuse to run if the user must enter a password but it is not +possible to disable echo on the terminal. +If the +.Em visiblepw +flag is set, +.Nm sudo +will prompt for a password even when it would be visible on the screen. +This makes it possible to run things like +.Dq Li ssh somehost sudo ls +since by default, +.Xr ssh 1 +does +not allocate a tty when running a command. +This flag is +.Em off +by default. +.El +.Pp +.Sy Integers : +.Bl -tag -width 16n +.It closefrom +Before it executes a command, +.Nm sudo +will close all open file descriptors other than standard input, +standard output and standard error (ie: file descriptors 0-2). +The +.Em closefrom +option can be used to specify a different file descriptor at which +to start closing. +The default is +.Li 3 . +.It passwd_tries +The number of tries a user gets to enter his/her password before +.Nm sudo +logs the failure and exits. +The default is +.Li @passwd_tries@ . +.El +.Pp +.Sy Integers that can be used in a boolean context : +.Bl -tag -width 16n +.It loglinelen +Number of characters per line for the file log. +This value is used to decide when to wrap lines for nicer log files. +This has no effect on the syslog log file, only the file log. +The default is +.Li @loglen@ +(use 0 or negate the option to disable word wrap). +.It passwd_timeout +Number of minutes before the +.Nm sudo +password prompt times out, or +.Li 0 +for no timeout. +The timeout may include a fractional component +if minute granularity is insufficient, for example +.Li 2.5 . +The +default is +.Li @password_timeout@ . +.It timestamp_timeout +Number of minutes that can elapse before +.Nm sudo +will ask for a passwd again. +The timeout may include a fractional component if +minute granularity is insufficient, for example +.Li 2.5 . +The default is +.Li @timeout@ . +Set this to +.Li 0 +to always prompt for a password. +If set to a value less than +.Li 0 +the user's timestamp will never expire. +This can be used to allow users to create or delete their own timestamps via +.Dq Li sudo -v +and +.Dq Li sudo -k +respectively. +.It umask +Umask to use when running the command. +Negate this option or set it to 0777 to preserve the user's umask. +The actual umask that is used will be the union of the user's umask +and the value of the +.Em umask +option, which defaults to +.Li @sudo_umask@ . +This guarantees +that +.Nm sudo +never lowers the umask when running a command. +Note: on systems that use PAM, the default PAM configuration may specify +its own umask which will override the value set in +.Em sudoers . +.El +.Pp +.Sy Strings : +.Bl -tag -width 16n +.It badpass_message +Message that is displayed if a user enters an incorrect password. +The default is +.Li @badpass_message@ +unless insults are enabled. +.It editor +A colon +.Pq Ql :\& +separated list of editors allowed to be used with +.Nm visudo . +.Nm visudo +will choose the editor that matches the user's +.Ev EDITOR +environment variable if possible, or the first editor in the +list that exists and is executable. +The default is +.Pa @editor@ . +.It iolog_dir +The top-level directory to use when constructing the path name for +the input/output log directory. +Only used if the +.Em log_input +or +.Em log_output +options are enabled or when the +.Li LOG_INPUT +or +.Li LOG_OUTPUT +tags are present for a command. +The session sequence number, if any, is stored in the directory. +The default is +.Pa @iolog_dir@ . +.Pp +The following percent +.Pq Ql % +escape sequences are supported: +.Bl -tag -width 4n +.It Li %{seq} +expanded to a monotonically increasing base-36 sequence number, such as 0100A5, +where every two digits are used to form a new directory, e.g.\& +.Pa 01/00/A5 +.It Li %{user} +expanded to the invoking user's login name +.It Li %{group} +expanded to the name of the invoking user's real group ID +.It Li %{runas_user} +expanded to the login name of the user the command will +be run as (e.g.\& root) +.It Li %{runas_group} +expanded to the group name of the user the command will +be run as (e.g.\& wheel) +.It Li %{hostname} +expanded to the local host name without the domain name +.It Li %{command} +expanded to the base name of the command being run +.El +.Pp +In addition, any escape sequences supported by the system's +.Xr strftime 3 +function will be expanded. +.Pp +To include a literal +.Ql % +character, the string +.Ql %% +should be used. +.It iolog_file +The path name, relative to +.Em iolog_dir , +in which to store input/output logs when the +.Em log_input +or +.Em log_output +options are enabled or when the +.Li LOG_INPUT +or +.Li LOG_OUTPUT +tags are present for a command. +Note that +.Em iolog_file +may contain directory components. +The default is +.Dq Li %{seq} . +.Pp +See the +.Em iolog_dir +option above for a list of supported percent +.Pq Ql % +escape sequences. +.Pp +In addition to the escape sequences, path names that end in six or +more +.Li X Ns No s +will have the +.Li X Ns No s +replaced with a unique combination of digits and letters, similar to the +.Xr mktemp 3 +function. +.It mailsub +Subject of the mail sent to the +.Em mailto +user. +The escape +.Li %h +will expand to the host name of the machine. +Default is +.Dq Li @mailsub@ . +.It noexec_file +This option is no longer supported. +The path to the noexec file should now be set in the +.Pa @sysconfdir@/sudo.conf +file. +.It passprompt +The default prompt to use when asking for a password; can be overridden via the +.Fl p +option or the +.Ev SUDO_PROMPT +environment variable. +The following percent +.Pq Ql % +escape sequences are supported: +.Bl -tag -width 4n +.It Li %H +expanded to the local host name including the domain name +(only if the machine's host name is fully qualified or the +.Em fqdn +option is set) +.It Li %h +expanded to the local host name without the domain name +.It Li %p +expanded to the user whose password is being asked for (respects the +.Em rootpw , +.Em targetpw +and +.Em runaspw +flags in +.Em sudoers ) +.It Li %U +expanded to the login name of the user the command will +be run as (defaults to root) +.It Li %u +expanded to the invoking user's login name +.It Li %% +two consecutive +.Li % +characters are collapsed into a single +.Li % +character +.El +.Pp +The default value is +.Dq Li @passprompt@ . +.It role +The default SELinux role to use when constructing a new security +context to run the command. +The default role may be overridden on a per-command basis in +.Em sudoers +or via command line options. +This option is only available whe +.Nm sudo +is built with SELinux support. +.It runas_default +The default user to run commands as if the +.Fl u +option is not specified on the command line. +This defaults to +.Li @runas_default@ . +.It syslog_badpri +Syslog priority to use when user authenticates unsuccessfully. +Defaults to +.Li @badpri@ . +.Pp +The following syslog priorities are supported: +.Sy alert , +.Sy crit , +.Sy debug , +.Sy emerg , +.Sy err , +.Sy info , +.Sy notice , +and +.Sy warning . +.It syslog_goodpri +Syslog priority to use when user authenticates successfully. +Defaults to +.Li @goodpri@ . +.Pp +See +.Sx syslog_badpri +for the list of supported syslog priorities. +.It sudoers_locale +Locale to use when parsing the sudoers file, logging commands, and +sending email. +Note that changing the locale may affect how sudoers is interpreted. +Defaults to +.Dq Li C . +.It timestampdir +The directory in which +.Nm sudo +stores its timestamp files. +The default is +.Pa @timedir@ . +.It timestampowner +The owner of the timestamp directory and the timestamps stored therein. +The default is +.Li root . +.It type +The default SELinux type to use when constructing a new security +context to run the command. +The default type may be overridden on a per-command basis in +.Em sudoers +or via command line options. +This option is only available whe +.Nm sudo +is built with SELinux support. +.El +.Pp +.Sy Strings that can be used in a boolean context : +.Bl -tag -width 12n +.It env_file +The +.Em env_file +option specifies the fully qualified path to a file containing variables +to be set in the environment of the program being run. +Entries in this file should either be of the form +.Dq Li VARIABLE=value +or +.Dq Li export VARIABLE=value . +The value may optionally be surrounded by single or double quotes. +Variables in this file are subject to other +.Nm sudo +environment settings such as +.Em env_keep +and +.Em env_check . +.It exempt_group +Users in this group are exempt from password and PATH requirements. +The group name specified should not include a +.Li % +prefix. +This is not set by default. +.It group_plugin +A string containing a +.Em sudoers +group plugin with optional arguments. +This can be used to implement support for the +.Li nonunix_group +syntax described earlier. +The string should consist of the plugin +path, either fully-qualified or relative to the +.Pa @prefix@/libexec +directory, followed by any configuration arguments the plugin requires. +These arguments (if any) will be passed to the plugin's initialization function. +If arguments are present, the string must be enclosed in double quotes +.Pq \&"" . +.Pp +For example, given +.Pa /etc/sudo-group , +a group file in Unix group format, the sample group plugin can be used: +.Bd -literal +Defaults group_plugin="sample_group.so /etc/sudo-group" +.Ed +.Pp +For more information see +.Xr sudo_plugin 5 . +.It lecture +This option controls when a short lecture will be printed along with +the password prompt. +It has the following possible values: +.Bl -tag -width 6n +.It always +Always lecture the user. +.It never +Never lecture the user. +.It once +Only lecture the user the first time they run +.Nm sudo . +.El +.Pp +If no value is specified, a value of +.Em once +is implied. +Negating the option results in a value of +.Em never +being used. +The default value is +.Em @lecture@ . +.It lecture_file +Path to a file containing an alternate +.Nm sudo +lecture that will be used in place of the standard lecture if the named +file exists. +By default, +.Nm sudo +uses a built-in lecture. +.It listpw +This option controls when a password will be required when a user runs +.Nm sudo +with the +.Fl l +option. +It has the following possible values: +.Bl -tag -width 8n +.It all +All the user's +.Em sudoers +entries for the current host must have +the +.Li NOPASSWD +flag set to avoid entering a password. +.It always +The user must always enter a password to use the +.Fl l +option. +.It any +At least one of the user's +.Em sudoers +entries for the current host +must have the +.Li NOPASSWD +flag set to avoid entering a password. +.It never +The user need never enter a password to use the +.Fl l +option. +.El +.Pp +If no value is specified, a value of +.Em any +is implied. +Negating the option results in a value of +.Em never +being used. +The default value is +.Em any . +.It logfile +Path to the +.Nm sudo +log file (not the syslog log file). +Setting a path turns on logging to a file; +negating this option turns it off. +By default, +.Nm sudo +logs via syslog. +.It mailerflags +Flags to use when invoking mailer. Defaults to +.Fl t . +.It mailerpath +Path to mail program used to send warning mail. +Defaults to the path to sendmail found at configure time. +.It mailfrom +Address to use for the +.Dq from +address when sending warning and error mail. +The address should be enclosed in double quotes +.Pq \&"" +to protect against +.Nm sudo +interpreting the +.Li @ +sign. +Defaults to the name of the user running +.Nm sudo . +.It mailto +Address to send warning and error mail to. +The address should be enclosed in double quotes +.Pq \&"" +to protect against +.Nm sudo +interpreting the +.Li @ +sign. +Defaults to +.Li @mailto@ . +.It secure_path +Path used for every command run from +.Nm sudo . +If you don't trust the +people running +.Nm sudo +to have a sane +.Ev PATH +environment variable you may want to use this. +Another use is if you want to have the +.Dq root path +be separate from the +.Dq user path . +Users in the group specified by the +.Em exempt_group +option are not affected by +.Em secure_path . +This option is @secure_path@ by default. +.It syslog +Syslog facility if syslog is being used for logging (negate to +disable syslog logging). +Defaults to +.Li @logfac@ . +.Pp +The following syslog facilities are supported: +.Sy authpriv +(if your +OS supports it), +.Sy auth , +.Sy daemon , +.Sy user , +.Sy local0 , +.Sy local1 , +.Sy local2 , +.Sy local3 , +.Sy local4 , +.Sy local5 , +.Sy local6 , +and +.Sy local7 . +.It verifypw +This option controls when a password will be required when a user runs +.Nm sudo +with the +.Fl v +option. +It has the following possible values: +.Bl -tag -width 6n +.It all +All the user's +.Em sudoers +entries for the current host must have the +.Li NOPASSWD +flag set to avoid entering a password. +.It always +The user must always enter a password to use the +.Fl v +option. +.It any +At least one of the user's +.Em sudoers +entries for the current host must have the +.Li NOPASSWD +flag set to avoid entering a password. +.It never +The user need never enter a password to use the +.Fl v +option. +.El +.Pp +If no value is specified, a value of +.Em all +is implied. +Negating the option results in a value of +.Em never +being used. +The default value is +.Em all . +.El +.Pp +.Sy Lists that can be used in a boolean context : +.Bl -tag -width 16n +.It env_check +Environment variables to be removed from the user's environment if +the variable's value contains +.Ql % +or +.Ql / +characters. +This can be used to guard against printf-style format vulnerabilities +in poorly-written programs. +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using +the +.Li = , +.Li += , +.Li -= , +and +.Li \&! +operators respectively. +Regardless of whether the +.Li env_reset +option is enabled or disabled, variables specified by +.Li env_check +will be preserved in the environment if they pass the aforementioned check. +The default list of environment variables to check is displayed when +.Nm sudo +is run by root with +the +.Fl V +option. +.It env_delete +Environment variables to be removed from the user's environment when the +.Em env_reset +option is not in effect. +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using the +.Li = , +.Li += , +.Li -= , +and +.Li \&! +operators respectively. +The default list of environment variables to remove is displayed when +.Nm sudo +is run by root with the +.Fl V +option. +Note that many operating systems will remove potentially dangerous +variables from the environment of any setuid process (such as +.Nm sudo ) . +.It env_keep +Environment variables to be preserved in the user's environment when the +.Em env_reset +option is in effect. +This allows fine-grained control over the environment +.Nm sudo Ns No -spawned +processes will receive. +The argument may be a double-quoted, space-separated list or a +single value without double-quotes. +The list can be replaced, added to, deleted from, or disabled by using the +.Li = , +.Li += , +.Li -= , +and +.Li \&! +operators respectively. +The default list of variables to keep +is displayed when +.Nm sudo +is run by root with the +.Fl V +option. +.El +.Sh SUDO.CONF +The +.Pa @sysconfdir@/sudo.conf +file determines which plugins the +.Nm sudo +front end will load. +If no +.Pa @sysconfdir@/sudo.conf +file +is present, or it contains no +.Li Plugin +lines, +.Nm sudo +will use the +.Em sudoers +security policy and I/O logging, which corresponds to the following +.Pa @sysconfdir@/sudo.conf +file. +.Bd -literal +# +# Default @sysconfdir@/sudo.conf file +# +# Format: +# Plugin plugin_name plugin_path plugin_options ... +# Path askpass /path/to/askpass +# Path noexec /path/to/sudo_noexec.so +# Debug sudo /var/log/sudo_debug all@warn +# Set disable_coredump true +# +# The plugin_path is relative to @prefix@/libexec unless +# fully qualified. +# The plugin_name corresponds to a global symbol in the plugin +# that contains the plugin interface structure. +# The plugin_options are optional. +# +Plugin policy_plugin sudoers.so +Plugin io_plugin sudoers.so +.Ed +.Ss PLUGIN OPTIONS +Starting with +.Nm sudo +1.8.5, it is possible to pass options to the +.Em sudoers +plugin. +Options may be listed after the path to the plugin (i.e.\& after +.Pa sudoers.so ) ; +multiple options should be space-separated. +For example: +.Bd -literal +Plugin sudoers_policy sudoers.so sudoers_file=/etc/sudoers sudoers_uid=0 sudoers_gid=0 sudoers_mode=0440 +.Ed +.Pp +The following plugin options are supported: +.Bl -tag -width 8n +.It sudoers_file=pathname +The +.Em sudoers_file +option can be used to override the default path +to the +.Em sudoers +file. +.It sudoers_uid=uid +The +.Em sudoers_uid +option can be used to override the default owner of the sudoers file. +It should be specified as a numeric user ID. +.It sudoers_gid=gid +The +.Em sudoers_gid +option can be used to override the default group of the sudoers file. +It should be specified as a numeric group ID. +.It sudoers_mode=mode +The +.Em sudoers_mode +option can be used to override the default file mode for the sudoers file. +It should be specified as an octal value. +.El +.Ss DEBUG FLAGS +Versions 1.8.4 and higher of the +.Em sudoers +plugin supports a debugging framework that can help track down what the +plugin is doing internally if there is a problem. +This can be configured in the +.Pa @sysconfdir@/sudo.conf +file as described in +.Xr sudo 8 . +.Pp +The +.Em sudoers +plugin uses the same debug flag format as the +.Nm sudo +front-end: +.Em subsystem Ns No @ Ns Em priority . +.Pp +The priorities used by +.Em sudoers , +in order of decreasing severity, +are: +.Em crit , +.Em err , +.Em warn , +.Em notice , +.Em diag , +.Em info , +.Em trace +and +.Em debug . +Each priority, when specified, also includes all priorities higher than it. +For example, a priority of +.Em notice +would include debug messages logged at +.Em notice +and higher. +.Pp +The following subsystems are used by +.Em sudoers : +.Bl -tag -width 8n +.It Em alias +.Li User_Alias , +.Li Runas_Alias , +.Li Host_Alias +and +.Li Cmnd_Alias +processing +.It Em all +matches every subsystem +.It Em audit +BSM and Linux audit code +.It Em auth +user authentication +.It Em defaults +.Em sudoers +.Em Defaults +settings +.It Em env +environment handling +.It Em ldap +LDAP-based sudoers +.It Em logging +logging support +.It Em match +matching of users, groups, hosts and netgroups in +.Em sudoers +.It Em netif +network interface handling +.It Em nss +network service switch handling in +.Em sudoers +.It Em parser +.Em sudoers +file parsing +.It Em perms +permission setting +.It Em plugin +The equivalent of +.Em main +for the plugin. +.It Em pty +pseudo-tty related code +.It Em rbtree +redblack tree internals +.It Em util +utility functions +.El +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +Sudo front end configuration +.It Pa @sysconfdir@/sudoers +List of who can run what +.It Pa /etc/group +Local groups file +.It Pa /etc/netgroup +List of network groups +.It Pa @iolog_dir@ +I/O log files +.It Pa @timedir@ +Directory containing time stamps for the +.Em sudoers +security policy +.It Pa /etc/environment +Initial environment for +.Fl i +mode on AIX and Linux systems +.El +.Sh EXAMPLES +Below are example +.Em sudoers +entries. +Admittedly, some of these are a bit contrived. +First, we allow a few environment variables to pass and then define our +.Em aliases : +.Bd -literal +# Run X applications through sudo; HOME is used to find the +# .Xauthority file. Note that other programs use HOME to find +# configuration files and this may lead to privilege escalation! +Defaults env_keep += "DISPLAY HOME" + +# User alias specification +User_Alias FULLTIMERS = millert, mikef, dowdy +User_Alias PARTTIMERS = bostley, jwfox, crawl +User_Alias WEBMASTERS = will, wendy, wim + +# Runas alias specification +Runas_Alias OP = root, operator +Runas_Alias DB = oracle, sybase +Runas_Alias ADMINGRP = adm, oper + +# Host alias specification +Host_Alias SPARC = bigtime, eclipse, moet, anchor :\e + SGI = grolsch, dandelion, black :\e + ALPHA = widget, thalamus, foobar :\e + HPPA = boa, nag, python +Host_Alias CUNETS = 128.138.0.0/255.255.0.0 +Host_Alias CSNETS = 128.138.243.0, 128.138.204.0/24, 128.138.242.0 +Host_Alias SERVERS = master, mail, www, ns +Host_Alias CDROM = orion, perseus, hercules + +# Cmnd alias specification +Cmnd_Alias DUMPS = /usr/bin/mt, /usr/sbin/dump, /usr/sbin/rdump,\e + /usr/sbin/restore, /usr/sbin/rrestore +Cmnd_Alias KILL = /usr/bin/kill +Cmnd_Alias PRINTING = /usr/sbin/lpc, /usr/bin/lprm +Cmnd_Alias SHUTDOWN = /usr/sbin/shutdown +Cmnd_Alias HALT = /usr/sbin/halt +Cmnd_Alias REBOOT = /usr/sbin/reboot +Cmnd_Alias SHELLS = /usr/bin/sh, /usr/bin/csh, /usr/bin/ksh,\e + /usr/local/bin/tcsh, /usr/bin/rsh,\e + /usr/local/bin/zsh +Cmnd_Alias SU = /usr/bin/su +Cmnd_Alias PAGERS = /usr/bin/more, /usr/bin/pg, /usr/bin/less +.Ed +.Pp +Here we override some of the compiled in default values. +We want +.Nm sudo +to log via +.Xr syslog 3 +using the +.Em auth +facility in all cases. +We don't want to subject the full time staff to the +.Nm sudo +lecture, user +.Sy millert +need not give a password, and we don't want to reset the +.Ev LOGNAME , +.Ev USER +or +.Ev USERNAME +environment variables when running commands as root. +Additionally, on the machines in the +.Em SERVERS +.Li Host_Alias , +we keep an additional local log file and make sure we log the year +in each log line since the log entries will be kept around for several years. +Lastly, we disable shell escapes for the commands in the PAGERS +.Li Cmnd_Alias +.Po +.Pa /usr/bin/more , +.Pa /usr/bin/pg +and +.Pa /usr/bin/less +.Pc . +.Bd -literal +# Override built-in defaults +Defaults syslog=auth +Defaults>root !set_logname +Defaults:FULLTIMERS !lecture +Defaults:millert !authenticate +Defaults@SERVERS log_year, logfile=/var/log/sudo.log +Defaults!PAGERS noexec +.Ed +.Pp +The +.Em User specification +is the part that actually determines who may run what. +.Bd -literal +root ALL = (ALL) ALL +%wheel ALL = (ALL) ALL +.Ed +.Pp +We let +.Sy root +and any user in group +.Sy wheel +run any command on any host as any user. +.Bd -literal +FULLTIMERS ALL = NOPASSWD: ALL +.Ed +.Pp +Full time sysadmins +.Po +.Sy millert , +.Sy mikef , +and +.Sy dowdy +.Pc +may run any command on any host without authenticating themselves. +.Bd -literal +PARTTIMERS ALL = ALL +.Ed +.Pp +Part time sysadmins +.Sy bostley , +.Sy jwfox , +and +.Sy crawl ) +may run any command on any host but they must authenticate themselves +first (since the entry lacks the +.Li NOPASSWD +tag). +.Bd -literal +jack CSNETS = ALL +.Ed +.Pp +The user +.Sy jack +may run any command on the machines in the +.Em CSNETS +alias (the networks +.Li 128.138.243.0 , +.Li 128.138.204.0 , +and +.Li 128.138.242.0 ) . +Of those networks, only +.Li 128.138.204.0 +has an explicit netmask (in CIDR notation) indicating it is a class C network. +For the other networks in +.Em CSNETS , +the local machine's netmask will be used during matching. +.Bd -literal +lisa CUNETS = ALL +.Ed +.Pp +The user +.Sy lisa +may run any command on any host in the +.Em CUNETS +alias (the class B network +.Li 128.138.0.0 ) . +.Bd -literal +operator ALL = DUMPS, KILL, SHUTDOWN, HALT, REBOOT, PRINTING,\e + sudoedit /etc/printcap, /usr/oper/bin/ +.Ed +.Pp +The +.Sy operator +user may run commands limited to simple maintenance. +Here, those are commands related to backups, killing processes, the +printing system, shutting down the system, and any commands in the +directory +.Pa /usr/oper/bin/ . +.Bd -literal +joe ALL = /usr/bin/su operator +.Ed +.Pp +The user +.Sy joe +may only +.Xr su 1 +to operator. +.Bd -literal +pete HPPA = /usr/bin/passwd [A-Za-z]*, !/usr/bin/passwd root + +%opers ALL = (: ADMINGRP) /usr/sbin/ +.Ed +.Pp +Users in the +.Sy opers +group may run commands in +.Pa /usr/sbin/ +as themselves +with any group in the +.Em ADMINGRP +.Li Runas_Alias +(the +.Sy adm +and +.Sy oper +groups). +.Pp +The user +.Sy pete +is allowed to change anyone's password except for +root on the +.Em HPPA +machines. +Note that this assumes +.Xr passwd 1 +does not take multiple user names on the command line. +.Bd -literal +bob SPARC = (OP) ALL : SGI = (OP) ALL +.Ed +.Pp +The user +.Sy bob +may run anything on the +.Em SPARC +and +.Em SGI +machines as any user listed in the +.Em OP +.Li Runas_Alias +.Po +.Sy root +and +.Sy operator . +.Pc +.Bd -literal +jim +biglab = ALL +.Ed +.Pp +The user +.Sy jim +may run any command on machines in the +.Em biglab +netgroup. +.Nm sudo +knows that +.Dq biglab +is a netgroup due to the +.Ql + +prefix. +.Bd -literal ++secretaries ALL = PRINTING, /usr/bin/adduser, /usr/bin/rmuser +.Ed +.Pp +Users in the +.Sy secretaries +netgroup need to help manage the printers as well as add and remove users, +so they are allowed to run those commands on all machines. +.Bd -literal +fred ALL = (DB) NOPASSWD: ALL +.Ed +.Pp +The user +.Sy fred +can run commands as any user in the +.Em DB +.Li Runas_Alias +.Po +.Sy oracle +or +.Sy sybase +.Pc +without giving a password. +.Bd -literal +john ALPHA = /usr/bin/su [!-]*, !/usr/bin/su *root* +.Ed +.Pp +On the +.Em ALPHA +machines, user +.Sy john +may su to anyone except root but he is not allowed to specify any options +to the +.Xr su 1 +command. +.Bd -literal +jen ALL, !SERVERS = ALL +.Ed +.Pp +The user +.Sy jen +may run any command on any machine except for those in the +.Em SERVERS +.Li Host_Alias +(master, mail, www and ns). +.Bd -literal +jill SERVERS = /usr/bin/, !SU, !SHELLS +.Ed +.Pp +For any machine in the +.Em SERVERS +.Li Host_Alias , +.Sy jill +may run +any commands in the directory +.Pa /usr/bin/ +except for those commands +belonging to the +.Em SU +and +.Em SHELLS +.Li Cmnd_Aliases . +.Bd -literal +steve CSNETS = (operator) /usr/local/op_commands/ +.Ed +.Pp +The user +.Sy steve +may run any command in the directory /usr/local/op_commands/ +but only as user operator. +.Bd -literal +matt valkyrie = KILL +.Ed +.Pp +On his personal workstation, valkyrie, +.Sy matt +needs to be able to kill hung processes. +.Bd -literal +WEBMASTERS www = (www) ALL, (root) /usr/bin/su www +.Ed +.Pp +On the host www, any user in the +.Em WEBMASTERS +.Li User_Alias +(will, wendy, and wim), may run any command as user www (which owns the +web pages) or simply +.Xr su 1 +to www. +.Bd -literal +ALL CDROM = NOPASSWD: /sbin/umount /CDROM,\e + /sbin/mount -o nosuid\,nodev /dev/cd0a /CDROM +.Ed +.Pp +Any user may mount or unmount a CD-ROM on the machines in the CDROM +.Li Host_Alias +(orion, perseus, hercules) without entering a password. +This is a bit tedious for users to type, so it is a prime candidate +for encapsulating in a shell script. +.Sh SECURITY NOTES +.Ss Limitations of the So !\& Sc operator +It is generally not effective to +.Dq subtract +commands from +.Sy ALL +using the +.Ql !\& +operator. +A user can trivially circumvent this by copying the desired command +to a different name and then executing that. +For example: +.Bd -literal +bill ALL = ALL, !SU, !SHELLS +.Ed +.Pp +Doesn't really prevent +.Sy bill +from running the commands listed in +.Em SU +or +.Em SHELLS +since he can simply copy those commands to a different name, or use +a shell escape from an editor or other program. +Therefore, these kind of restrictions should be considered +advisory at best (and reinforced by policy). +.Pp +In general, if a user has sudo +.Sy ALL +there is nothing to prevent them from creating their own program that gives +them a root shell (or making their own copy of a shell) regardless of any +.Ql !\& +elements in the user specification. +.Ss Security implications of Em fast_glob +If the +.Em fast_glob +option is in use, it is not possible to reliably negate commands where the +path name includes globbing (aka wildcard) characters. +This is because the C library's +.Xr fnmatch 3 +function cannot resolve relative paths. +While this is typically only an inconvenience for rules that grant privileges, +it can result in a security issue for rules that subtract or revoke privileges. +.Pp +For example, given the following +.Em sudoers +entry: +.Bd -literal +john ALL = /usr/bin/passwd [a-zA-Z0-9]*, /usr/bin/chsh [a-zA-Z0-9]*,\e + /usr/bin/chfn [a-zA-Z0-9]*, !/usr/bin/* root +.Ed +.Pp +User +.Sy john +can still run +.Li /usr/bin/passwd root +if +.Em fast_glob +is enabled by changing to +.Pa /usr/bin +and running +.Li ./passwd root +instead. +.Ss Preventing Shell Escapes +Once +.Nm sudo +executes a program, that program is free to do whatever +it pleases, including run other programs. +This can be a security issue since it is not uncommon for a program to +allow shell escapes, which lets a user bypass +.Nm sudo Ns No 's +access control and logging. +Common programs that permit shell escapes include shells (obviously), +editors, paginators, mail and terminal programs. +.Pp +There are two basic approaches to this problem: +.Bl -tag -width 8n +.It restrict +Avoid giving users access to commands that allow the user to run +arbitrary commands. +Many editors have a restricted mode where shell +escapes are disabled, though +.Nm sudoedit +is a better solution to +running editors via +.Nm sudo . +Due to the large number of programs that +offer shell escapes, restricting users to the set of programs that +do not is often unworkable. +.It noexec +Many systems that support shared libraries have the ability to +override default library functions by pointing an environment +variable (usually +.Ev LD_PRELOAD ) +to an alternate shared library. +On such systems, +.Nm sudo Ns No 's +.Em noexec +functionality can be used to prevent a program run by +.Nm sudo +from executing any other programs. +Note, however, that this applies only to native dynamically-linked +executables. +Statically-linked executables and foreign executables +running under binary emulation are not affected. +.Pp +The +.Em noexec +feature is known to work on SunOS, Solaris, *BSD, +Linux, IRIX, Tru64 UNIX, MacOS X, HP-UX 11.x and AIX 5.3 and above. +It should be supported on most operating systems that support the +.Ev LD_PRELOAD +environment variable. +Check your operating system's manual pages for the dynamic linker +(usually ld.so, ld.so.1, dyld, dld.sl, rld, or loader) to see if +.Ev LD_PRELOAD +is supported. +.Pp +On Solaris 10 and higher, +.Em noexec +uses Solaris privileges instead of the +.Ev LD_PRELOAD +environment variable. +.Pp +To enable +.Em noexec +for a command, use the +.Li NOEXEC +tag as documented +in the User Specification section above. +Here is that example again: +.Bd -literal +aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi +.Ed +.Pp +This allows user +.Sy aaron +to run +.Pa /usr/bin/more +and +.Pa /usr/bin/vi +with +.Em noexec +enabled. +This will prevent those two commands from +executing other commands (such as a shell). +If you are unsure whether or not your system is capable of supporting +.Em noexec +you can always just try it out and check whether shell escapes work when +.Em noexec +is enabled. +.El +.Pp +Note that restricting shell escapes is not a panacea. +Programs running as root are still capable of many potentially hazardous +operations (such as changing or overwriting files) that could lead +to unintended privilege escalation. +In the specific case of an editor, a safer approach is to give the +user permission to run +.Nm sudoedit . +.Ss Time stamp file checks +.Em sudoers +will check the ownership of its time stamp directory +.Po +.Pa @timedir@ +by default +.Pc +and ignore the directory's contents if it is not owned by root or +if it is writable by a user other than root. +On systems that allow non-root users to give away files via +.Xr chown 2 , +if the time stamp directory is located in a world-writable +directory (e.g.\&, +.Pa /tmp ) , +it is possible for a user to create the time stamp directory before +.Nm sudo +is run. +However, because +.Em sudoers +checks the ownership and mode of the directory and its +contents, the only damage that can be done is to +.Dq hide +files by putting them in the time stamp dir. +This is unlikely to happen since once the time stamp dir is owned by root +and inaccessible by any other user, the user placing files there would be +unable to get them back out. +.Pp +.Em sudoers +will not honor time stamps set far in the future. +Time stamps with a date greater than current_time + 2 * +.Li TIMEOUT +will be ignored and sudo will log and complain. +This is done to keep a user from creating his/her own time stamp with a +bogus date on systems that allow users to give away files if the time +stamp directory is located in a world-writable directory. +.Pp +On systems where the boot time is available, +.Em sudoers +will ignore time stamps that date from before the machine booted. +.Pp +Since time stamp files live in the file system, they can outlive a +user's login session. +As a result, a user may be able to login, run a command with +.Nm sudo +after authenticating, logout, login again, and run +.Nm sudo +without authenticating so long as the time stamp file's modification +time is within +.Li @timeout@ +minutes (or whatever the timeout is set to in +.Em sudoers ) . +When the +.Em tty_tickets +option is enabled, the time stamp has per-tty granularity but still +may outlive the user's session. +On Linux systems where the devpts filesystem is used, Solaris systems +with the devices filesystem, as well as other systems that utilize a +devfs filesystem that monotonically increase the inode number of devices +as they are created (such as Mac OS X), +.Em sudoers +is able to determine when a tty-based time stamp file is stale and will +ignore it. +Administrators should not rely on this feature as it is not universally +available. +.Sh SEE ALSO +.Xr rsh 1 , +.Xr su 1 , +.Xr fnmatch 3 , +.Xr glob 3 , +.Xr mktemp 3 , +.Xr strftime 3 , +.Xr sudoers.ldap 5 , +.Xr sudo_plugin 8 , +.Xr sudo 8 , +.Xr visudo 8 +.Sh CAVEATS +The +.Em sudoers +file should +.Sy always +be edited by the +.Nm visudo +command which locks the file and does grammatical checking. +It is +imperative that +.Em sudoers +be free of syntax errors since +.Nm sudo +will not run with a syntactically incorrect +.Em sudoers +file. +.Pp +When using netgroups of machines (as opposed to users), if you +store fully qualified host name in the netgroup (as is usually the +case), you either need to have the machine's host name be fully qualified +as returned by the +.Li hostname +command or use the +.Em fqdn +option in +.Em sudoers . +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at http://www.sudo.ws/sudo/bugs/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or http://www.sudo.ws/sudo/license.html for complete details. diff --git a/doc/sudoreplay.mdoc.in b/doc/sudoreplay.mdoc.in new file mode 100644 index 000000000..3bb283a76 --- /dev/null +++ b/doc/sudoreplay.mdoc.in @@ -0,0 +1,374 @@ +.\" +.\" Copyright (c) 2009-2012 Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 12, 2012 +.Dt SUDOREPLAY 8 +.Os +.Sh NAME +.Nm sudoreplay +.Nd replay sudo session logs +.Sh SYNOPSIS +.Nm sudoreplay +.Op Fl h +.Bk -words +.Op Fl d Ar directory +.Ek +.Bk -words +.Op Fl f Ar filter +.Ek +.Bk -words +.Op Fl m Ar max_wait +.Ek +.Bk -words +.Op Fl s Ar speed_factor +.Ek +ID +.Pp +.Nm sudoreplay +.Op Fl h +.Bk -words +.Op Fl d Ar directory +.Ek +.Fl l +.Op search expression +.Sh DESCRIPTION +.Nm sudoreplay +plays back or lists the output logs created by +.Nm sudo . +When replaying, +.Nm sudoreplay +can play the session back in real-time, or the playback speed may be +adjusted (faster or slower) based on the command line options. +.Pp +The +.Em ID +should either be a six character sequence of digits and +upper case letters, e.g.\& +.Li 0100A5 , +or a pattern matching the +.Em iolog_file +option in the +.Em sudoers +file. +When a command is run via +.Nm sudo +with +.Em log_output +enabled in the +.Em sudoers +file, a +.Li TSID=ID +string is logged via syslog or to the +.Nm sudo +log file. +The +.Em ID +may also be determined using +.Nm sudoreplay Ns No 's +list mode. +.Pp +In list mode, +.Nm sudoreplay +can be used to find the ID of a session based on a number of criteria +such as the user, tty or command run. +.Pp +In replay mode, if the standard output has not been redirected, +.Nm sudoreplay +will act on the following keys: +.Bl -tag -width 12n +.It So Li \ Sc No (space) +Pause output; press any key to resume. +.It Ql < +Reduce the playback speed by one half. +.It Ql > +Double the playback speed. +.El +.Sh OPTIONS +.Nm sudoreplay +accepts the following command line options: +.Bl -tag -width 12n +.It Fl d Ar directory +Use +.Ar directory +to for the session logs instead of the default, +.Pa @iolog_dir@ . +.It Fl f Ar filter +By default, +.Nm sudoreplay +will play back the command's standard output, standard error and tty output. +The +.Fl f +option can be used to select which of these to output. +The +.Ar filter +argument is a comma-separated list, consisting of one or more of following: +.Em stdout , +.Em stderr , +and +.Em ttyout . +.It Fl h +The +.Fl h No ( Em help Ns No ) +option causes +.Nm sudoreplay +to print a short help message to the standard output and exit. +.It Fl l Op Ar search expression +Enable +.Dq list mode . +In this mode, +.Nm sudoreplay +will list available sessions in a format similar to the +.Nm sudo +log file format, sorted by file name (or sequence number). +If a +.Ar search expression +is specified, it will be used to restrict the IDs that are displayed. +An expression is composed of the following predicates: +.Bl -tag -width 6n +.It command Ar pattern +Evaluates to true if the command run matches +.Ar pattern . +On systems with POSIX regular expression support, the pattern may +be an extended regular expression. +On systems without POSIX regular expression support, a simple substring +match is performed instead. +.It cwd Ar directory +Evaluates to true if the command was run with the specified current +working directory. +.It fromdate Ar date +Evaluates to true if the command was run on or after +.Ar date . +See +.Sx Date and time format +for a description of supported date and time formats. +.It group Ar runas_group +Evaluates to true if the command was run with the specified +.Ar runas_group . +Note that unless a +.Ar runas_group +was explicitly specified when +.Nm sudo +was run this field will be empty in the log. +.It runas Ar runas_user +Evaluates to true if the command was run as the specified +.Ar runas_user . +Note that +.Nm sudo +runs commands as user +.Em root +by default. +.It todate Ar date +Evaluates to true if the command was run on or prior to +.Ar date . +See +.Sx Date and time format +for a description of supported date and time formats. +.It tty Ar tty name +Evaluates to true if the command was run on the specified terminal device. +The +.Ar tty name +should be specified without the +.Pa /dev/ +prefix, e.g.\& +.Pa tty01 +instead of +.Pa /dev/tty01 . +.It user Ar user name +Evaluates to true if the ID matches a command run by +.Ar user name . +.El +.Pp +Predicates may be abbreviated to the shortest unique string (currently +all predicates may be shortened to a single character). +.Pp +Predicates may be combined using +.Em and , +.Em or +and +.Em \&! +operators as well as +.Ql \&( +and +.Ql \&) +grouping (note that parentheses must generally be escaped from the shell). +The +.Em and +operator is optional, adjacent predicates have an implied +.Em and +unless separated by an +.Em or . +.It Fl m Ar max_wait +Specify an upper bound on how long to wait between key presses or output data. +By default, +.Nm sudoreplay +will accurately reproduce the delays between key presses or program output. +However, this can be tedious when the session includes long pauses. +When the +.Fl m +option is specified, +.Nm sudoreplay +will limit these pauses to at most +.Em max_wait +seconds. +The value may be specified as a floating point number, e.g.\& +.Em 2.5 . +.It Fl s Ar speed_factor +This option causes +.Nm sudoreplay +to adjust the number of seconds it will wait between key presses or +program output. +This can be used to slow down or speed up the display. +For example, a +.Ar speed_factor +of +.Em 2 +would make the output twice as fast whereas a +.Ar speed_factor +of +.Em .5 +would make the output twice as slow. +.It Fl V +The +.Fl V No ( Em version Ns No ) +option causes +.Nm sudoreplay +to print its version number +and exit. +.El +.Ss Date and time format +The time and date may be specified multiple ways, common formats include: +.Bl -tag -width 6n +.It HH:MM:SS am MM/DD/CCYY timezone +24 hour time may be used in place of am/pm. +.It HH:MM:SS am Month, Day Year timezone +24 hour time may be used in place of am/pm, and month and day names +may be abbreviated. +Note that month and day of the week names must be specified in English. +.It CCYY-MM-DD HH:MM:SS +ISO time format +.It DD Month CCYY HH:MM:SS +The month name may be abbreviated. +.El +.Pp +Either time or date may be omitted, the am/pm and timezone are optional. +If no date is specified, the current day is assumed; if no time is +specified, the first second of the specified date is used. +The less significant parts of both time and date may also be omitted, +in which case zero is assumed. +.Pp +The following are all valid time and date specifications: +.Bl -tag -width 6n +.It now +The current time and date. +.It tomorrow +Exactly one day from now. +.It yesterday +24 hours ago. +.It 2 hours ago +2 hours ago. +.It next Friday +The first second of the next Friday. +.It this week +The current time but the first day of the coming week. +.It a fortnight ago +The current time but 14 days ago. +.It 10:01 am 9/17/2009 +10:01 am, September 17, 2009. +.It 10:01 am +10:01 am on the current day. +.It 10 +10:00 am on the current day. +.It 9/17/2009 +00:00 am, September 17, 2009. +.It 10:01 am Sep 17, 2009 +10:01 am, September 17, 2009. +.El +.Sh FILES +.Bl -tag -width 24n +.It Pa @iolog_dir@ +The default I/O log directory. +.It Pa @iolog_dir@/00/00/01/log +Example session log info. +.It Pa @iolog_dir@/00/00/01/stdin +Example session standard input log. +.It Pa @iolog_dir@/00/00/01/stdout +Example session standard output log. +.It Pa @iolog_dir@/00/00/01/stderr +Example session standard error log. +.It Pa @iolog_dir@/00/00/01/ttyin +Example session tty input file. +.It Pa @iolog_dir@/00/00/01/ttyout +Example session tty output file. +.It Pa @iolog_dir@/00/00/01/timing +Example session timing file. +.El +.Pp +Note that the +.Em stdin , +.Em stdout +and +.Em stderr +files will be empty unless +.Nm sudo +was used as part of a pipeline for a particular command. +.Sh EXAMPLES +List sessions run by user +.Em millert : +.Bd -literal -offset indent +# sudoreplay -l user millert +.Ed +.Pp +List sessions run by user +.Em bob +with a command containing the string vi: +.Bd -literal -offset indent +# sudoreplay -l user bob command vi +.Ed +.Pp +List sessions run by user +.Em jeff +that match a regular expression: +.Bd -literal -offset indent +# sudoreplay -l user jeff command '/bin/[a-z]*sh' +.Ed +.Pp +List sessions run by jeff or bob on the console: +.Bd -literal -offset indent +# sudoreplay -l ( user jeff or user bob ) tty console +.Ed +.Sh SEE ALSO +.Xr sudo 8 , +.Xr script 1 +.Sh AUTHORS +Todd C. Miller +.Sh BUGS +If you feel you have found a bug in +.Nm sudoreplay , +please submit a bug report at http://www.sudo.ws/sudo/bugs/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudoreplay +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or http://www.sudo.ws/sudo/license.html for complete details. diff --git a/doc/visudo.mdoc.in b/doc/visudo.mdoc.in new file mode 100644 index 000000000..7efa0a2c1 --- /dev/null +++ b/doc/visudo.mdoc.in @@ -0,0 +1,319 @@ +.\" +.\" Copyright (c) 1996,1998-2005, 2007-2012 +.\" Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.Dd July 12, 2012 +.Dt VISUDO 8 +.Os +.Sh NAME +.Nm visudo +.Nd edit the sudoers file +.Sh SYNOPSIS +.Nm visudo +.Op Fl chqsV +.Bk -words +.Op Fl f Ar sudoers +.Ek +.Sh DESCRIPTION +.Nm visudo +edits the +.Em sudoers +file in a safe fashion, analogous to +.Xr vipw 8 . +.Nm visudo +locks the +.Em sudoers +file against multiple simultaneous edits, provides basic sanity checks, +and checks for parse errors. +If the +.Em sudoers +file is currently being edited you will receive a message to try again later. +.Pp +There is a hard-coded list of one or more editors that +.Nm visudo +will use set at compile-time that may be overridden via the +.Em editor +.Em sudoers +.Li Default +variable. +This list defaults to +.Li "@editor@" . +Normally, +.Nm visudo +does not honor the +.Ev VISUAL +or +.Ev EDITOR +environment variables unless they contain an editor in the aforementioned +editors list. +However, if +.Nm visudo +is configured with the +.Li --with-env-editor +option or the +.Em env_editor +.Li Default +variable is set in +.Em sudoers , +.Nm visudo +will use any the editor defines by +.Ev VISUAL +or +.Ev EDITOR . +Note that this can be a security hole since it allows the user to +execute any program they wish simply by setting +.Ev VISUAL +or +.Ev EDITOR . +.Pp +.Nm visudo +parses the +.Em sudoers +file after the edit and will +not save the changes if there is a syntax error. +Upon finding an error, +.Nm visudo +will print a message stating the line number(s) +where the error occurred and the user will receive the +.Dq What now? +prompt. +At this point the user may enter +.Ql e +to re-edit the +.Em sudoers +file, +.Ql x +to exit without saving the changes, or +.Ql Q +to quit and save changes. +The +.Ql Q +option should be used with extreme care because if +.Nm visudo +believes there to be a parse error, so will +.Nm sudo +and no one +will be able to +.Nm sudo +again until the error is fixed. +If +.Ql e +is typed to edit the +.Em sudoers +file after a parse error has been detected, the cursor will be placed on +the line where the error occurred (if the editor supports this feature). +.Sh OPTIONS +.Nm visudo +accepts the following command line options: +accepts the following command line options: +.Bl -tag -width Fl +.It Fl c +Enable +.Em check-only +mode. +The existing +.Em sudoers +file will be +checked for syntax errors, owner and mode. +A message will be printed to the standard output describing the status of +.Em sudoers +unless the +.Fl q +option was specified. +If the check completes successfully, +.Nm visudo +will exit with a value of 0. +If an error is encountered, +.Nm visudo +will exit with a value of 1. +.It Fl f Ar sudoers +Specify and alternate +.Em sudoers +file location. +With this option +.Nm visudo +will edit (or check) the +.Em sudoers +file of your choice, +instead of the default, +.Pa @sysconfdir@/sudoers . +The lock file used is the specified +.Em sudoers +file with +.Dq \.tmp +appended to it. +In +.Em check-only +mode only, the argument to +.Fl f +may be +.Ql - , +indicating that +.Em sudoers +will be read from the standard input. +.It Fl h +The +.Fl h No ( Em help Ns No ) +option causes +.Nm visudo +to print a short help message +to the standard output and exit. +.It Fl q +Enable +.Em quiet +mode. +In this mode details about syntax errors are not printed. +This option is only useful when combined with +the +.Fl c +option. +.It Fl s +Enable +.Em strict +checking of the +.Em sudoers +file. +If an alias is used before it is defined, +.Nm visudo +will consider this a parse error. +Note that it is not possible to differentiate between an +alias and a host name or user name that consists solely of uppercase +letters, digits, and the underscore +.Pq Ql _ +character. +.It Fl V +The +.Fl V ( Em version Ns No ) +option causes +.Nm visudo +to print its version number +and exit. +.El +.Sh ENVIRONMENT +The following environment variables may be consulted depending on +the value of the +.Em editor +and +.Em env_editor +.Em sudoers +settings: +.Bl -tag -width 15n +.It Ev VISUAL +Invoked by +.Nm visudo +as the editor to use +.It Ev EDITOR +Used by +.Nm visudo +if +.Ev VISUAL +is not set +.El +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudoers +List of who can run what +.It Pa @sysconfdir@/sudoers.tmp +Lock file for visudo +.El +.Sh DIAGNOSTICS +.Bl -tag -width 4n +.It Li sudoers file busy, try again later. +Someone else is currently editing the +.Em sudoers +file. +.It Li @sysconfdir@/sudoers.tmp: Permission denied +You didn't run +.Nm visudo +as root. +.It Li Can't find you in the passwd database +Your user ID does not appear in the system passwd file. +.It Li Warning: {User,Runas,Host,Cmnd}_Alias referenced but not defined +Either you are trying to use an undeclared {User,Runas,Host,Cmnd}_Alias +or you have a user or host name listed that consists solely of +uppercase letters, digits, and the underscore +.Pq Ql _ +character. +In the latter case, you can ignore the warnings +.Po +.Nm sudo +will not complain +.Pc . +In +.Fl s +(strict) mode these are errors, not warnings. +.It Li Warning: unused {User,Runas,Host,Cmnd}_Alias +The specified {User,Runas,Host,Cmnd}_Alias was defined but never +used. +You may wish to comment out or remove the unused alias. +In +.Fl s +(strict) mode this is an error, not a warning. +.It Li Warning: cycle in {User,Runas,Host,Cmnd}_Alias +The specified {User,Runas,Host,Cmnd}_Alias includes a reference to +itself, either directly or through an alias it includes. +This is only a warning by default as +.Nm sudo +will ignore cycles when parsing +the +.Em sudoers +file. +.El +.Sh SEE ALSO +.Xr vi 1 , +.Xr sudoers 5 , +.Xr sudo 8 , +.Xr vipw 8 +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (http://www.sudo.ws/sudo/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh CAVEATS +There is no easy way to prevent a user from gaining a root shell if +the editor used by +.Nm visudo +allows shell escapes. +.Sh BUGS +If you feel you have found a bug in +.Nm visudo , +please submit a bug report at http://www.sudo.ws/sudo/bugs/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm visudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or http://www.sudo.ws/sudo/license.html for complete details.