2 Copyright (c) 1994-1996, 1998-2005, 2007
3 Todd C. Miller <Todd.Miller@courtesan.com>
5 Permission to use, copy, modify, and distribute this software for any
6 purpose with or without fee is hereby granted, provided that the above
7 copyright notice and this permission notice appear in all copies.
9 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
18 Sponsored in part by the Defense Advanced Research Projects
19 Agency (DARPA) and Air Force Research Laboratory, Air Force
20 Materiel Command, USAF, under agreement number F39502-99-1-0512.
22 $Sudo: sudo.pod,v 1.70.2.18 2007/08/13 16:23:31 millert Exp $
27 sudo, sudoedit - execute a command as another user
31 B<sudo> B<-h> | B<-K> | B<-k> | B<-L> | B<-l> | B<-V> | B<-v>
33 B<sudo> [B<-bEHPS>] S<[B<-a> I<auth_type>]>
34 S<[B<-c> I<class>|I<->]> S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
35 S<[B<VAR>=I<value>]> S<{B<-i> | B<-s> | I<command>}>
37 B<sudoedit> [B<-S>] S<[B<-a> I<auth_type>]> S<[B<-c> I<class>|I<->]>
38 S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
43 B<sudo> allows a permitted user to execute a I<command> as the
44 superuser or another user, as specified in the I<sudoers> file.
45 The real and effective uid and gid are set to match those of the
46 target user as specified in the passwd file and the group vector
47 is initialized based on the group file (unless the B<-P> option was
48 specified). If the invoking user is root or if the target user is
49 the same as the invoking user, no password is required. Otherwise,
50 B<sudo> requires that users authenticate themselves with a password
51 by default (NOTE: in the default configuration this is the user's
52 password, not the root password). Once a user has been authenticated,
53 a timestamp is updated and the user may then use sudo without a
54 password for a short period of time (C<@timeout@> minutes unless
55 overridden in I<sudoers>).
57 When invoked as B<sudoedit>, the B<-e> option (described below),
60 B<sudo> determines who is an authorized user by consulting the file
61 F<@sysconfdir@/sudoers>. By giving B<sudo> the B<-v> flag, a user
62 can update the time stamp without running a I<command>. The password
63 prompt itself will also time out if the user's password is not
64 entered within C<@password_timeout@> minutes (unless overridden via
67 If a user who is not listed in the I<sudoers> file tries to run a
68 command via B<sudo>, mail is sent to the proper authorities, as
69 defined at configure time or in the I<sudoers> file (defaults to
70 C<@mailto@>). Note that the mail will not be sent if an unauthorized
71 user tries to run sudo with the B<-l> or B<-v> flags. This allows
72 users to determine for themselves whether or not they are allowed
75 If B<sudo> is run by root and the C<SUDO_USER> environment variable
76 is set, B<sudo> will use this value to determine who the actual
77 user is. This can be used by a user to log commands through sudo
78 even when a root shell has been invoked. It also allows the B<-e>
79 flag to remain useful even when being run via a sudo-run script or
80 program. Note however, that the sudoers lookup is still done for
81 root, not the user specified by C<SUDO_USER>.
83 B<sudo> can log both successful and unsuccessful attempts (as well
84 as errors) to syslog(3), a log file, or both. By default B<sudo>
85 will log via syslog(3) but this is changeable at configure time
86 or via the I<sudoers> file.
90 B<sudo> accepts the following command line options:
96 The B<-a> (I<authentication type>) option causes B<sudo> to use the
97 specified authentication type when validating the user, as allowed
98 by F</etc/login.conf>. The system administrator may specify a list
99 of sudo-specific authentication methods by adding an "auth-sudo"
100 entry in F</etc/login.conf>. This option is only available on systems
101 that support BSD authentication.
105 The B<-b> (I<background>) option tells B<sudo> to run the given
106 command in the background. Note that if you use the B<-b>
107 option you cannot use shell job control to manipulate the process.
111 The B<-c> (I<class>) option causes B<sudo> to run the specified command
112 with resources limited by the specified login class. The I<class>
113 argument can be either a class name as defined in C</etc/login.conf>,
114 or a single '-' character. Specifying a I<class> of C<-> indicates
115 that the command should be run restricted by the default login
116 capabilities for the user the command is run as. If the I<class>
117 argument specifies an existing user class, the command must be run
118 as root, or the B<sudo> command must be run from a shell that is already
119 root. This option is only available on systems with BSD login classes.
123 The B<-E> (I<preserve> I<environment>) option will override the
124 I<env_reset> option in L<sudoers(5)>). It is only
125 available when either the matching command has the C<SETENV> tag
126 or the I<setenv> option is set in L<sudoers(5)>.
130 The B<-e> (I<edit>) option indicates that, instead of running
131 a command, the user wishes to edit one or more files. In lieu
132 of a command, the string "sudoedit" is used when consulting
133 the I<sudoers> file. If the user is authorized by I<sudoers>
134 the following steps are taken:
140 Temporary copies are made of the files to be edited with the owner
141 set to the invoking user.
145 The editor specified by the C<VISUAL> or C<EDITOR> environment
146 variables is run to edit the temporary files. If neither C<VISUAL>
147 nor C<EDITOR> are set, the program listed in the I<editor> I<sudoers>
152 If they have been modified, the temporary files are copied back to
153 their original location and the temporary versions are removed.
157 If the specified file does not exist, it will be created. Note
158 that unlike most commands run by B<sudo>, the editor is run with
159 the invoking user's environment unmodified. If, for some reason,
160 B<sudo> is unable to update a file with its edited version, the
161 user will receive a warning and the edited copy will remain in a
166 The B<-H> (I<HOME>) option sets the C<HOME> environment variable
167 to the homedir of the target user (root by default) as specified
168 in passwd(5). By default, B<sudo> does not modify C<HOME>
169 (see I<set_home> and I<always_set_home> in L<sudoers(5)>).
173 The B<-h> (I<help>) option causes B<sudo> to print a usage message and exit.
177 The B<-i> (I<simulate initial login>) option runs the shell specified
178 in the L<passwd(5)> entry of the user that the command is
179 being run as. The command name argument given to the shell begins
180 with a `C<->' to tell the shell to run as a login shell. B<sudo>
181 attempts to change to that user's home directory before running the
182 shell. It also initializes the environment, leaving I<TERM>
183 unchanged, setting I<HOME>, I<SHELL>, I<USER>, I<LOGNAME>, and
184 I<PATH>, and unsetting all other environment variables. Note that
185 because the shell to use is determined before the I<sudoers> file
186 is parsed, a I<runas_default> setting in I<sudoers> will specify
187 the user to run the shell as but will not affect which shell is
192 The B<-K> (sure I<kill>) option is like B<-k> except that it removes
193 the user's timestamp entirely. Like B<-k>, this option does not
198 The B<-k> (I<kill>) option to B<sudo> invalidates the user's timestamp
199 by setting the time on it to the Epoch. The next time B<sudo> is
200 run a password will be required. This option does not require a password
201 and was added to allow a user to revoke B<sudo> permissions from a .logout
206 The B<-L> (I<list> defaults) option will list out the parameters
207 that may be set in a I<Defaults> line along with a short description
208 for each. This option is useful in conjunction with L<grep(1)>.
212 The B<-l> (I<list>) option will list out the allowed (and
213 forbidden) commands for the invoking user on the current host.
217 The B<-P> (I<preserve> I<group vector>) option causes B<sudo> to
218 preserve the invoking user's group vector unaltered. By default,
219 B<sudo> will initialize the group vector to the list of groups the
220 target user is in. The real and effective group IDs, however, are
221 still set to match the target user.
225 The B<-p> (I<prompt>) option allows you to override the default
226 password prompt and use a custom one. The following percent (`C<%>')
227 escapes are supported:
233 expanded to the local hostname including the domain name
234 (on if the machine's hostname is fully qualified or the I<fqdn>
235 I<sudoers> option is set)
239 expanded to the local hostname without the domain name
243 expanded to the login name of the user the command will
244 be run as (defaults to root)
248 expanded to the invoking user's login name
252 two consecutive C<%> characters are collapsed into a single C<%> character
258 The B<-S> (I<stdin>) option causes B<sudo> to read the password from
259 the standard input instead of the terminal device.
263 The B<-s> (I<shell>) option runs the shell specified by the I<SHELL>
264 environment variable if it is set or the shell as specified
269 The B<-u> (I<user>) option causes B<sudo> to run the specified
270 command as a user other than I<root>. To specify a I<uid> instead
271 of a I<username>, use I<#uid>. When running commands as a I<uid>,
272 many shells require that the '#' be escaped with a backslash ('\').
273 Note that if the I<targetpw> Defaults option is set (see L<sudoers(5)>)
274 it is not possible to run commands with a uid not listed in the
279 The B<-V> (I<version>) option causes B<sudo> to print the version
280 number and exit. If the invoking user is already root the B<-V>
281 option will print out a list of the defaults B<sudo> was compiled
282 with as well as the machine's local network addresses.
286 If given the B<-v> (I<validate>) option, B<sudo> will update the
287 user's timestamp, prompting for the user's password if necessary.
288 This extends the B<sudo> timeout for another C<@timeout@> minutes
289 (or whatever the timeout is set to in I<sudoers>) but does not run
294 The B<--> flag indicates that B<sudo> should stop processing command
295 line arguments. It is most useful in conjunction with the B<-s> flag.
299 Environment variables to be set for the command may also be passed
300 on the command line in the form of B<VAR>=I<value>, e.g.
301 B<LD_LIBRARY_PATH>=I</usr/local/pkg/lib>. Variables passed on the
302 command line are subject to the same restrictions as normal environment
303 variables with one important exception. If the I<setenv> option
304 is set in I<sudoers> or the command to be run has the C<SETENV> tag
305 set the user may set variables that would overwise be forbidden.
306 See L<sudoers(5)> for more information.
310 Upon successful execution of a program, the return value from B<sudo>
311 will simply be the return value of the program that was executed.
313 Otherwise, B<sudo> quits with an exit value of 1 if there is a
314 configuration/permission problem or if B<sudo> cannot execute the
315 given command. In the latter case the error string is printed to
316 stderr. If B<sudo> cannot L<stat(2)> one or more entries in the user's
317 C<PATH> an error is printed on stderr. (If the directory does not
318 exist or if it is not really a directory, the entry is ignored and
319 no error is printed.) This should not happen under normal
320 circumstances. The most common reason for L<stat(2)> to return
321 "permission denied" is if you are running an automounter and one
322 of the directories in your C<PATH> is on a machine that is currently
325 =head1 SECURITY NOTES
327 B<sudo> tries to be safe when executing external commands.
329 There are two distinct ways to deal with environment variables.
330 By default, the I<env_reset> I<sudoers> option is enabled.
331 This causes commands to be executed with a minimal environment
332 containing C<TERM>, C<PATH>, C<HOME>, C<SHELL>, C<LOGNAME>, C<USER>
333 and C<USERNAME> in addition to variables from the invoking process
334 permitted by the I<env_check> and I<env_keep> I<sudoers> options.
335 There is effectively a whitelist for environment variables.
337 If, however, the I<env_reset> option is disabled in I<sudoers>, any
338 variables not explicitly denied by the I<env_check> and I<env_delete>
339 options are inherited from the invoking process. In this case,
340 I<env_check> and I<env_delete> behave like a blacklist. Since it
341 is not possible to blacklist all potentially dangerous environment
342 variables, use of the default I<env_reset> behavior is encouraged.
344 In all cases, environment variables with a value beginning with
345 C<()> are removed as they could be interpreted as B<bash> functions.
346 The list of environment variables that B<sudo> allows or denies is
347 contained in the output of C<sudo -V> when run as root.
349 Note that the dynamic linker on most operating systems will remove
350 variables that can control dynamic linking from the environment of
351 setuid executables, including B<sudo>. Depending on the operating
352 system this may include C<_RLD*>, C<DYLD_*>, C<LD_*>, C<LDR_*>,
353 C<LIBPATH>, C<SHLIB_PATH>, and others. These type of variables are
354 removed from the environment before B<sudo> even begins execution
355 and, as such, it is not possible for B<sudo> to preserve them.
357 To prevent command spoofing, B<sudo> checks "." and "" (both denoting
358 current directory) last when searching for a command in the user's
359 PATH (if one or both are in the PATH). Note, however, that the
360 actual C<PATH> environment variable is I<not> modified and is passed
361 unchanged to the program that B<sudo> executes.
363 B<sudo> will check the ownership of its timestamp directory
364 (F<@timedir@> by default) and ignore the directory's contents if
365 it is not owned by root or if it is writable by a user other than
366 root. On systems that allow non-root users to give away files via
367 L<chown(2)>, if the timestamp directory is located in a directory
368 writable by anyone (e.g., F</tmp>), it is possible for a user to
369 create the timestamp directory before B<sudo> is run. However,
370 because B<sudo> checks the ownership and mode of the directory and
371 its contents, the only damage that can be done is to "hide" files
372 by putting them in the timestamp dir. This is unlikely to happen
373 since once the timestamp dir is owned by root and inaccessible by
374 any other user, the user placing files there would be unable to get
375 them back out. To get around this issue you can use a directory
376 that is not world-writable for the timestamps (F</var/adm/sudo> for
377 instance) or create F<@timedir@> with the appropriate owner (root)
378 and permissions (0700) in the system startup files.
380 B<sudo> will not honor timestamps set far in the future.
381 Timestamps with a date greater than current_time + 2 * C<TIMEOUT>
382 will be ignored and sudo will log and complain. This is done to
383 keep a user from creating his/her own timestamp with a bogus
384 date on systems that allow users to give away files.
386 Please note that B<sudo> will normally only log the command it
387 explicitly runs. If a user runs a command such as C<sudo su> or
388 C<sudo sh>, subsequent commands run from that shell will I<not> be
389 logged, nor will B<sudo>'s access control affect them. The same
390 is true for commands that offer shell escapes (including most
391 editors). Because of this, care must be taken when giving users
392 access to commands via B<sudo> to verify that the command does not
393 inadvertently give the user an effective root shell. For more
394 information, please see the C<PREVENTING SHELL ESCAPES> section in
399 B<sudo> utilizes the following environment variables:
405 Default editor to use in B<-e> (sudoedit) mode if C<VISUAL> is not set
409 In B<-s> or B<-H> mode (or if sudo was configured with the
410 --enable-shell-sets-home option), set to homedir of the target user
414 Set to a sane value if the I<secure_path> sudoers option is set.
418 Used to determine shell to run with C<-s> option
422 Used as the default password prompt
424 =item C<SUDO_COMMAND>
426 Set to the command run by sudo
430 Set to the login of the user who invoked sudo
434 Set to the uid of the user who invoked sudo
438 Set to the gid of the user who invoked sudo
442 If set, C<PS1> will be set to its value
446 Set to the target user (root unless the B<-u> option is specified)
450 Default editor to use in B<-e> (sudoedit) mode
458 =item F<@sysconfdir@/sudoers>C< >List of who can run what
460 =item F<@timedir@>C< >Directory containing timestamps
466 Note: the following examples assume suitable L<sudoers(5)> entries.
468 To get a file listing of an unreadable directory:
470 $ sudo ls /usr/local/protected
472 To list the home directory of user yazza on a machine where the
473 file system holding ~yazza is not exported as root:
475 $ sudo -u yazza ls ~yazza
477 To edit the F<index.html> file as user www:
479 $ sudo -u www vi ~www/htdocs/index.html
481 To shutdown a machine:
483 $ sudo shutdown -r +15 "quick reboot"
485 To make a usage listing of the directories in the /home
486 partition. Note that this runs the commands in a sub-shell
487 to make the C<cd> and file redirection work.
489 $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
493 L<grep(1)>, L<su(1)>, L<stat(2)>, L<login_cap(3)>, L<passwd(5)>,
494 L<sudoers(5)>, L<visudo(8)>
498 Many people have worked on B<sudo> over the years; this
499 version consists of code written primarily by:
504 See the HISTORY file in the B<sudo> distribution or visit
505 http://www.sudo.ws/sudo/history.html for a short history
510 There is no easy way to prevent a user from gaining a root shell
511 if that user is allowed to run arbitrary commands via B<sudo>.
512 Also, many programs (such as editors) allow the user to run commands
513 via shell escapes, thus avoiding B<sudo>'s checks. However, on
514 most systems it is possible to prevent shell escapes with B<sudo>'s
515 I<noexec> functionality. See the L<sudoers(5)> manual
518 It is not meaningful to run the C<cd> command directly via sudo, e.g.,
520 $ sudo cd /usr/local/protected
522 since when the command exits the parent process (your shell) will
523 still be the same. Please see the EXAMPLES section for more information.
525 If users have sudo C<ALL> there is nothing to prevent them from
526 creating their own program that gives them a root shell regardless
527 of any '!' elements in the user specification.
529 Running shell scripts via B<sudo> can expose the same kernel bugs that
530 make setuid shell scripts unsafe on some operating systems (if your OS
531 has a /dev/fd/ directory, setuid shell scripts are generally safe).
535 If you feel you have found a bug in B<sudo>, please submit a bug report
536 at http://www.sudo.ws/sudo/bugs/
540 Limited free support is available via the sudo-users mailing list,
541 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
546 B<sudo> is provided ``AS IS'' and any express or implied warranties,
547 including, but not limited to, the implied warranties of merchantability
548 and fitness for a particular purpose are disclaimed. See the LICENSE
549 file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
550 for complete details.