-=cut
-Copyright (c) 1994-1996, 1998-2005, 2007
+Copyright (c) 1994-1996, 1998-2005, 2007-2009
Todd C. Miller <Todd.Miller@courtesan.com>
Permission to use, copy, modify, and distribute this software for any
Agency (DARPA) and Air Force Research Laboratory, Air Force
Materiel Command, USAF, under agreement number F39502-99-1-0512.
-$Sudo: sudo.pod,v 1.70.2.19 2007/11/21 19:26:10 millert Exp $
+$Sudo: sudo.pod,v 1.124 2009/06/15 21:19:47 millert Exp $
=pod
=head1 NAME
=head1 SYNOPSIS
-B<sudo> B<-h> | B<-K> | B<-k> | B<-L> | B<-l> | B<-V> | B<-v>
-
-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>]> S<[B<-c> I<class>|I<->]>
-S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
-file ...
+B<sudo> B<-h> | B<-K> | B<-k> | B<-L> | B<-V>
+
+B<sudo> B<-v> [B<-AknS>]
+S<[B<-a> I<auth_type>]>
+S<[B<-p> I<prompt>]>
+
+B<sudo> B<-l[l]> [B<-AknS>]
+S<[B<-a> I<auth_type>]>
+S<[B<-g> I<groupname>|I<#gid>]> S<[B<-p> I<prompt>]>
+S<[B<-U> I<username>]> S<[B<-u> I<username>|I<#uid>]> [I<command>]
+
+B<sudo> [B<-AbEHnPS>]
+S<[B<-a> I<auth_type>]>
+S<[B<-C> I<fd>]>
+S<[B<-c> I<class>|I<->]>
+S<[B<-g> I<groupname>|I<#gid>]> S<[B<-p> I<prompt>]>
+S<[B<-r> I<role>]> S<[B<-t> I<type>]>
+S<[B<-u> I<username>|I<#uid>]>
+S<[B<VAR>=I<value>]> S<[B<-i> | B<-s>]> [I<command>]
+
+B<sudoedit> [B<-AnS>]
+S<[B<-a> I<auth_type>]>
+S<[B<-C> I<fd>]>
+S<[B<-c> I<class>|I<->]>
+S<[B<-g> I<groupname>|I<#gid>]> S<[B<-p> I<prompt>]>
+S<[B<-u> I<username>|I<#uid>]> file ...
=head1 DESCRIPTION
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
-prompt itself will also time out if the user's password is not
-entered within C<@password_timeout@> minutes (unless overridden via
-I<sudoers>).
+F<@sysconfdir@/sudoers>. By running B<sudo> with the B<-v> option,
+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>).
If a user who is not listed in the I<sudoers> file tries to run a
command via B<sudo>, mail is sent to the proper authorities, as
defined at configure time or in the I<sudoers> file (defaults to
C<@mailto@>). Note that the mail will not be sent if an unauthorized
-user tries to run sudo with the B<-l> or B<-v> flags. This allows
+user tries to run sudo with the B<-l> or B<-v> option. This allows
users to determine for themselves whether or not they are allowed
to use B<sudo>.
is set, B<sudo> 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 B<-e>
-flag to remain useful even when being run via a sudo-run script or
+option to remain useful even when being run via a sudo-run script or
program. Note however, that the sudoers lookup is still done for
root, not the user specified by C<SUDO_USER>.
B<sudo> accepts the following command line options:
-=over 4
+=over 12
+
+=item -A
-=item -a
+Normally, if B<sudo> requires a password, it will read it from the
+current terminal. If the B<-A> (I<askpass>) 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 C<SUDO_ASKPASS> environment variable is set, it specifies the
+path to the helper program. Otherwise, the value specified by the
+I<askpass> option in L<sudoers(5)> is used.
+
+=item -a I<type>
The B<-a> (I<authentication type>) option causes B<sudo> to use the
specified authentication type when validating the user, as allowed
command in the background. Note that if you use the B<-b>
option you cannot use shell job control to manipulate the process.
-=item -c
+=item -C I<fd>
+
+Normally, B<sudo> will close all open file descriptors other than
+standard input, standard output and standard error. The B<-C>
+(I<close from>) option allows the user to specify a starting point
+above the standard error (file descriptor three). Values less than
+three are not permitted. This option is only available if the
+administrator has enabled the I<closefrom_override> option in
+L<sudoers(5)>.
+
+=item -c I<class>
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 C</etc/login.conf>,
+argument can be either a class name as defined in F</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>
=item 2.
-The editor specified by the C<VISUAL> or C<EDITOR> environment
-variables is run to edit the temporary files. If neither C<VISUAL>
-nor C<EDITOR> are set, the program listed in the I<editor> I<sudoers>
-variable is used.
+The editor specified by the C<SUDO_EDITOR>, C<VISUAL> or C<EDITOR>
+environment variables is run to edit the temporary files. If none
+of C<SUDO_EDITOR>, C<VISUAL> or C<EDITOR> are set, the first program
+listed in the I<editor> I<sudoers> variable is used.
=item 3.
user will receive a warning and the edited copy will remain in a
temporary file.
+=item -g I<group>
+
+Normally, B<sudo> sets the primary group to the one specified by
+the passwd database for the user the command is being run as (by
+default, root). The B<-g> (I<group>) option causes B<sudo> to run
+the specified command with the primary group set to I<group>. To
+specify a I<gid> instead of a I<group name>, use I<#gid>. When
+running commands as a I<gid>, many shells require that the '#' be
+escaped with a backslash ('\'). If no B<-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 I<group>.
+
=item -H
The B<-H> (I<HOME>) option sets the C<HOME> environment variable
The B<-h> (I<help>) option causes B<sudo> to print a usage message and exit.
-=item -i
+=item -i [command]
The B<-i> (I<simulate initial login>) option runs the shell specified
-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>
-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
-I<PATH>, and unsetting all other environment variables. Note that
-because the shell to use is determined before the I<sudoers> file
-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.
+in the L<passwd(5)> entry of the target user as a login shell. This
+means that login-specific resource files such as C<.profile> or
+C<.login> will be read by the shell. If a command is specified,
+it is passed to the shell for execution. Otherwise, an interactive
+shell is executed. B<sudo> attempts to change to that user's home
+directory before running the shell. It also initializes the
+environment, leaving I<DISPLAY> and I<TERM> unchanged, setting
+I<HOME>, I<SHELL>, I<USER>, I<LOGNAME>, and I<PATH>, as well as
+the contents of F</etc/environment> on Linux and AIX systems.
+All other environment variables are removed.
=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.
+the user's timestamp entirely and may not be used in conjunction
+with a command or other option. 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
-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.
+When used by itself, 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 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.
+
+When used in conjunction with a command or an option that may require
+a password, the B<-k> option will cause B<sudo> to ignore the user's
+timestamp file. As a result, B<sudo> will prompt for a password
+(if one is required by I<sudoers>) and will not update the user's
+timestamp file.
=item -L
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
+=item -l[l] [I<command>]
+
+If no I<command> is specified, the B<-l> (I<list>) option will list
+the allowed (and forbidden) commands for the invoking user (or the
+user specified by the B<-U> option) on the current host. If a
+I<command> is specified and is permitted by I<sudoers>, the
+fully-qualified path to the command is displayed along with any
+command line arguments. If I<command> is specified but not allowed,
+B<sudo> will exit with a status value of 1. If the B<-l> option is
+specified with an B<l> argument (i.e. B<-ll>), or if B<-l>
+is specified multiple times, a longer list format is used.
+
+=item -n
-The B<-l> (I<list>) option will list out the allowed (and
-forbidden) commands for the invoking user on the current host.
+The B<-n> (I<non-interactive>) option prevents B<sudo> from prompting
+the user for a password. If a password is required for the command
+to run, B<sudo> will display an error messages and exit.
=item -P
target user is in. The real and effective group IDs, however, are
still set to match the target user.
-=item -p
+=item -p I<prompt>
The B<-p> (I<prompt>) option allows you to override the default
password prompt and use a custom one. The following percent (`C<%>')
expanded to the local hostname without the domain name
+=item C<%p>
+
+expanded to the user whose password is being asked for (respects the
+I<rootpw>, I<targetpw> and I<runaspw> flags in I<sudoers>)
+
=item C<%U>
expanded to the login name of the user the command will
=back
+The prompt specified by the B<-p> option will override the system
+password prompt on systems that support PAM unless the
+I<passprompt_override> flag is disabled in I<sudoers>.
+
+=item -r I<role>
+
+The B<-r> (I<role>) option causes the new (SELinux) security context to
+have the role specified by I<role>.
+
=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
+=item -s [command]
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(5)>.
+environment variable if it is set or the shell as specified in
+L<passwd(5)>. If a command is specified, it is passed to the shell
+for execution. Otherwise, an interactive shell is executed.
+
+=item -t I<type>
-=item -u
+The B<-t> (I<type>) option causes the new (SELinux) security context to
+have the type specified by I<type>. If no type is specified, the default
+type is derived from the specified role.
+
+=item -U I<user>
+
+The B<-U> (I<other user>) option is used in conjunction with the B<-l>
+option to specify the user whose privileges should be listed. Only
+root or a user with B<sudo> C<ALL> on the current host may use this
+option.
+
+=item -u I<user>
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>,
+of a I<user name>, 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
=item --
-The B<--> flag indicates that B<sudo> should stop processing command
-line arguments. It is most useful in conjunction with the B<-s> flag.
+The B<--> option indicates that B<sudo> should stop processing command
+line arguments. It is most useful in conjunction with the B<-s> option.
=back
=head1 RETURN VALUES
-Upon successful execution of a program, the return value from B<sudo>
-will simply be the return value of the program that was executed.
+Upon successful execution of a program, the exit status from B<sudo>
+will simply be the exit status of the program that was executed.
Otherwise, B<sudo> quits with an exit value of 1 if there is a
configuration/permission problem or if B<sudo> cannot execute the
=item C<EDITOR>
-Default editor to use in B<-e> (sudoedit) mode if C<VISUAL> is not set
+Default editor to use in B<-e> (sudoedit) mode if neither C<SUDO_EDITOR>
+nor C<VISUAL> is set
=item C<HOME>
Used to determine shell to run with C<-s> option
-=item C<SUDO_PROMPT>
+=item C<SUDO_ASKPASS>
-Used as the default password prompt
+Specifies the path to a helper program used to read the password
+if no terminal is available or if the C<-A> option is specified.
=item C<SUDO_COMMAND>
Set to the command run by sudo
-=item C<SUDO_USER>
+=item C<SUDO_EDITOR>
-Set to the login of the user who invoked sudo
+Default editor to use in B<-e> (sudoedit) mode
-=item C<SUDO_UID>
+=item C<SUDO_GID>
-Set to the uid of the user who invoked sudo
+Set to the group ID of the user who invoked sudo
-=item C<SUDO_GID>
+=item C<SUDO_PROMPT>
-Set to the gid of the user who invoked sudo
+Used as the default password prompt
=item C<SUDO_PS1>
-If set, C<PS1> will be set to its value
+If set, C<PS1> will be set to its value for the program being run
+
+=item C<SUDO_UID>
+
+Set to the user ID of the user who invoked sudo
+
+=item C<SUDO_USER>
+
+Set to the login of the user who invoked sudo
=item C<USER>
=item C<VISUAL>
-Default editor to use in B<-e> (sudoedit) mode
+Default editor to use in B<-e> (sudoedit) mode if C<SUDO_EDITOR>
+is not set
=back
=head1 FILES
-=over 4
+=over 24
+
+=item F<@sysconfdir@/sudoers>
+
+List of who can run what
-=item F<@sysconfdir@/sudoers>C< >List of who can run what
+=item F<@timedir@>
-=item F<@timedir@>C< >Directory containing timestamps
+Directory containing timestamps
+
+=item F</etc/environment>
+
+Initial environment for B<-i> mode on Linux and AIX
=back
$ sudo ls /usr/local/protected
-To list the home directory of user yazza on a machine where the
-file system holding ~yazza is not exported as root:
+To list the home directory of user yaz on a machine where the
+file system holding ~yaz is not exported as root:
- $ sudo -u yazza ls ~yazza
+ $ sudo -u yaz ls ~yaz
To edit the F<index.html> file as user www:
$ sudo -u www vi ~www/htdocs/index.html
+To view system logs only accessible to root and users in the adm group:
+
+ $ sudo -g adm view /var/log/syslog
+
+To run an editor as jim with a different primary group:
+
+ $ sudo -u jim -g audio vi ~jim/sound.txt
+
To shutdown a machine:
$ sudo shutdown -r +15 "quick reboot"
=head1 SEE ALSO
-L<grep(1)>, L<su(1)>, L<stat(2)>, L<login_cap(3)>, L<passwd(5)>,
-L<sudoers(5)>, L<visudo(8)>
+L<grep(1)>, L<su(1)>, L<stat(2)>,
+L<login_cap(3)>,
+L<passwd(5)>, L<sudoers(5)>, L<visudo(8)>
=head1 AUTHORS
version consists of code written primarily by:
Todd C. Miller
- Chris Jepeway
See the HISTORY file in the B<sudo> distribution or visit
http://www.sudo.ws/sudo/history.html for a short history
projects / debian / sudo / blobdiff