1SUDO(8)                      MAINTENANCE COMMANDS                      SUDO(8)
2
3
4

NAME

6       sudo, sudoedit - execute a command as another user
7

SYNOPSIS

9       sudo -h | -K | -k | -L | -V
10
11       sudo -v [-AknS] [-g group name|#gid] [-p prompt] [-u username|#uid]
12
13       sudo -l[l] [-AknS] [-g group name|#gid] [-p prompt] [-U user name]
14       [-u user name|#uid] [command]
15
16       sudo [-AbEHnPS] [-C fd] [-g group name|#gid] [-p prompt] [-r role]
17       [-t type] [-u user name|#uid] [VAR=value] [-i | -s] [command]
18
19       sudoedit [-AnS] [-C fd] [-g group name|#gid] [-p prompt]
20       [-u user name|#uid] file ...
21

DESCRIPTION

23       sudo allows a permitted user to execute a command as the superuser or
24       another user, as specified in the sudoers file.  The real and effective
25       uid and gid are set to match those of the target user as specified in
26       the passwd file and the group vector is initialized based on the group
27       file (unless the -P option was specified).  If the invoking user is
28       root or if the target user is the same as the invoking user, no
29       password is required.  Otherwise, sudo requires that users authenticate
30       themselves with a password by default (NOTE: in the default
31       configuration this is the user's password, not the root password).
32       Once a user has been authenticated, a time stamp is updated and the
33       user may then use sudo without a password for a short period of time (5
34       minutes unless overridden in sudoers).
35
36       When invoked as sudoedit, the -e option (described below), is implied.
37
38       sudo determines who is an authorized user by consulting the file
39       /etc/sudoers.  By running sudo with the -v option, a user can update
40       the time stamp without running a command.  If a password is required,
41       sudo will exit if the user's password is not entered within a
42       configurable time limit.  The default password prompt timeout is 5
43       minutes.
44
45       If a user who is not listed in the sudoers file tries to run a command
46       via sudo, mail is sent to the proper authorities, as defined at
47       configure time or in the sudoers file (defaults to root).  Note that
48       the mail will not be sent if an unauthorized user tries to run sudo
49       with the -l or -v option.  This allows users to determine for
50       themselves whether or not they are allowed to use sudo.
51
52       If sudo is run by root and the SUDO_USER environment variable is set,
53       sudo will use this value to determine who the actual user is.  This can
54       be used by a user to log commands through sudo even when a root shell
55       has been invoked.  It also allows the -e option to remain useful even
56       when being run via a sudo-run script or program.  Note however, that
57       the sudoers lookup is still done for root, not the user specified by
58       SUDO_USER.
59
60       sudo can log both successful and unsuccessful attempts (as well as
61       errors) to syslog(3), a log file, or both.  By default sudo will log
62       via syslog(3) but this is changeable at configure time or via the
63       sudoers file.
64

OPTIONS

66       sudo accepts the following command line options:
67
68       -A          Normally, if sudo requires a password, it will read it from
69                   the current terminal.  If the -A (askpass) option is
70                   specified, a (possibly graphical) helper program is
71                   executed to read the user's password and output the
72                   password to the standard output.  If the SUDO_ASKPASS
73                   environment variable is set, it specifies the path to the
74                   helper program.  Otherwise, the value specified by the
75                   askpass option in sudoers(5) is used.
76
77       -b          The -b (background) option tells sudo to run the given
78                   command in the background.  Note that if you use the -b
79                   option you cannot use shell job control to manipulate the
80                   process.
81
82       -C fd       Normally, sudo will close all open file descriptors other
83                   than standard input, standard output and standard error.
84                   The -C (close from) option allows the user to specify a
85                   starting point above the standard error (file descriptor
86                   three).  Values less than three are not permitted.  This
87                   option is only available if the administrator has enabled
88                   the closefrom_override option in sudoers(5).
89
90       -E          The -E (preserve environment) option will override the
91                   env_reset option in sudoers(5)).  It is only available when
92                   either the matching command has the SETENV tag or the
93                   setenv option is set in sudoers(5).
94
95       -e          The -e (edit) option indicates that, instead of running a
96                   command, the user wishes to edit one or more files.  In
97                   lieu of a command, the string "sudoedit" is used when
98                   consulting the sudoers file.  If the user is authorized by
99                   sudoers the following steps are taken:
100
101                   1.  Temporary copies are made of the files to be edited
102                       with the owner set to the invoking user.
103
104                   2.  The editor specified by the SUDO_EDITOR, VISUAL or
105                       EDITOR environment variables is run to edit the
106                       temporary files.  If none of SUDO_EDITOR, VISUAL or
107                       EDITOR are set, the first program listed in the editor
108                       sudoers variable is used.
109
110                   3.  If they have been modified, the temporary files are
111                       copied back to their original location and the
112                       temporary versions are removed.
113
114                   If the specified file does not exist, it will be created.
115                   Note that unlike most commands run by sudo, the editor is
116                   run with the invoking user's environment unmodified.  If,
117                   for some reason, sudo is unable to update a file with its
118                   edited version, the user will receive a warning and the
119                   edited copy will remain in a temporary file.
120
121       -g group    Normally, sudo sets the primary group to the one specified
122                   by the passwd database for the user the command is being
123                   run as (by default, root).  The -g (group) option causes
124                   sudo to run the specified command with the primary group
125                   set to group.  To specify a gid instead of a group name,
126                   use #gid.  When running commands as a gid, many shells
127                   require that the '#' be escaped with a backslash ('\').  If
128                   no -u option is specified, the command will be run as the
129                   invoking user (not root).  In either case, the primary
130                   group will be set to group.
131
132       -H          The -H (HOME) option sets the HOME environment variable to
133                   the homedir of the target user (root by default) as
134                   specified in passwd(5).  The default handling of the HOME
135                   environment variable depends on sudoers(5) settings.  By
136                   default, sudo will set HOME if env_reset or always_set_home
137                   are set, or if set_home is set and the -s option is
138                   specified on the command line.
139
140       -h          The -h (help) option causes sudo to print a usage message
141                   and exit.
142
143       -i [command]
144                   The -i (simulate initial login) option runs the shell
145                   specified in the passwd(5) entry of the target user as a
146                   login shell.  This means that login-specific resource files
147                   such as .profile or .login will be read by the shell.  If a
148                   command is specified, it is passed to the shell for
149                   execution.  Otherwise, an interactive shell is executed.
150                   sudo attempts to change to that user's home directory
151                   before running the shell.  It also initializes the
152                   environment, leaving DISPLAY and TERM unchanged, setting
153                   HOME, MAIL, SHELL, USER, LOGNAME, and PATH, as well as the
154                   contents of /etc/environment on Linux and AIX systems.  All
155                   other environment variables are removed.
156
157       -K          The -K (sure kill) option is like -k except that it removes
158                   the user's time stamp entirely and may not be used in
159                   conjunction with a command or other option.  This option
160                   does not require a password.
161
162       -k          When used by itself, the -k (kill) option to sudo
163                   invalidates the user's time stamp by setting the time on it
164                   to the Epoch.  The next time sudo is run a password will be
165                   required.  This option does not require a password and was
166                   added to allow a user to revoke sudo permissions from a
167                   .logout file.
168
169                   When used in conjunction with a command or an option that
170                   may require a password, the -k option will cause sudo to
171                   ignore the user's time stamp file.  As a result, sudo will
172                   prompt for a password (if one is required by sudoers) and
173                   will not update the user's time stamp file.
174
175       -L          The -L (list defaults) option will list the parameters that
176                   may be set in a Defaults line along with a short
177                   description for each.  This option will be removed from a
178                   future version of sudo.
179
180       -l[l] [command]
181                   If no command is specified, the -l (list) option will list
182                   the allowed (and forbidden) commands for the invoking user
183                   (or the user specified by the -U option) on the current
184                   host.  If a command is specified and is permitted by
185                   sudoers, the fully-qualified path to the command is
186                   displayed along with any command line arguments.  If
187                   command is specified but not allowed, sudo will exit with a
188                   status value of 1.  If the -l option is specified with an l
189                   argument (i.e. -ll), or if -l is specified multiple times,
190                   a longer list format is used.
191
192       -n          The -n (non-interactive) option prevents sudo from
193                   prompting the user for a password.  If a password is
194                   required for the command to run, sudo will display an error
195                   messages and exit.
196
197       -P          The -P (preserve group vector) option causes sudo to
198                   preserve the invoking user's group vector unaltered.  By
199                   default, sudo will initialize the group vector to the list
200                   of groups the target user is in.  The real and effective
201                   group IDs, however, are still set to match the target user.
202
203       -p prompt   The -p (prompt) option allows you to override the default
204                   password prompt and use a custom one.  The following
205                   percent (`%') escapes are supported:
206
207                   %H  expanded to the local host name including the domain
208                       name (on if the machine's host name is fully qualified
209                       or the fqdn sudoers option is set)
210
211                   %h  expanded to the local host name without the domain name
212
213                   %p  expanded to the user whose password is being asked for
214                       (respects the rootpw, targetpw and runaspw flags in
215                       sudoers)
216
217                   %U  expanded to the login name of the user the command will
218                       be run as (defaults to root)
219
220                   %u  expanded to the invoking user's login name
221
222                   %%  two consecutive % characters are collapsed into a
223                       single % character
224
225                   The prompt specified by the -p option will override the
226                   system password prompt on systems that support PAM unless
227                   the passprompt_override flag is disabled in sudoers.
228
229       -r role     The -r (role) option causes the new (SELinux) security
230                   context to have the role specified by role.
231
232       -S          The -S (stdin) option causes sudo to read the password from
233                   the standard input instead of the terminal device.  The
234                   password must be followed by a newline character.
235
236       -s [command]
237                   The -s (shell) option runs the shell specified by the SHELL
238                   environment variable if it is set or the shell as specified
239                   in passwd(5).  If a command is specified, it is passed to
240                   the shell for execution.  Otherwise, an interactive shell
241                   is executed.
242
243       -t type     The -t (type) option causes the new (SELinux) security
244                   context to have the type specified by type.  If no type is
245                   specified, the default type is derived from the specified
246                   role.
247
248       -U user     The -U (other user) option is used in conjunction with the
249                   -l option to specify the user whose privileges should be
250                   listed.  Only root or a user with sudo ALL on the current
251                   host may use this option.
252
253       -u user     The -u (user) option causes sudo to run the specified
254                   command as a user other than root.  To specify a uid
255                   instead of a user name, use #uid.  When running commands as
256                   a uid, many shells require that the '#' be escaped with a
257                   backslash ('\').  Note that if the targetpw Defaults option
258                   is set (see sudoers(5)) it is not possible to run commands
259                   with a uid not listed in the password database.
260
261       -V          The -V (version) option causes sudo to print the version
262                   number and exit.  If the invoking user is already root the
263                   -V option will print out a list of the defaults sudo was
264                   compiled with as well as the machine's local network
265                   addresses.
266
267       -v          If given the -v (validate) option, sudo will update the
268                   user's time stamp, prompting for the user's password if
269                   necessary.  This extends the sudo timeout for another 5
270                   minutes (or whatever the timeout is set to in sudoers) but
271                   does not run a command.
272
273       --          The -- option indicates that sudo should stop processing
274                   command line arguments.
275
276       Environment variables to be set for the command may also be passed on
277       the command line in the form of VAR=value, e.g.
278       LD_LIBRARY_PATH=/usr/local/pkg/lib.  Variables passed on the command
279       line are subject to the same restrictions as normal environment
280       variables with one important exception.  If the setenv option is set in
281       sudoers, the command to be run has the SETENV tag set or the command
282       matched is ALL, the user may set variables that would overwise be
283       forbidden.  See sudoers(5) for more information.
284

RETURN VALUES

286       Upon successful execution of a program, the exit status from sudo will
287       simply be the exit status of the program that was executed.
288
289       Otherwise, sudo quits with an exit value of 1 if there is a
290       configuration/permission problem or if sudo cannot execute the given
291       command.  In the latter case the error string is printed to stderr.  If
292       sudo cannot stat(2) one or more entries in the user's PATH an error is
293       printed on stderr.  (If the directory does not exist or if it is not
294       really a directory, the entry is ignored and no error is printed.)
295       This should not happen under normal circumstances.  The most common
296       reason for stat(2) to return "permission denied" is if you are running
297       an automounter and one of the directories in your PATH is on a machine
298       that is currently unreachable.
299

SECURITY NOTES

301       sudo tries to be safe when executing external commands.
302
303       There are two distinct ways to deal with environment variables.  By
304       default, the env_reset sudoers option is enabled.  This causes commands
305       to be executed with a minimal environment containing TERM, PATH, HOME,
306       SHELL, LOGNAME, USER and USERNAME in addition to variables from the
307       invoking process permitted by the env_check and env_keep sudoers
308       options.  There is effectively a whitelist for environment variables.
309
310       If, however, the env_reset option is disabled in sudoers, any variables
311       not explicitly denied by the env_check and env_delete options are
312       inherited from the invoking process.  In this case, env_check and
313       env_delete behave like a blacklist.  Since it is not possible to
314       blacklist all potentially dangerous environment variables, use of the
315       default env_reset behavior is encouraged.
316
317       In all cases, environment variables with a value beginning with () are
318       removed as they could be interpreted as bash functions.  The list of
319       environment variables that sudo allows or denies is contained in the
320       output of sudo -V when run as root.
321
322       Note that the dynamic linker on most operating systems will remove
323       variables that can control dynamic linking from the environment of
324       setuid executables, including sudo.  Depending on the operating system
325       this may include _RLD*, DYLD_*, LD_*, LDR_*, LIBPATH, SHLIB_PATH, and
326       others.  These type of variables are removed from the environment
327       before sudo even begins execution and, as such, it is not possible for
328       sudo to preserve them.
329
330       To prevent command spoofing, sudo checks "." and "" (both denoting
331       current directory) last when searching for a command in the user's PATH
332       (if one or both are in the PATH).  Note, however, that the actual PATH
333       environment variable is not modified and is passed unchanged to the
334       program that sudo executes.
335
336       sudo will check the ownership of its time stamp directory (/var/db/sudo
337       by default) and ignore the directory's contents if it is not owned by
338       root or if it is writable by a user other than root.  On systems that
339       allow non-root users to give away files via chown(2), if the time stamp
340       directory is located in a directory writable by anyone (e.g., /tmp), it
341       is possible for a user to create the time stamp directory before sudo
342       is run.  However, because sudo checks the ownership and mode of the
343       directory and its contents, the only damage that can be done is to
344       "hide" files by putting them in the time stamp dir.  This is unlikely
345       to happen since once the time stamp dir is owned by root and
346       inaccessible by any other user, the user placing files there would be
347       unable to get them back out.  To get around this issue you can use a
348       directory that is not world-writable for the time stamps (/var/adm/sudo
349       for instance) or create /var/db/sudo with the appropriate owner (root)
350       and permissions (0700) in the system startup files.
351
352       sudo will not honor time stamps set far in the future.  Timestamps with
353       a date greater than current_time + 2 * TIMEOUT will be ignored and sudo
354       will log and complain.  This is done to keep a user from creating
355       his/her own time stamp with a bogus date on systems that allow users to
356       give away files.
357
358       On systems where the boot time is available, sudo will also not honor
359       time stamps from before the machine booted.
360
361       Since time stamp files live in the file system, they can outlive a
362       user's login session.  As a result, a user may be able to login, run a
363       command with sudo after authenticating, logout, login again, and run
364       sudo without authenticating so long as the time stamp file's
365       modification time is within 5 minutes (or whatever the timeout is set
366       to in sudoers).  When the tty_tickets option is enabled in sudoers, the
367       time stamp has per-tty granularity but still may outlive the user's
368       session.  On Linux systems where the devpts filesystem is used, Solaris
369       systems with the devices filesystem, as well as other systems that
370       utilize a devfs filesystem that monotonically increase the inode number
371       of devices as they are created (such as Mac OS X), sudo is able to
372       determine when a tty-based time stamp file is stale and will ignore it.
373       Administrators should not rely on this feature as it is not universally
374       available.
375
376       Please note that sudo will normally only log the command it explicitly
377       runs.  If a user runs a command such as sudo su or sudo sh, subsequent
378       commands run from that shell will not be logged, nor will sudo's access
379       control affect them.  The same is true for commands that offer shell
380       escapes (including most editors).  Because of this, care must be taken
381       when giving users access to commands via sudo to verify that the
382       command does not inadvertently give the user an effective root shell.
383       For more information, please see the PREVENTING SHELL ESCAPES section
384       in sudoers(5).
385

ENVIRONMENT

387       sudo utilizes the following environment variables:
388
389       EDITOR          Default editor to use in -e (sudoedit) mode if neither
390                       SUDO_EDITOR nor VISUAL is set
391
392       MAIL            In -i mode or when env_reset is enabled in sudoers, set
393                       to the mail spool of the target user
394
395       HOME            Set to the home directory of the target user if -i or
396                       -H are specified, env_reset or always_set_home are set
397                       in sudoers, or when the -s option is specified and
398                       set_home is set in sudoers
399
400       PATH            Set to a sane value if the secure_path sudoers option
401                       is set.
402
403       SHELL           Used to determine shell to run with -s option
404
405       SUDO_ASKPASS    Specifies the path to a helper program used to read the
406                       password if no terminal is available or if the -A
407                       option is specified.
408
409       SUDO_COMMAND    Set to the command run by sudo
410
411       SUDO_EDITOR     Default editor to use in -e (sudoedit) mode
412
413       SUDO_GID        Set to the group ID of the user who invoked sudo
414
415       SUDO_PROMPT     Used as the default password prompt
416
417       SUDO_PS1        If set, PS1 will be set to its value for the program
418                       being run
419
420       SUDO_UID        Set to the user ID of the user who invoked sudo
421
422       SUDO_USER       Set to the login of the user who invoked sudo
423
424       USER            Set to the target user (root unless the -u option is
425                       specified)
426
427       VISUAL          Default editor to use in -e (sudoedit) mode if
428                       SUDO_EDITOR is not set
429

FILES

431       /etc/sudoers            List of who can run what
432
433       /var/db/sudo            Directory containing time stamps
434
435       /etc/environment        Initial environment for -i mode on Linux and
436                               AIX
437

EXAMPLES

439       Note: the following examples assume suitable sudoers(5) entries.
440
441       To get a file listing of an unreadable directory:
442
443        $ sudo ls /usr/local/protected
444
445       To list the home directory of user yaz on a machine where the file
446       system holding ~yaz is not exported as root:
447
448        $ sudo -u yaz ls ~yaz
449
450       To edit the index.html file as user www:
451
452        $ sudo -u www vi ~www/htdocs/index.html
453
454       To view system logs only accessible to root and users in the adm group:
455
456        $ sudo -g adm view /var/log/syslog
457
458       To run an editor as jim with a different primary group:
459
460        $ sudo -u jim -g audio vi ~jim/sound.txt
461
462       To shutdown a machine:
463
464        $ sudo shutdown -r +15 "quick reboot"
465
466       To make a usage listing of the directories in the /home partition.
467       Note that this runs the commands in a sub-shell to make the cd and file
468       redirection work.
469
470        $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
471

SEE ALSO

473       grep(1), su(1), stat(2), passwd(5), sudoers(5), visudo(8)
474

AUTHORS

476       Many people have worked on sudo over the years; this version consists
477       of code written primarily by:
478
479               Todd C. Miller
480
481       See the HISTORY file in the sudo distribution or visit
482       http://www.sudo.ws/sudo/history.html for a short history of sudo.
483

CAVEATS

485       There is no easy way to prevent a user from gaining a root shell if
486       that user is allowed to run arbitrary commands via sudo.  Also, many
487       programs (such as editors) allow the user to run commands via shell
488       escapes, thus avoiding sudo's checks.  However, on most systems it is
489       possible to prevent shell escapes with sudo's noexec functionality.
490       See the sudoers(5) manual for details.
491
492       It is not meaningful to run the cd command directly via sudo, e.g.,
493
494        $ sudo cd /usr/local/protected
495
496       since when the command exits the parent process (your shell) will still
497       be the same.  Please see the EXAMPLES section for more information.
498
499       If users have sudo ALL there is nothing to prevent them from creating
500       their own program that gives them a root shell regardless of any '!'
501       elements in the user specification.
502
503       Running shell scripts via sudo can expose the same kernel bugs that
504       make setuid shell scripts unsafe on some operating systems (if your OS
505       has a /dev/fd/ directory, setuid shell scripts are generally safe).
506

BUGS

508       If you feel you have found a bug in sudo, please submit a bug report at
509       http://www.sudo.ws/sudo/bugs/
510

SUPPORT

512       Limited free support is available via the sudo-users mailing list, see
513       http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
514       the archives.
515

DISCLAIMER

517       sudo is provided ``AS IS'' and any express or implied warranties,
518       including, but not limited to, the implied warranties of
519       merchantability and fitness for a particular purpose are disclaimed.
520       See the LICENSE file distributed with sudo or
521       http://www.sudo.ws/sudo/license.html for complete details.
522
523
524
5251.7.4                            July 19, 2010                         SUDO(8)
Impressum