2 Copyright (c) 1994-1996,1998-2003 Todd C. Miller <Todd.Miller@courtesan.com>
4 Permission to use, copy, modify, and distribute this software for any
5 purpose with or without fee is hereby granted, provided that the above
6 copyright notice and this permission notice appear in all copies.
8 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
17 Sponsored in part by the Defense Advanced Research Projects
18 Agency (DARPA) and Air Force Research Laboratory, Air Force
19 Materiel Command, USAF, under agreement number F39502-99-1-0512.
21 $Sudo: sudo.pod,v 1.73 2004/09/08 18:34:38 millert Exp $
26 sudo, sudoedit - execute a command as another user
30 B<sudo> B<-K> | B<-L> | B<-V> | B<-h> | B<-k> | B<-l> | B<-v>
32 B<sudo> [B<-HPSb>] S<[B<-a> I<auth_type>]> S<[B<-c> I<class>|I<->]>
33 S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
34 S<{B<-e> file [...] | B<-i> | B<-s> | I<command>}>
36 B<sudoedit> [B<-S>] S<[B<-a> I<auth_type>]>
37 S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
42 B<sudo> allows a permitted user to execute a I<command> as the
43 superuser or another user, as specified in the I<sudoers> file.
44 The real and effective uid and gid are set to match those of the
45 target user as specified in the passwd file and the group vector
46 is initialized based on the group file (unless the B<-P> option was
47 specified). If the invoking user is root or if the target user is
48 the same as the invoking user, no password is required. Otherwise,
49 B<sudo> requires that users authenticate themselves with a password
50 by default (NOTE: in the default configuration this is the user's
51 password, not the root password). Once a user has been authenticated,
52 a timestamp is updated and the user may then use sudo without a
53 password for a short period of time (C<@timeout@> minutes unless
54 overridden in I<sudoers>).
56 When invoked as B<sudoedit>, the B<-e> option (described below),
59 B<sudo> determines who is an authorized user by consulting the file
60 F<@sysconfdir@/sudoers>. By giving B<sudo> the B<-v> flag a user
61 can update the time stamp without running a I<command.> The password
62 prompt itself will also time out if the user's password is not
63 entered within C<@password_timeout@> minutes (unless overridden via
66 If a user who is not listed in the I<sudoers> file tries to run a
67 command via B<sudo>, mail is sent to the proper authorities, as
68 defined at configure time or in the I<sudoers> file (defaults to
69 C<@mailto@>). Note that the mail will not be sent if an unauthorized
70 user tries to run sudo with the B<-l> or B<-v> flags. This allows
71 users to determine for themselves whether or not they are allowed
74 If B<sudo> is run by root and the C<SUDO_USER> environment variable
75 is set, B<sudo> will use this value to determine who the actual
76 user is. This can be used by a user to log commands through sudo
77 even when a root shell has been invoked. It also allows the B<-e>
78 flag to remain useful even when being run via a sudo-run script or
79 program. Note however, that the sudoers lookup is still done for
80 root, not the user specified by C<SUDO_USER>.
82 B<sudo> can log both successful and unsuccessful attempts (as well
83 as errors) to syslog(3), a log file, or both. By default B<sudo>
84 will log via syslog(3) but this is changeable at configure time
85 or via the I<sudoers> file.
89 B<sudo> accepts the following command line options:
95 The B<-H> (I<HOME>) option sets the C<HOME> environment variable
96 to the homedir of the target user (root by default) as specified
97 in passwd(@mansectform@). By default, B<sudo> does not modify C<HOME>
98 (see I<set_home> and I<always_set_home> in L<sudoers(@mansectform@)>).
102 The B<-K> (sure I<kill>) option is like B<-k> except that it removes
103 the user's timestamp entirely. Like B<-k>, this option does not
108 The B<-L> (I<list> defaults) option will list out the parameters
109 that may be set in a I<Defaults> line along with a short description
110 for each. This option is useful in conjunction with grep(1).
114 The B<-P> (I<preserve group vector>) option causes B<sudo> to
115 preserve the invoking user's group vector unaltered. By default,
116 B<sudo> will initialize the group vector to the list of groups the
117 target user is in. The real and effective group IDs, however, are
118 still set to match the target user.
122 The B<-S> (I<stdin>) option causes B<sudo> to read the password from
123 the standard input instead of the terminal device.
127 The B<-V> (I<version>) option causes B<sudo> to print the version
128 number and exit. If the invoking user is already root the B<-V>
129 option will print out a list of the defaults B<sudo> was compiled
130 with as well as the machine's local network addresses.
134 The B<-a> (I<authentication type>) option causes B<sudo> to use the
135 specified authentication type when validating the user, as allowed
136 by /etc/login.conf. The system administrator may specify a list
137 of sudo-specific authentication methods by adding an "auth-sudo"
138 entry in /etc/login.conf. This option is only available on systems
139 that support BSD authentication where B<sudo> has been configured
140 with the --with-bsdauth option.
144 The B<-b> (I<background>) option tells B<sudo> to run the given
145 command in the background. Note that if you use the B<-b>
146 option you cannot use shell job control to manipulate the process.
150 The B<-c> (I<class>) option causes B<sudo> to run the specified command
151 with resources limited by the specified login class. The I<class>
152 argument can be either a class name as defined in /etc/login.conf,
153 or a single '-' character. Specifying a I<class> of C<-> indicates
154 that the command should be run restricted by the default login
155 capabilities for the user the command is run as. If the I<class>
156 argument specifies an existing user class, the command must be run
157 as root, or the B<sudo> command must be run from a shell that is already
158 root. This option is only available on systems with BSD login classes
159 where B<sudo> has been configured with the --with-logincap option.
163 The B<-e> (I<edit>) option indicates that, instead of running
164 a command, the user wishes to edit one or more files. In lieu
165 of a command, the string "sudoedit" is used when consulting
166 the I<sudoers> file. If the user is authorized by I<sudoers>
167 the following steps are taken:
173 Temporary copies are made of the files to be edited with the owner
174 set to the invoking user.
178 The editor specified by the C<VISUAL> or C<EDITOR> environment
179 variables is run to edit the temporary files. If neither C<VISUAL>
180 nor C<EDITOR> are set, the program listed in the I<editor> I<sudoers>
185 If they have been modified, the temporary files are copied back to
186 their original location and the temporary versions are removed.
190 If the specified file does not exist, it will be created. Note
191 that unlike most commands run by B<sudo>, the editor is run with
192 the invoking user's environment unmodified. If, for some reason,
193 B<sudo> is unable to update a file with its edited version, the
194 user will receive a warning and the edited copy will remain in a
199 The B<-h> (I<help>) option causes B<sudo> to print a usage message and exit.
203 The B<-i> (I<simulate initial login>) option runs the shell specified
204 in the L<passwd(@mansectform@)> entry of the user that the command is
205 being run as. The command name argument given to the shell begins
206 with a C<-> to tell the shell to run as a login shell. B<sudo>
207 attempts to change to that user's home directory before running the
208 shell. It also initializes the environment, leaving I<TERM>
209 unchanged, setting I<HOME>, I<SHELL>, I<USER>, I<LOGNAME>, and
210 I<PATH>, and unsetting all other environment variables. Note that
211 because the shell to use is determined before the I<sudoers> file
212 is parsed, a I<runas_default> setting in I<sudoers> will specify
213 the user to run the shell as but will not affect which shell is
218 The B<-k> (I<kill>) option to B<sudo> invalidates the user's timestamp
219 by setting the time on it to the epoch. The next time B<sudo> is
220 run a password will be required. This option does not require a password
221 and was added to allow a user to revoke B<sudo> permissions from a .logout
226 The B<-l> (I<list>) option will list out the allowed (and
227 forbidden) commands for the user on the current host.
231 The B<-p> (I<prompt>) option allows you to override the default
232 password prompt and use a custom one. The following percent (`C<%>')
233 escapes are supported:
239 expanded to the invoking user's login name
243 expanded to the login name of the user the command will
244 be run as (defaults to root)
248 expanded to the local hostname without the domain name
252 expanded to the local hostname including the domain name
253 (on if the machine's hostname is fully qualified or the I<fqdn>
254 sudoers option is set)
258 two consecutive C<%> characters are collapsed into a single C<%> character
264 The B<-s> (I<shell>) option runs the shell specified by the I<SHELL>
265 environment variable if it is set or the shell as specified
266 in L<passwd(@mansectform@)>.
270 The B<-u> (I<user>) option causes B<sudo> to run the specified command
271 as a user other than I<root>. To specify a I<uid> instead of a
272 I<username>, use I<#uid>. Note that if the I<targetpw> Defaults
273 option is set (see L<sudoers(@mansectform@)>) it is not possible
274 to run commands with a uid not listed in the password database.
278 If given the B<-v> (I<validate>) option, B<sudo> will update the
279 user's timestamp, prompting for the user's password if necessary.
280 This extends the B<sudo> timeout for another C<@timeout@> minutes
281 (or whatever the timeout is set to in I<sudoers>) but does not run
286 The B<--> flag indicates that B<sudo> should stop processing command
287 line arguments. It is most useful in conjunction with the B<-s> flag.
293 Upon successful execution of a program, the return value from B<sudo>
294 will simply be the return value of the program that was executed.
296 Otherwise, B<sudo> quits with an exit value of 1 if there is a
297 configuration/permission problem or if B<sudo> cannot execute the
298 given command. In the latter case the error string is printed to
299 stderr. If B<sudo> cannot L<stat(2)> one or more entries in the user's
300 C<PATH> an error is printed on stderr. (If the directory does not
301 exist or if it is not really a directory, the entry is ignored and
302 no error is printed.) This should not happen under normal
303 circumstances. The most common reason for L<stat(2)> to return
304 "permission denied" is if you are running an automounter and one
305 of the directories in your C<PATH> is on a machine that is currently
308 =head1 SECURITY NOTES
310 B<sudo> tries to be safe when executing external commands. Variables
311 that control how dynamic loading and binding is done can be used
312 to subvert the program that B<sudo> runs. To combat this the
313 C<LD_*>, C<_RLD_*>, C<SHLIB_PATH> (HP-UX only), and C<LIBPATH> (AIX
314 only) environment variables are removed from the environment passed
315 on to all commands executed. B<sudo> will also remove the C<IFS>,
316 C<CDPATH>, C<ENV>, C<BASH_ENV>, C<KRB_CONF>, C<KRBCONFDIR>, C<KRBTKFILE>,
317 C<KRB5_CONFIG>, C<LOCALDOMAIN>, C<RES_OPTIONS>, C<HOSTALIASES>,
318 C<NLSPATH>, C<PATH_LOCALE>, C<TERMINFO>, C<TERMINFO_DIRS> and
319 C<TERMPATH> variables as they too can pose a threat. If the
320 C<TERMCAP> variable is set and is a pathname, it too is ignored.
321 Additionally, if the C<LC_*> or C<LANGUAGE> variables contain the
322 C</> or C<%> characters, they are ignored. Environment variables
323 with a value beginning with C<()> are also removed as they could
324 be interpreted as B<bash> functions. If B<sudo> has been
325 compiled with SecurID support, the C<VAR_ACE>, C<USR_ACE> and
326 C<DLC_ACE> variables are cleared as well. The list of environment
327 variables that B<sudo> clears is contained in the output of
328 C<sudo -V> when run as root.
330 To prevent command spoofing, B<sudo> checks "." and "" (both denoting
331 current directory) last when searching for a command in the user's
332 PATH (if one or both are in the PATH). Note, however, that the
333 actual C<PATH> environment variable is I<not> modified and is passed
334 unchanged to the program that B<sudo> executes.
336 For security reasons, if your OS supports shared libraries and does
337 not disable user-defined library search paths for setuid programs
338 (most do), you should either use a linker option that disables this
339 behavior or link B<sudo> statically.
341 B<sudo> will check the ownership of its timestamp directory
342 (F<@timedir@> by default) and ignore the directory's contents if
343 it is not owned by root and only writable by root. On systems that
344 allow non-root users to give away files via L<chown(2)>, if the timestamp
345 directory is located in a directory writable by anyone (e.g.: F</tmp>),
346 it is possible for a user to create the timestamp directory before
347 B<sudo> is run. However, because B<sudo> checks the ownership and
348 mode of the directory and its contents, the only damage that can
349 be done is to "hide" files by putting them in the timestamp dir.
350 This is unlikely to happen since once the timestamp dir is owned
351 by root and inaccessible by any other user the user placing files
352 there would be unable to get them back out. To get around this
353 issue you can use a directory that is not world-writable for the
354 timestamps (F</var/adm/sudo> for instance) or create F<@timedir@>
355 with the appropriate owner (root) and permissions (0700) in the
356 system startup files.
358 B<sudo> will not honor timestamps set far in the future.
359 Timestamps with a date greater than current_time + 2 * C<TIMEOUT>
360 will be ignored and sudo will log and complain. This is done to
361 keep a user from creating his/her own timestamp with a bogus
362 date on systems that allow users to give away files.
364 Please note that B<sudo> will only log the command it explicitly
365 runs. If a user runs a command such as C<sudo su> or C<sudo sh>,
366 subsequent commands run from that shell will I<not> be logged, nor
367 will B<sudo>'s access control affect them. The same is true for
368 commands that offer shell escapes (including most editors). Because
369 of this, care must be taken when giving users access to commands
370 via B<sudo> to verify that the command does not inadvertently give
371 the user an effective root shell.
375 B<sudo> utilizes the following environment variables:
377 EDITOR Default editor to use in -e (sudoedit) mode if
380 HOME In -s or -H mode (or if sudo was configured with
381 the --enable-shell-sets-home option), set to
382 homedir of the target user
384 PATH Set to a sane value if sudo was configured with
385 the --with-secure-path option
387 SHELL Used to determine shell to run with -s option
389 SUDO_PROMPT Used as the default password prompt
391 SUDO_COMMAND Set to the command run by sudo
393 SUDO_USER Set to the login of the user who invoked sudo
395 SUDO_UID Set to the uid of the user who invoked sudo
397 SUDO_GID Set to the gid of the user who invoked sudo
399 SUDO_PS1 If set, PS1 will be set to its value
401 USER Set to the target user (root unless the -u option
404 VISUAL Default editor to use in -e (sudoedit) mode
408 @sysconfdir@/sudoers List of who can run what
409 @timedir@ Directory containing timestamps
413 Note: the following examples assume suitable L<sudoers(@mansectform@)> entries.
415 To get a file listing of an unreadable directory:
417 $ sudo ls /usr/local/protected
419 To list the home directory of user yazza on a machine where the
420 file system holding ~yazza is not exported as root:
422 $ sudo -u yazza ls ~yazza
424 To edit the F<index.html> file as user www:
426 $ sudo -u www vi ~www/htdocs/index.html
428 To shutdown a machine:
430 $ sudo shutdown -r +15 "quick reboot"
432 To make a usage listing of the directories in the /home
433 partition. Note that this runs the commands in a sub-shell
434 to make the C<cd> and file redirection work.
436 $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
440 L<grep(1)>, L<su(1)>, L<stat(2)>, L<login_cap(3)>, L<sudoers(@mansectform@)>,
441 L<passwd(@mansectform@)>, L<visudo(@mansectsu@)>
445 Many people have worked on B<sudo> over the years; this
446 version consists of code written primarily by:
451 See the HISTORY file in the B<sudo> distribution or visit
452 http://www.sudo.ws/sudo/history.html for a short history
457 There is no easy way to prevent a user from gaining a root shell
458 if that user is allowed to run arbitrary commands via B<sudo>.
459 Also, many programs (such as editors) allow the user to run commands
460 via shell escapes, thus avoiding B<sudo>'s checks. However, on
461 most systems it is possible to prevent shell escapes with B<sudo>'s
462 I<noexec> functionality. See the L<sudoers(@mansectform@)> manual
465 It is not meaningful to run the C<cd> command directly via sudo, e.g.
467 $ sudo cd /usr/local/protected
469 since when whe command exits the parent process (your shell) will
470 still be the same. Please see the EXAMPLES section for more information.
472 If users have sudo C<ALL> there is nothing to prevent them from
473 creating their own program that gives them a root shell regardless
474 of any '!' elements in the user specification.
476 Running shell scripts via B<sudo> can expose the same kernel bugs that
477 make setuid shell scripts unsafe on some operating systems (if your OS
478 has a /dev/fd/ directory, setuid shell scripts are generally safe).
482 If you feel you have found a bug in B<sudo>, please submit a bug report
483 at http://www.sudo.ws/sudo/bugs/
487 Commercial support is available for B<sudo>, see
488 http://www.sudo.ws/sudo/support.html for details.
490 Limited free support is available via the sudo-users mailing list,
491 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
496 B<Sudo> is provided ``AS IS'' and any express or implied warranties,
497 including, but not limited to, the implied warranties of merchantability
498 and fitness for a particular purpose are disclaimed. See the LICENSE
499 file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
500 for complete details.