1 .\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!
2 .\" IT IS GENERATED AUTOMATICALLY FROM sudo.mdoc.in
4 .\" Copyright (c) 1994-1996, 1998-2005, 2007-2013
5 .\" Todd C. Miller <Todd.Miller@courtesan.com>
7 .\" Permission to use, copy, modify, and distribute this software for any
8 .\" purpose with or without fee is hereby granted, provided that the above
9 .\" copyright notice and this permission notice appear in all copies.
11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
20 .\" Sponsored in part by the Defense Advanced Research Projects
21 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
22 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
24 .TH "SUDO" "@mansectsu@" "March 13, 2013" "Sudo @PACKAGE_VERSION@" "System Manager's Manual"
30 \- execute a command as another user
34 \fB\-h\fR | \fB\-K\fR | \fB\-k\fR | \fB\-V\fR
40 [\fB\-a\fR\ \fIauth_type\fR]
41 [\fB\-g\fR\ \fIgroup\ name\fR\ |\ \fI#gid\fR]
42 [\fB\-p\fR\ \fIprompt\fR]
43 [\fB\-u\fR\ \fIuser\ name\fR\ |\ \fI#uid\fR]
49 [\fB\-a\fR\ \fIauth_type\fR]
50 [\fB\-g\fR\ \fIgroup\ name\fR\ |\ \fI#gid\fR]
51 [\fB\-p\fR\ \fIprompt\fR]
52 [\fB\-U\fR\ \fIuser\ name\fR]
53 [\fB\-u\fR\ \fIuser\ name\fR\ |\ \fI#uid\fR]
59 [\fB\-a\fR\ \fIauth_type\fR]
61 [\fB\-c\fR\ \fIclass\fR\ |\ \fI-\fR]
62 [\fB\-g\fR\ \fIgroup\ name\fR\ |\ \fI#gid\fR]
63 [\fB\-p\fR\ \fIprompt\fR]
64 [\fB\-r\fR\ \fIrole\fR]
65 [\fB\-t\fR\ \fItype\fR]
66 [\fB\-u\fR\ \fIuser\ name\fR\ |\ \fI#uid\fR]
67 [\fBVAR\fR=\fIvalue\fR]
68 \fB\-i\fR\ |\ \fB\-s\fR
74 [\fB\-a\fR\ \fIauth_type\fR]
76 [\fB\-c\fR\ \fIclass\fR\ |\ \fI-\fR]
77 [\fB\-g\fR\ \fIgroup\ name\fR\ |\ \fI#gid\fR]
78 [\fB\-p\fR\ \fIprompt\fR]
79 [\fB\-u\fR\ \fIuser\ name\fR\ |\ \fI#uid\fR]
84 allows a permitted user to execute a
86 as the superuser or another user, as specified by the security
90 supports a plugin architecture for security policies and input/output
92 Third parties can develop and distribute their own policy and I/O
93 logging plugins to work seamlessly with the
96 The default security policy is
98 which is configured via the file
99 \fI@sysconfdir@/sudoers\fR,
103 section for more information.
105 The security policy determines what privileges, if any, a user has
108 The policy may require that users authenticate themselves with a
109 password or another authentication mechanism.
110 If authentication is required,
112 will exit if the user's password is not entered within a configurable
114 This limit is policy-specific; the default password prompt timeout
118 \fR@password_timeout@\fR
121 Security policies may support credential caching to allow the user
124 again for a period of time without requiring authentication.
127 policy caches credentials for
129 minutes, unless overridden in
130 sudoers(@mansectform@).
135 option, a user can update the cached credentials without running a
142 option (described below), is implied.
144 Security policies may log successful and failed attempts to use
146 If an I/O plugin is configured, the running command's input and
147 output may be logged as well.
149 The options are as follows:
154 requires a password, it will read it from the user's terminal.
156 \fB\-A\fR (\fIaskpass\fR)
157 option is specified, a (possibly graphical) helper program is
158 executed to read the user's password and output the password to the
162 environment variable is set, it specifies the path to the helper
165 sudo.conf(@mansectform@)
166 contains a line specifying the askpass program, that value will be
173 # Path to askpass helper program
174 Path askpass /usr/X11R6/bin/ssh-askpass
178 If no askpass program is available,
180 will exit with an error.
187 \fB\-a\fR (\fIauthentication type\fR)
190 to use the specified authentication type when validating the user,
192 \fI/etc/login.conf\fR.
193 The system administrator may specify a list of sudo-specific
194 authentication methods by adding an
197 \fI/etc/login.conf\fR.
198 This option is only available on systems that support BSD authentication.
203 \fB\-b\fR (\fIbackground\fR)
206 to run the given command in the background.
207 Note that if you use the
209 option you cannot use shell job control to manipulate the process.
210 Most interactive commands will fail to work properly in background
216 will close all open file descriptors other than standard input,
217 standard output and standard error.
219 \fB\-C\fR (\fIclose from\fR)
220 option allows the user to specify a starting point above the standard
221 error (file descriptor three).
222 Values less than three are not permitted.
223 The security policy may restrict the user's ability to use the
228 policy only permits use of the
230 option when the administrator has enabled the
231 \fIclosefrom_override\fR
234 \fB\-c\fR \fIclass\fR
236 \fB\-c\fR (\fIclass\fR)
239 to run the specified command with resources limited by the specified
243 argument can be either a class name as defined in
244 \fI/etc/login.conf\fR,
252 indicates that the command should be run restricted by the default
253 login capabilities for the user the command is run as.
256 argument specifies an existing user class, the command must be run
259 command must be run from a shell that is already root.
260 This option is only available on systems with BSD login classes.
264 \fB\-E\fR (\fIpreserve environment\fR)
265 option indicates to the security policy that the user wishes to
266 preserve their existing environment variables.
267 The security policy may return an error if the
269 option is specified and the user does not have permission to preserve
274 \fB\-e\fR (\fIedit\fR)
275 option indicates that, instead of running a command, the user wishes
276 to edit one or more files.
277 In lieu of a command, the string "sudoedit" is used when consulting
279 If the user is authorized by the policy, the following steps are
284 Temporary copies are made of the files to be edited with the owner
285 set to the invoking user.
288 The editor specified by the policy is run to edit the temporary
297 environment variables (in that order).
303 are set, the first program listed in the
305 sudoers(@mansectform@)
309 If they have been modified, the temporary files are copied back to
310 their original location and the temporary versions are removed.
312 If the specified file does not exist, it will be created.
313 Note that unlike most commands run by
315 the editor is run with the invoking user's environment unmodified.
318 is unable to update a file with its edited version, the user will
319 receive a warning and the edited copy will remain in a temporary
325 \fB\-g\fR \fIgroup\fR
328 runs a command with the primary group set to the one specified by
329 the password database for the user the command is being run as (by
332 \fB\-g\fR (\fIgroup\fR)
335 to run the command with the primary group set to
344 When running commands as a
346 many shells require that the
348 be escaped with a backslash
352 option is specified, the command will be run as the invoking user
354 In either case, the primary group will be set to
360 \fB\-H\fR (\fIHOME\fR)
361 option requests that the security policy set the
363 environment variable to the home directory of the target user (root
364 by default) as specified by the password database.
365 Depending on the policy, this may be the default behavior.
369 \fB\-h\fR (\fIhelp\fR)
372 to print a short help message to the standard output and exit.
374 \fB\-i\fR [\fIcommand\fR]
376 \fB\-i\fR (\fIsimulate initial login\fR)
377 option runs the shell specified by the password database entry of
378 the target user as a login shell.
379 This means that login-specific resource files such as
383 will be read by the shell.
384 If a command is specified, it is passed to the shell for execution
388 If no command is specified, an interactive shell is executed.
390 attempts to change to that user's home directory before running the
392 The security policy shall initialize the environment to a minimal
393 set of variables, similar to what is present when a user logs in.
395 \fICommand Environment\fR
397 sudoers(@mansectform@)
398 manual documents how the
400 option affects the environment in which a command is run when the
406 \fB\-K\fR (sure \fIkill\fR)
409 except that it removes the user's cached credentials entirely and
410 may not be used in conjunction with a command or other option.
411 This option does not require a password.
412 Not all security policies support credential caching.
414 \fB\-k\fR [\fIcommand\fR]
416 \fB\-k\fR (\fIkill\fR)
419 invalidates the user's cached credentials.
422 is run a password will be required.
423 This option does not require a password and was added to allow a
429 Not all security policies support credential caching.
431 When used in conjunction with a command or an option that may require
436 to ignore the user's cached credentials.
439 will prompt for a password (if one is required by the security
440 policy) and will not update the user's cached credentials.
442 \fB\-l\fR[\fBl\fR] [\fIcommand\fR]
446 \fB\-l\fR (\fIlist\fR)
447 option will list the allowed (and forbidden) commands for the
448 invoking user (or the user specified by the
450 option) on the current host.
453 is specified and is permitted by the security policy, the fully-qualified
454 path to the command is displayed along with any command line
458 is specified but not allowed,
460 will exit with a status value of 1.
463 option is specified with an
469 is specified multiple times, a longer list format is used.
473 \fB\-n\fR (\fInon-interactive\fR)
476 from prompting the user for a password.
477 If a password is required for the command to run,
479 will display an error message and exit.
483 \fB\-P\fR (\fIpreserve group vector\fR)
486 to preserve the invoking user's group vector unaltered.
489 policy will initialize the group vector to the list of groups the
491 The real and effective group IDs, however, are still set to match
494 \fB\-p\fR \fIprompt\fR
496 \fB\-p\fR (\fIprompt\fR)
497 option allows you to override the default password prompt and use
499 The following percent
501 escapes are supported by the
507 expanded to the host name including the domain name (on if the
508 machine's host name is fully qualified or the
511 sudoers(@mansectform@))
514 expanded to the local host name without the domain name
517 expanded to the name of the user whose password is being requested
524 sudoers(@mansectform@))
527 expanded to the login name of the user the command will be run as
528 (defaults to root unless the
530 option is also specified)
533 expanded to the invoking user's login name
538 characters are collapsed into a single
542 The prompt specified by the
544 option will override the system password prompt on systems that
545 support PAM unless the
546 \fIpassprompt_override\fR
555 \fB\-r\fR (\fIrole\fR)
556 option causes the new (SELinux) security context to have the role
563 \fB\-S\fR (\fIstdin\fR)
566 to read the password from the standard input instead of the terminal
568 The password must be followed by a newline character.
570 \fB\-s\fR [\fIcommand\fR]
572 \fB\-s\fR (\fIshell\fR)
573 option runs the shell specified by the
575 environment variable if it is set or the shell as specified in the
577 If a command is specified, it is passed to the shell for execution
581 If no command is specified, an interactive shell is executed.
585 \fB\-t\fR (\fItype\fR)
586 option causes the new (SELinux) security context to have the type
589 If no type is specified, the default type is derived from the
594 \fB\-U\fR (\fIother user\fR)
595 option is used in conjunction with the
597 option to specify the user whose privileges should be listed.
598 The security policy may restrict listing other users' privileges.
601 policy only allows root or a user with the
603 privilege on the current host to use this option.
607 \fB\-u\fR (\fIuser\fR)
610 to run the specified command as a user other than
617 When running commands as a
619 many shells require that the
621 be escaped with a backslash
623 Security policies may restrict
625 to those listed in the password database.
630 that are not in the password database as long as the
633 Other security policies may not support this.
637 \fB\-V\fR (\fIversion\fR)
640 to print its version string and the version string of the security
641 policy plugin and any I/O plugins.
642 If the invoking user is already root the
644 option will display the arguments passed to configure when
646 was built and plugins may display more verbose information such as
651 \fB\-v\fR (\fIvalidate\fR)
654 will update the user's cached credentials, authenticating the user's
655 password if necessary.
658 plugin, this extends the
662 minutes (or whatever the timeout is set to by the security policy)
663 but does not run a command.
664 Not all security policies support cached credentials.
669 option indicates that
671 should stop processing command line arguments.
673 Environment variables to be set for the command may also be passed
674 on the command line in the form of
675 \fBVAR\fR=\fIvalue\fR,
677 \fBLD_LIBRARY_PATH\fR=\fI/usr/local/pkg/lib\fR.
678 Variables passed on the command line are subject to the same
679 restrictions as normal environment variables with one important
685 the command to be run has the
687 tag set or the command matched is
689 the user may set variables that would otherwise be forbidden.
691 sudoers(@mansectform@)
692 for more information.
693 .SH "COMMAND EXECUTION"
696 executes a command, the security policy specifies the execution
697 environment for the command.
698 Typically, the real and effective uid and gid are set to
699 match those of the target user, as specified in the password database,
700 and the group vector is initialized based on the group database
703 option was specified).
705 The following parameters may be specified by security policy:
708 real and effective user ID
711 real and effective group ID
714 supplementary group IDs
720 current working directory
723 file creation mode mask (umask)
726 SELinux role and type
738 scheduling priority (aka nice value)
742 runs a command, it calls
744 sets up the execution environment as described above, and calls the
746 system call in the child process.
749 process waits until the command has completed, then passes the
750 command's exit status to the security policy's close function and exits.
751 If an I/O logging plugin is configured or if the security policy
752 explicitly requests it, a new pseudo-terminal
754 is created and a second
756 process is used to relay job control signals between the user's
757 existing pty and the new pty the command is being run in.
758 This extra process makes it possible to, for example, suspend
759 and resume the command.
760 Without it, the command would be in what POSIX terms an
761 ``orphaned process group''
762 and it would not receive any job control signals.
763 As a special case, if the policy plugin does not define a close
764 function and no pty is required,
766 will execute the command directly instead of calling
769 .SS "Signal handling"
770 Because the command is run as a child of the
774 will relay signals it receives to the command.
775 Unless the command is being run in a new pty, the
780 signals are not relayed unless they are sent by a user process,
782 Otherwise, the command would receive
784 twice every time the user entered control-C.
785 Some signals, such as
789 cannot be caught and thus will not be relayed to the command.
792 should be used instead of
794 when you wish to suspend a command being run by
799 will not relay signals that were sent by the command it is running.
800 This prevents the command from accidentally killing itself.
805 to all non-system processes other than itself before rebooting
811 signal it received back to
813 which might then exit before the system was actually rebooted,
814 leaving it in a half-dead state similar to single user mode.
815 Note, however, that this check only applies to the command run by
817 and not any other processes that the command may create.
818 As a result, running a script that calls
821 shutdown(@mansectsu@)
824 may cause the system to end up in this undefined state unless the
827 shutdown(@mansectsu@)
830 family of functions instead of
832 (which interposes a shell between the command and the calling process).
834 If no I/O logging plugins are loaded and the policy plugin has not
837 function, set a command timeout or required that the command be
840 may execute the command directly instead of running it as a child process.
842 Plugins are dynamically loaded based on the contents of the
843 sudo.conf(@mansectform@)
846 sudo.conf(@mansectform@)
847 file is present, or it contains no
851 will use the traditional
853 security policy and I/O logging.
855 sudo.conf(@mansectform@)
856 manual for details of the
857 \fI@sysconfdir@/sudo.conf\fR
859 sudo_plugin(@mansectsu@)
860 manual for more information about the
864 Upon successful execution of a program, the exit status from
866 will simply be the exit status of the program that was executed.
870 exits with a value of 1 if there is a configuration/permission
873 cannot execute the given command.
874 In the latter case the error string is printed to the standard error.
879 one or more entries in the user's
881 an error is printed on stderr.
882 (If the directory does not exist or if it is not really a directory,
883 the entry is ignored and no error is printed.)
884 This should not happen under normal circumstances.
885 The most common reason for
888 ``permission denied''
889 is if you are running an automounter and one of the directories in
892 is on a machine that is currently unreachable.
895 tries to be safe when executing external commands.
897 To prevent command spoofing,
899 checks "." and "" (both denoting current directory) last when
900 searching for a command in the user's
902 (if one or both are in the
904 Note, however, that the actual
906 environment variable is
908 modified and is passed unchanged to the program that
914 will normally only log the command it explicitly runs.
915 If a user runs a command such as
919 subsequent commands run from that shell are not subject to
922 The same is true for commands that offer shell escapes (including
924 If I/O logging is enabled, subsequent commands will have their input and/or
925 output logged, but there will not be traditional logs for those commands.
926 Because of this, care must be taken when giving users access to commands via
928 to verify that the command does not inadvertently give the user an
929 effective root shell.
930 For more information, please see the
931 \fIPREVENTING SHELL ESCAPES\fR
933 sudoers(@mansectform@).
935 To prevent the disclosure of potentially sensitive information,
937 disables core dumps by default while it is executing (they are
938 re-enabled for the command that is run).
941 crashes, you may wish to re-enable core dumps by setting
944 sudo.conf(@mansectform@)
949 Set disable_coredump false
954 sudo.conf(@mansectform@)
955 manual for more information.
958 utilizes the following environment variables.
959 The security policy has control over the actual content of the command's
963 Default editor to use in
965 (sudoedit) mode if neither
978 set to the mail spool of the target user.
981 Set to the home directory of the target user if
988 \fIalways_set_home\fR
993 option is specified and
999 May be overridden by the security policy.
1002 Used to determine shell to run with
1007 Specifies the path to a helper program used to read the password
1008 if no terminal is available or if the
1010 option is specified.
1013 Set to the command run by sudo.
1016 Default editor to use in
1021 Set to the group ID of the user who invoked sudo.
1024 Used as the default password prompt.
1029 will be set to its value for the program being run.
1032 Set to the user ID of the user who invoked sudo.
1035 Set to the login name of the user who invoked sudo.
1038 Set to the target user (root unless the
1040 option is specified).
1043 Default editor to use in
1050 \fI@sysconfdir@/sudo.conf\fR
1052 front end configuration
1054 Note: the following examples assume a properly configured security
1057 To get a file listing of an unreadable directory:
1061 $ sudo ls /usr/local/protected
1065 To list the home directory of user yaz on a machine where the file
1066 system holding ~yaz is not exported as root:
1070 $ sudo -u yaz ls ~yaz
1080 $ sudo -u www vi ~www/htdocs/index.html
1084 To view system logs only accessible to root and users in the adm
1089 $ sudo -g adm view /var/log/syslog
1093 To run an editor as jim with a different primary group:
1097 $ sudo -u jim -g audio vi ~jim/sound.txt
1101 To shut down a machine:
1105 $ sudo shutdown -r +15 "quick reboot"
1109 To make a usage listing of the directories in the /home partition.
1110 Note that this runs the commands in a sub-shell to make the
1112 and file redirection work.
1116 $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
1123 passwd(@mansectform@),
1124 sudo.conf(@mansectform@),
1125 sudoers(@mansectform@),
1126 sudo_plugin(@mansectsu@),
1127 sudoreplay(@mansectsu@),
1130 See the HISTORY file in the
1132 distribution (http://www.sudo.ws/sudo/history.html) for a brief
1135 Many people have worked on
1137 over the years; this version consists of code written primarily by:
1143 See the CONTRIBUTORS file in the
1145 distribution (http://www.sudo.ws/sudo/contributors.html) for an
1146 exhaustive list of people who have contributed to
1149 There is no easy way to prevent a user from gaining a root shell
1150 if that user is allowed to run arbitrary commands via
1152 Also, many programs (such as editors) allow the user to run commands
1153 via shell escapes, thus avoiding
1156 However, on most systems it is possible to prevent shell escapes with the
1157 sudoers(@mansectform@)
1162 It is not meaningful to run the
1164 command directly via sudo, e.g.,
1168 $ sudo cd /usr/local/protected
1172 since when the command exits the parent process (your shell) will
1176 section for more information.
1178 Running shell scripts via
1180 can expose the same kernel bugs that make setuid shell scripts
1181 unsafe on some operating systems (if your OS has a /dev/fd/ directory,
1182 setuid shell scripts are generally safe).
1184 If you feel you have found a bug in
1186 please submit a bug report at http://www.sudo.ws/sudo/bugs/
1188 Limited free support is available via the sudo-users mailing list,
1189 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1190 search the archives.
1195 and any express or implied warranties, including, but not limited
1196 to, the implied warranties of merchantability and fitness for a
1197 particular purpose are disclaimed.
1198 See the LICENSE file distributed with
1200 or http://www.sudo.ws/sudo/license.html for complete details.
projects / debian / sudo / blob