-Copyright (c) 1994-1996, 1998-2005, 2007-2011
+Copyright (c) 1994-1996, 1998-2005, 2007-2012
Todd C. Miller <Todd.Miller@courtesan.com>
Permission to use, copy, modify, and distribute this software for any
distinct ways I<sudoers> can deal with environment variables.
By default, the I<env_reset> option is enabled. This causes commands
-to be executed with a minimal environment containing C<TERM>,
-C<PATH>, C<HOME>, C<MAIL>, C<SHELL>, C<LOGNAME>, C<USER> and C<USERNAME> in
-addition to variables from the invoking process permitted by the
+to be executed with a new, minimal environment. On AIX (and Linux
+systems without PAM), the environment is initialized with the
+contents of the F</etc/environment> file. On BSD systems, if the
+I<use_loginclass> option is enabled, the environment is initialized
+based on the I<path> and I<setenv> settings in F</etc/login.conf>.
+The new environment contains the C<TERM>, C<PATH>, C<HOME>, C<MAIL>,
+C<SHELL>, C<LOGNAME>, C<USER>, C<USERNAME> and C<SUDO_*> variables
+in addition to variables from the invoking process permitted by the
I<env_check> and I<env_keep> options. This is effectively a whitelist
for environment variables.
specified, I<sudoers> will initialize the environment regardless
of the value of I<env_reset>. The I<DISPLAY>, I<PATH> and I<TERM>
variables remain unchanged; I<HOME>, I<MAIL>, I<SHELL>, I<USER>,
-and I<LOGNAME> are set based on the target user. On Linux and AIX
-systems the contents of F</etc/environment> are also included. All
-other environment variables are removed.
+and I<LOGNAME> are set based on the target user. On AIX (and Linux
+systems without PAM), the contents of F</etc/environment> are also
+included. On BSD systems, if the I<use_loginclass> option is
+enabled, the I<path> and I<setenv> variables in F</etc/login.conf>
+are also applied. All other environment variables are removed.
+
+Finally, if the I<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.
=head1 SUDOERS FILE FORMAT
aaron shanty = NOEXEC: /usr/bin/more, /usr/bin/vi
-See the L<PREVENTING SHELL ESCAPES> section below for more details
+See the L<Preventing Shell Escapes> section below for more details
on how C<NOEXEC> works and whether or not it will work on your system.
=head3 SETENV and NOSETENV
themselves include other files. A hard limit of 128 nested include
files is enforced to prevent include file loops.
-The file name may include the C<%h> escape, signifying the short form
+If the path to the include file is not fully-qualified (does not
+begin with a F</>), it must be located in the same directory as the
+sudoers file it was included from. For example, if F</etc/sudoers>
+contains the line:
+
+=over 4
+
+C<#include sudoers.local>
+
+=back
+
+the file that will be included is F</etc/sudoers.local>.
+
+The file name may also include the C<%h> escape, signifying the short form
of the host name. I.e., if the machine's host name is "xerxes", then
C<#include /etc/sudoers.%h>
=item env_reset
-If set, B<sudo> will reset the environment to only contain the
-LOGNAME, MAIL, SHELL, USER, USERNAME and the C<SUDO_*> variables. Any
+If set, B<sudo> will run the command in a minimal environment
+containing the C<TERM>, C<PATH>, C<HOME>, C<MAIL>, C<SHELL>,
+C<LOGNAME>, C<USER>, C<USERNAME> and C<SUDO_*> variables. Any
variables in the caller's environment that match the C<env_keep>
-and C<env_check> lists are then added. The default contents of the
-C<env_keep> and C<env_check> lists are displayed when B<sudo> is
-run by root with the I<-V> option. If the I<secure_path> option
-is set, its value will be used for the C<PATH> environment variable.
-This flag is I<@env_reset@> by default.
+and C<env_check> lists are then added, followed by any variables
+present in the file specified by the I<env_file> option (if any).
+The default contents of the C<env_keep> and C<env_check> lists are
+displayed when B<sudo> is run by root with the I<-V> option. If
+the I<secure_path> option is set, its value will be used for the
+C<PATH> environment variable. This flag is I<@env_reset@> by
+default.
=item fast_glob
If set, all commands run via B<sudo> will behave as if the C<NOEXEC>
tag has been set, unless overridden by a C<EXEC> tag. See the
-description of I<NOEXEC and EXEC> below as well as the L<PREVENTING SHELL
-ESCAPES> section at the end of this manual. This flag is I<off> by default.
+description of I<NOEXEC and EXEC> below as well as the L<Preventing Shell
+Escapes> section at the end of this manual. This flag is I<off> by default.
=item path_info
=item noexec_file
-This option is deprecated and will be removed in a future release
-of B<sudo>. The path to the noexec file should now be set in the
-F<@sysconfdir@/sudo.conf> file.
+This option is no longer supported. The path to the noexec file
+should now be set in the F<@sysconfdir@/sudo.conf> file.
=item passprompt
=item env_file
-The I<env_file> options specifies the fully qualified path to a
+The I<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
C<VARIABLE=value> or C<export VARIABLE=value>. The value may
=back
+=head1 SUDO.CONF
+
+The F<@sysconfdir@/sudo.conf> file determines which plugins the
+B<sudo> front end will load. If no F<@sysconfdir@/sudo.conf> file
+is present, or it contains no C<Plugin> lines, B<sudo> will use the
+I<sudoers> security policy and I/O logging, which corresponds to
+the following F<@sysconfdir@/sudo.conf> file.
+
+ #
+ # 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
+
+=head2 PLUGIN OPTIONS
+
+Starting with B<sudo> 1.8.5 it is possible to pass options to the
+I<sudoers> plugin. Options may be listed after the path to the
+plugin (i.e. after F<sudoers.so>); multiple options should be
+space-separated. For example:
+
+ Plugin sudoers_policy sudoers.so sudoers_file=/etc/sudoers sudoers_uid=0 sudoers_gid=0 sudoers_mode=0440
+
+The following plugin options are supported:
+
+=over 10
+
+=item sudoers_file=pathname
+
+The I<sudoers_file> option can be used to override the default path
+to the I<sudoers> file.
+
+=item sudoers_uid=uid
+
+The I<sudoers_uid> option can be used to override the default owner
+of the sudoers file. It should be specified as a numeric user ID.
+
+=item sudoers_gid=gid
+
+The I<sudoers_gid> option can be used to override the default group
+of the sudoers file. It should be specified as a numeric group ID.
+
+=item sudoers_mode=mode
+
+The I<sudoers_mode> option can be used to override the default file
+mode for the sudoers file. It should be specified as an octal value.
+
+=back
+
+=head2 DEBUG FLAGS
+
+Versions 1.8.4 and higher of the I<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 F<@sysconfdir@/sudo.conf> file as described in L<sudo(8)>.
+
+The I<sudoers> plugin uses the same debug flag format as B<sudo>
+itself: I<subsystem>@I<priority>.
+
+The priorities used by I<sudoers>, in order of decreasing severity,
+are: I<crit>, I<err>, I<warn>, I<notice>, I<diag>, I<info>, I<trace>
+and I<debug>. Each priority, when specified, also includes all
+priorities higher than it. For example, a priority of I<notice>
+would include debug messages logged at I<notice> and higher.
+
+The following subsystems are used by I<sudoers>:
+
+=over 10
+
+=item I<alias>
+
+C<User_Alias>, C<Runas_Alias>, C<Host_Alias> and C<Cmnd_Alias> processing
+
+=item I<all>
+
+matches every subsystem
+
+=item I<audit>
+
+BSM and Linux audit code
+
+=item I<auth>
+
+user authentication
+
+=item I<defaults>
+
+I<sudoers> I<Defaults> settings
+
+=item I<env>
+
+environment handling
+
+=item I<ldap>
+
+LDAP-based sudoers
+
+=item I<logging>
+
+logging support
+
+=item I<match>
+
+matching of users, groups, hosts and netgroups in I<sudoers>
+
+=item I<netif>
+
+network interface handling
+
+=item I<nss>
+
+network service switch handling in I<sudoers>
+
+=item I<parser>
+
+I<sudoers> file parsing
+
+=item I<perms>
+
+permission setting
+
+=item I<plugin>
+
+The equivalent of I<main> for the plugin.
+
+=item I<pty>
+
+pseudo-tty related code
+
+=item I<rbtree>
+
+redblack tree internals
+
+=item I<util>
+
+utility functions
+
+=back
+
=head1 FILES
=over 24
+=item F<@sysconfdir@/sudo.conf>
+
+Sudo front end configuration
+
=item F<@sysconfdir@/sudoers>
List of who can run what
=item F</etc/environment>
-Initial environment for B<-i> mode on Linux and AIX
+Initial environment for B<-i> mode on AIX and Linux systems
=back
=head1 SECURITY NOTES
+=head2 Limitations of the '!' operator
+
It is generally not effective to "subtract" commands from C<ALL>
using the '!' operator. A user can trivially circumvent this
by copying the desired command to a different name and then
program. Therefore, these kind of restrictions should be considered
advisory at best (and reinforced by policy).
-Furthermore, if the I<fast_glob> option is in use, it is not possible
+In general, if a user has sudo C<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 '!' elements
+in the user specification.
+
+=head2 Security implications of I<fast_glob>
+
+If the I<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
L<fnmatch(3)> function cannot resolve relative paths. While this
User B<john> can still run C</usr/bin/passwd root> if I<fast_glob> is
enabled by changing to F</usr/bin> and running C<./passwd root> instead.
-=head1 PREVENTING SHELL ESCAPES
+=head2 Preventing Shell Escapes
Once B<sudo> executes a program, that program is free to do whatever
it pleases, including run other programs. This can be a security
editor, a safer approach is to give the user permission to run
B<sudoedit>.
-=head1 SECURITY NOTES
+=head2 Time stamp file checks
I<sudoers> will check the ownership of its time stamp directory
(F<@timedir@> by default) and ignore the directory's contents if
tty-based time stamp file is stale and will ignore it. Administrators
should not rely on this feature as it is not universally available.
-If users have sudo C<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 '!' elements in the
-user specification.
-
=head1 SEE ALSO
L<rsh(1)>, L<su(1)>, L<fnmatch(3)>, L<glob(3)>, L<mktemp(3)>, L<strftime(3)>,