Imported Upstream version 1.6.9p6
[debian/sudo] / sudo.pod
index 3b913d48c146fc850cb0300256bfc69bc7ce1dd9..694ae3627f05876a61b492bcc02dc91fd1b37b35 100644 (file)
--- a/sudo.pod
+++ b/sudo.pod
@@ -1,5 +1,6 @@
 =cut
-Copyright (c) 1994-1996,1998-2003 Todd C. Miller <Todd.Miller@courtesan.com>
+Copyright (c) 1994-1996, 1998-2005, 2007
+       Todd C. Miller <Todd.Miller@courtesan.com>
 
 Permission to use, copy, modify, and distribute this software for any
 purpose with or without fee is hereby granted, provided that the above
@@ -18,7 +19,7 @@ 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.
 
-$Sudo: sudo.pod,v 1.73 2004/09/08 18:34:38 millert Exp $
+$Sudo: sudo.pod,v 1.70.2.18 2007/08/13 16:23:31 millert Exp $
 =pod
 
 =head1 NAME
@@ -27,15 +28,15 @@ sudo, sudoedit - execute a command as another user
 
 =head1 SYNOPSIS
 
-B<sudo> B<-K> | B<-L> | B<-V> | B<-h> | B<-k> | B<-l> | B<-v>
+B<sudo> B<-h> | B<-K> | B<-k> | B<-L> | B<-l> | B<-V> | B<-v>
 
-B<sudo> [B<-HPSb>] S<[B<-a> I<auth_type>]> S<[B<-c> I<class>|I<->]>
-S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
-S<{B<-e> file [...] | B<-i> | B<-s> | I<command>}>
+B<sudo> [B<-bEHPS>] S<[B<-a> I<auth_type>]>
+S<[B<-c> I<class>|I<->]> S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
+S<[B<VAR>=I<value>]> S<{B<-i> | B<-s> | I<command>}>
 
-B<sudoedit> [B<-S>] S<[B<-a> I<auth_type>]>
+B<sudoedit> [B<-S>] S<[B<-a> I<auth_type>]> S<[B<-c> I<class>|I<->]>
 S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
-file [...]
+file ...
 
 =head1 DESCRIPTION
 
@@ -57,8 +58,8 @@ When invoked as B<sudoedit>, the B<-e> option (described below),
 is implied.
 
 B<sudo> determines who is an authorized user by consulting the file
-F<@sysconfdir@/sudoers>.  By giving B<sudo> the B<-v> flag a user
-can update the time stamp without running a I<command.> The password
+F<@sysconfdir@/sudoers>.  By giving B<sudo> the B<-v> flag, a user
+can update the time stamp without running a I<command>. The password
 prompt itself will also time out if the user's password is not
 entered within C<@password_timeout@> minutes (unless overridden via
 I<sudoers>).
@@ -90,54 +91,14 @@ B<sudo> accepts the following command line options:
 
 =over 4
 
-=item -H
-
-The B<-H> (I<HOME>) option sets the C<HOME> environment variable
-to the homedir of the target user (root by default) as specified
-in passwd(@mansectform@).  By default, B<sudo> does not modify C<HOME>
-(see I<set_home> and I<always_set_home> in L<sudoers(@mansectform@)>).
-
-=item -K
-
-The B<-K> (sure I<kill>) option is like B<-k> except that it removes
-the user's timestamp entirely.  Like B<-k>, this option does not
-require a password.
-
-=item -L
-
-The B<-L> (I<list> defaults) option will list out the parameters
-that may be set in a I<Defaults> line along with a short description
-for each.  This option is useful in conjunction with grep(1).
-
-=item -P
-
-The B<-P> (I<preserve group vector>) option causes B<sudo> to
-preserve the invoking user's group vector unaltered.  By default,
-B<sudo> 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.
-
-=item -S
-
-The B<-S> (I<stdin>) option causes B<sudo> to read the password from
-the standard input instead of the terminal device.
-
-=item -V
-
-The B<-V> (I<version>) option causes B<sudo> to print the version
-number and exit.  If the invoking user is already root the B<-V>
-option will print out a list of the defaults B<sudo> was compiled
-with as well as the machine's local network addresses.
-
 =item -a
 
 The B<-a> (I<authentication type>) option causes B<sudo> to use the
 specified authentication type when validating the user, as allowed
-by /etc/login.conf.  The system administrator may specify a list
+by F</etc/login.conf>.  The system administrator may specify a list
 of sudo-specific authentication methods by adding an "auth-sudo"
-entry in /etc/login.conf.  This option is only available on systems
-that support BSD authentication where B<sudo> has been configured
-with the --with-bsdauth option.
+entry in F</etc/login.conf>.  This option is only available on systems
+that support BSD authentication.
 
 =item -b
 
@@ -149,14 +110,20 @@ option you cannot use shell job control to manipulate the process.
 
 The B<-c> (I<class>) option causes B<sudo> to run the specified command
 with resources limited by the specified login class.  The I<class>
-argument can be either a class name as defined in /etc/login.conf,
+argument can be either a class name as defined in C</etc/login.conf>,
 or a single '-' character.  Specifying a I<class> of C<-> indicates
 that the command should be run restricted by the default login
 capabilities for the user the command is run as.  If the I<class>
 argument specifies an existing user class, the command must be run
 as root, or the B<sudo> command must be run from a shell that is already
-root.  This option is only available on systems with BSD login classes
-where B<sudo> has been configured with the --with-logincap option.
+root.  This option is only available on systems with BSD login classes.
+
+=item -E
+
+The B<-E> (I<preserve> I<environment>) option will override the
+I<env_reset> option in L<sudoers(5)>).  It is only
+available when either the matching command has the C<SETENV> tag
+or the I<setenv> option is set in L<sudoers(5)>.
 
 =item -e
 
@@ -166,7 +133,7 @@ of a command, the string "sudoedit" is used when consulting
 the I<sudoers> file.  If the user is authorized by I<sudoers>
 the following steps are taken:
 
-=over 8
+=over 4
 
 =item 1.
 
@@ -194,6 +161,13 @@ B<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.
 
+=item -H
+
+The B<-H> (I<HOME>) option sets the C<HOME> environment variable
+to the homedir of the target user (root by default) as specified
+in passwd(5).  By default, B<sudo> does not modify C<HOME>
+(see I<set_home> and I<always_set_home> in L<sudoers(5)>).
+
 =item -h
 
 The B<-h> (I<help>) option causes B<sudo> to print a usage message and exit.
@@ -201,9 +175,9 @@ The B<-h> (I<help>) option causes B<sudo> to print a usage message and exit.
 =item -i
 
 The B<-i> (I<simulate initial login>) option runs the shell specified
-in the L<passwd(@mansectform@)> entry of the user that the command is
+in the L<passwd(5)> entry of the user that the command is
 being run as.  The command name argument given to the shell begins
-with a C<-> to tell the shell to run as a login shell.  B<sudo>
+with a `C<->' to tell the shell to run as a login shell.  B<sudo>
 attempts to change to that user's home directory before running the
 shell.  It also initializes the environment, leaving I<TERM>
 unchanged, setting I<HOME>, I<SHELL>, I<USER>, I<LOGNAME>, and
@@ -213,18 +187,38 @@ is parsed, a I<runas_default> setting in I<sudoers> will specify
 the user to run the shell as but will not affect which shell is
 actually run.
 
+=item -K
+
+The B<-K> (sure I<kill>) option is like B<-k> except that it removes
+the user's timestamp entirely.  Like B<-k>, this option does not
+require a password.
+
 =item -k
 
 The B<-k> (I<kill>) option to B<sudo> invalidates the user's timestamp
-by setting the time on it to the epoch.  The next time B<sudo> is
+by setting the time on it to the Epoch.  The next time B<sudo> is
 run a password will be required.  This option does not require a password
 and was added to allow a user to revoke B<sudo> permissions from a .logout
 file.
 
+=item -L
+
+The B<-L> (I<list> defaults) option will list out the parameters
+that may be set in a I<Defaults> line along with a short description
+for each.  This option is useful in conjunction with L<grep(1)>.
+
 =item -l
 
 The B<-l> (I<list>) option will list out the allowed (and
-forbidden) commands for the user on the current host.
+forbidden) commands for the invoking user on the current host.
+
+=item -P
+
+The B<-P> (I<preserve> I<group vector>) option causes B<sudo> to
+preserve the invoking user's group vector unaltered.  By default,
+B<sudo> 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.
 
 =item -p
 
@@ -232,26 +226,26 @@ The B<-p> (I<prompt>) option allows you to override the default
 password prompt and use a custom one.  The following percent (`C<%>')
 escapes are supported:
 
-=over 8
+=over 4
 
-=item C<%u>
+=item C<%H>
 
-expanded to the invoking user's login name
+expanded to the local hostname including the domain name
+(on if the machine's hostname is fully qualified or the I<fqdn>
+I<sudoers> option is set)
+
+=item C<%h>
+
+expanded to the local hostname without the domain name
 
 =item C<%U>
 
 expanded to the login name of the user the command will
 be run as (defaults to root)
 
-=item C<%h>
-
-expanded to the local hostname without the domain name
-
-=item C<%H>
+=item C<%u>
 
-expanded to the local hostname including the domain name
-(on if the machine's hostname is fully qualified or the I<fqdn>
-sudoers option is set)
+expanded to the invoking user's login name
 
 =item C<%%>
 
@@ -259,19 +253,33 @@ two consecutive C<%> characters are collapsed into a single C<%> character
 
 =back
 
+=item -S
+
+The B<-S> (I<stdin>) option causes B<sudo> to read the password from
+the standard input instead of the terminal device.
+
 =item -s
 
 The B<-s> (I<shell>) option runs the shell specified by the I<SHELL>
 environment variable if it is set or the shell as specified
-in L<passwd(@mansectform@)>.
+in L<passwd(5)>.
 
 =item -u
 
-The B<-u> (I<user>) option causes B<sudo> to run the specified command
-as a user other than I<root>.  To specify a I<uid> instead of a
-I<username>, use I<#uid>.  Note that if the I<targetpw> Defaults
-option is set (see L<sudoers(@mansectform@)>) it is not possible
-to run commands with a uid not listed in the password database.
+The B<-u> (I<user>) option causes B<sudo> to run the specified
+command as a user other than I<root>.  To specify a I<uid> instead
+of a I<username>, use I<#uid>.  When running commands as a I<uid>,
+many shells require that the '#' be escaped with a backslash ('\').
+Note that if the I<targetpw> Defaults option is set (see L<sudoers(5)>)
+it is not possible to run commands with a uid not listed in the
+password database.
+
+=item -V
+
+The B<-V> (I<version>) option causes B<sudo> to print the version
+number and exit.  If the invoking user is already root the B<-V>
+option will print out a list of the defaults B<sudo> was compiled
+with as well as the machine's local network addresses.
 
 =item -v
 
@@ -288,6 +296,15 @@ line arguments.  It is most useful in conjunction with the B<-s> flag.
 
 =back
 
+Environment variables to be set for the command may also be passed
+on the command line in the form of B<VAR>=I<value>, e.g.
+B<LD_LIBRARY_PATH>=I</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 I<setenv> option
+is set in I<sudoers> or the command to be run has the C<SETENV> tag
+set the user may set variables that would overwise be forbidden.
+See L<sudoers(5)> for more information.
+
 =head1 RETURN VALUES
 
 Upon successful execution of a program, the return value from B<sudo>
@@ -307,25 +324,35 @@ unreachable.
 
 =head1 SECURITY NOTES
 
-B<sudo> tries to be safe when executing external commands.  Variables
-that control how dynamic loading and binding is done can be used
-to subvert the program that B<sudo> runs.  To combat this the
-C<LD_*>, C<_RLD_*>, C<SHLIB_PATH> (HP-UX only), and C<LIBPATH> (AIX
-only) environment variables are removed from the environment passed
-on to all commands executed.  B<sudo> will also remove the C<IFS>,
-C<CDPATH>, C<ENV>, C<BASH_ENV>, C<KRB_CONF>, C<KRBCONFDIR>, C<KRBTKFILE>,
-C<KRB5_CONFIG>, C<LOCALDOMAIN>, C<RES_OPTIONS>, C<HOSTALIASES>,
-C<NLSPATH>, C<PATH_LOCALE>, C<TERMINFO>, C<TERMINFO_DIRS> and
-C<TERMPATH> variables as they too can pose a threat.  If the
-C<TERMCAP> variable is set and is a pathname, it too is ignored.
-Additionally, if the C<LC_*> or C<LANGUAGE> variables contain the
-C</> or C<%> characters, they are ignored.  Environment variables
-with a value beginning with C<()> are also removed as they could
-be interpreted as B<bash> functions.  If B<sudo> has been
-compiled with SecurID support, the C<VAR_ACE>, C<USR_ACE> and
-C<DLC_ACE> variables are cleared as well.  The list of environment
-variables that B<sudo> clears is contained in the output of
-C<sudo -V> when run as root.
+B<sudo> tries to be safe when executing external commands.
+
+There are two distinct ways to deal with environment variables.
+By default, the I<env_reset> I<sudoers> option is enabled.
+This causes commands to be executed with a minimal environment
+containing C<TERM>, C<PATH>, C<HOME>, C<SHELL>, C<LOGNAME>, C<USER>
+and C<USERNAME> in addition to variables from the invoking process
+permitted by the I<env_check> and I<env_keep> I<sudoers> options.
+There is effectively a whitelist for environment variables.
+
+If, however, the I<env_reset> option is disabled in I<sudoers>, any
+variables not explicitly denied by the I<env_check> and I<env_delete>
+options are inherited from the invoking process.  In this case,
+I<env_check> and I<env_delete> behave like a blacklist.  Since it
+is not possible to blacklist all potentially dangerous environment
+variables, use of the default I<env_reset> behavior is encouraged.
+
+In all cases, environment variables with a value beginning with
+C<()> are removed as they could be interpreted as B<bash> functions.
+The list of environment variables that B<sudo> allows or denies is
+contained in the output of C<sudo -V> when run as root.
+
+Note that the dynamic linker on most operating systems will remove
+variables that can control dynamic linking from the environment of
+setuid executables, including B<sudo>.  Depending on the operating
+system this may include C<_RLD*>, C<DYLD_*>, C<LD_*>, C<LDR_*>,
+C<LIBPATH>, C<SHLIB_PATH>, and others.  These type of variables are
+removed from the environment before B<sudo> even begins execution
+and, as such, it is not possible for B<sudo> to preserve them.
 
 To prevent command spoofing, B<sudo> checks "." and "" (both denoting
 current directory) last when searching for a command in the user's
@@ -333,27 +360,22 @@ PATH (if one or both are in the PATH).  Note, however, that the
 actual C<PATH> environment variable is I<not> modified and is passed
 unchanged to the program that B<sudo> executes.
 
-For security reasons, if your OS supports shared libraries and does
-not disable user-defined library search paths for setuid programs
-(most do), you should either use a linker option that disables this
-behavior or link B<sudo> statically.
-
 B<sudo> will check the ownership of its timestamp directory
 (F<@timedir@> by default) and ignore the directory's contents if
-it is not owned by root and only writable by root.  On systems that
-allow non-root users to give away files via L<chown(2)>, if the timestamp
-directory is located in a directory writable by anyone (e.g.: F</tmp>),
-it is possible for a user to create the timestamp directory before
-B<sudo> is run.  However, because B<sudo> checks the ownership and
-mode of the directory and its contents, the only damage that can
-be done is to "hide" files by putting them in the timestamp dir.
-This is unlikely to happen since once the timestamp dir is owned
-by root and inaccessible by any other user the user placing files
-there would be unable to get them back out.  To get around this
-issue you can use a directory that is not world-writable for the
-timestamps (F</var/adm/sudo> for instance) or create F<@timedir@>
-with the appropriate owner (root) and permissions (0700) in the
-system startup files.
+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
+L<chown(2)>, if the timestamp directory is located in a directory
+writable by anyone (e.g., F</tmp>), it is possible for a user to
+create the timestamp directory before B<sudo> is run.  However,
+because B<sudo> checks the ownership and mode of the directory and
+its contents, the only damage that can be done is to "hide" files
+by putting them in the timestamp dir.  This is unlikely to happen
+since once the timestamp dir is owned by root and inaccessible by
+any other user, the user placing files there would be unable to get
+them back out.  To get around this issue you can use a directory
+that is not world-writable for the timestamps (F</var/adm/sudo> for
+instance) or create F<@timedir@> with the appropriate owner (root)
+and permissions (0700) in the system startup files.
 
 B<sudo> will not honor timestamps set far in the future.
 Timestamps with a date greater than current_time + 2 * C<TIMEOUT>
@@ -361,56 +383,87 @@ will be ignored and sudo will log and complain.  This is done to
 keep a user from creating his/her own timestamp with a bogus
 date on systems that allow users to give away files.
 
-Please note that B<sudo> will only log the command it explicitly
-runs.  If a user runs a command such as C<sudo su> or C<sudo sh>,
-subsequent commands run from that shell will I<not> be logged, nor
-will B<sudo>'s access control affect them.  The same is true for
-commands that offer shell escapes (including most editors).  Because
-of this, care must be taken when giving users access to commands
-via B<sudo> to verify that the command does not inadvertently give
-the user an effective root shell.
+Please note that B<sudo> will normally only log the command it
+explicitly runs.  If a user runs a command such as C<sudo su> or
+C<sudo sh>, subsequent commands run from that shell will I<not> be
+logged, nor will B<sudo>'s access control affect them.  The same
+is true for commands that offer shell escapes (including most
+editors).  Because of this, care must be taken when giving users
+access to commands via B<sudo> to verify that the command does not
+inadvertently give the user an effective root shell.  For more
+information, please see the C<PREVENTING SHELL ESCAPES> section in
+L<sudoers(5)>.
 
 =head1 ENVIRONMENT
 
 B<sudo> utilizes the following environment variables:
 
- EDITOR                        Default editor to use in -e (sudoedit) mode if
-                       VISUAL is not set
+=over 16
+
+=item C<EDITOR>
+
+Default editor to use in B<-e> (sudoedit) mode if C<VISUAL> is not set
+
+=item C<HOME>
+
+In B<-s> or B<-H> mode (or if sudo was configured with the
+--enable-shell-sets-home option), set to homedir of the target user
+
+=item C<PATH>
+
+Set to a sane value if the I<secure_path> sudoers option is set.
+
+=item C<SHELL>
 
- HOME                  In -s or -H mode (or if sudo was configured with
-                       the --enable-shell-sets-home option), set to
-                       homedir of the target user
+Used to determine shell to run with C<-s> option
 
- PATH                  Set to a sane value if sudo was configured with
-                       the --with-secure-path option
+=item C<SUDO_PROMPT>
 
- SHELL                 Used to determine shell to run with -s option
+Used as the default password prompt
 
- SUDO_PROMPT           Used as the default password prompt
+=item C<SUDO_COMMAND>
 
- SUDO_COMMAND          Set to the command run by sudo
+Set to the command run by sudo
 
- SUDO_USER             Set to the login of the user who invoked sudo
+=item C<SUDO_USER>
 
- SUDO_UID              Set to the uid of the user who invoked sudo
+Set to the login of the user who invoked sudo
 
- SUDO_GID              Set to the gid of the user who invoked sudo
+=item C<SUDO_UID>
 
- SUDO_PS1              If set, PS1 will be set to its value
+Set to the uid of the user who invoked sudo
 
- USER                  Set to the target user (root unless the -u option
-                       is specified)
+=item C<SUDO_GID>
 
- VISUAL                        Default editor to use in -e (sudoedit) mode
+Set to the gid of the user who invoked sudo
+
+=item C<SUDO_PS1>
+
+If set, C<PS1> will be set to its value
+
+=item C<USER>
+
+Set to the target user (root unless the B<-u> option is specified)
+
+=item C<VISUAL>
+
+Default editor to use in B<-e> (sudoedit) mode
+
+=back
 
 =head1 FILES
 
- @sysconfdir@/sudoers          List of who can run what
- @timedir@             Directory containing timestamps
+=over 4
+
+=item F<@sysconfdir@/sudoers>C<                >List of who can run what
+
+=item F<@timedir@>C<           >Directory containing timestamps
+
+=back
 
 =head1 EXAMPLES
 
-Note: the following examples assume suitable L<sudoers(@mansectform@)> entries.
+Note: the following examples assume suitable L<sudoers(5)> entries.
 
 To get a file listing of an unreadable directory:
 
@@ -437,15 +490,15 @@ to make the C<cd> and file redirection work.
 
 =head1 SEE ALSO
 
-L<grep(1)>, L<su(1)>, L<stat(2)>, L<login_cap(3)>, L<sudoers(@mansectform@)>,
-L<passwd(@mansectform@)>, L<visudo(@mansectsu@)>
+L<grep(1)>, L<su(1)>, L<stat(2)>, L<login_cap(3)>, L<passwd(5)>,
+L<sudoers(5)>, L<visudo(8)>
 
 =head1 AUTHORS
 
 Many people have worked on B<sudo> over the years; this
 version consists of code written primarily by:
 
-       Todd Miller
+       Todd C. Miller
        Chris Jepeway
 
 See the HISTORY file in the B<sudo> distribution or visit
@@ -459,14 +512,14 @@ if that user is allowed to run arbitrary commands via B<sudo>.
 Also, many programs (such as editors) allow the user to run commands
 via shell escapes, thus avoiding B<sudo>'s checks.  However, on
 most systems it is possible to prevent shell escapes with B<sudo>'s
-I<noexec> functionality.  See the L<sudoers(@mansectform@)> manual
+I<noexec> functionality.  See the L<sudoers(5)> manual
 for details.
 
-It is not meaningful to run the C<cd> command directly via sudo, e.g.
+It is not meaningful to run the C<cd> command directly via sudo, e.g.,
 
  $ sudo cd /usr/local/protected
 
-since when whe command exits the parent process (your shell) will
+since when the command exits the parent process (your shell) will
 still be the same.  Please see the EXAMPLES section for more information.
 
 If users have sudo C<ALL> there is nothing to prevent them from
@@ -484,16 +537,13 @@ at http://www.sudo.ws/sudo/bugs/
 
 =head1 SUPPORT
 
-Commercial support is available for B<sudo>, see
-http://www.sudo.ws/sudo/support.html for details.
-
 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.
 
 =head1 DISCLAIMER
 
-B<Sudo> is provided ``AS IS'' and any express or implied warranties,
+B<sudo> is provided ``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 B<sudo> or http://www.sudo.ws/sudo/license.html