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-2012
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@" "July 10, 2012" "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 \fI@sysconfdir@/sudo.conf\fR
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 envionment 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 method and exits.
751 If an I/O logging plugin is configured, a new pseudo-terminal
753 is created and a second
755 process is used to relay job control signals between the user's
756 existing pty and the new pty the command is being run in.
757 This extra process makes it possible to, for example, suspend
758 and resume the command.
759 Without it, the command would be in what POSIX terms an
760 ``orphaned process group''
761 and it would not receive any job control signals.
762 .SS "Signal handling"
763 Because the command is run as a child of the
767 will relay signals it receives to the command.
768 Unless the command is being run in a new pty, the
773 signals are not relayed unless they are sent by a user process,
775 Otherwise, the command would receive
777 twice every time the user entered control-C.
778 Some signals, such as
782 cannot be caught and thus will not be relayed to the command.
785 should be used instead of
787 when you wish to suspend a command being run by
792 will not relay signals that were sent by the command it is running.
793 This prevents the command from accidentally killing itself.
798 to all non-system processes other than itself before rebooting
804 signal it received back to
806 which might then exit before the system was actually rebooted,
807 leaving it in a half-dead state similar to single user mode.
808 Note, however, that this check only applies to the command run by
810 and not any other processes that the command may create.
811 As a result, running a script that calls
814 shutdown(@mansectsu@)
817 may cause the system to end up in this undefined state unless the
820 shutdown(@mansectsu@)
823 family of functions instead of
825 (which interposes a shell between the command and the calling process).
827 Plugins are dynamically loaded based on the contents of the
828 \fI@sysconfdir@/sudo.conf\fR
831 \fI@sysconfdir@/sudo.conf\fR
832 file is present, or it contains no
836 will use the traditional
838 security policy and I/O logging, which corresponds to the following
839 \fI@sysconfdir@/sudo.conf\fR
845 # Default @sysconfdir@/sudo.conf file
848 # Plugin plugin_name plugin_path plugin_options ...
849 # Path askpass /path/to/askpass
850 # Path noexec /path/to/sudo_noexec.so
851 # Debug sudo /var/log/sudo_debug all@warn
852 # Set disable_coredump true
854 # The plugin_path is relative to @prefix@/libexec unless
856 # The plugin_name corresponds to a global symbol in the plugin
857 # that contains the plugin interface structure.
858 # The plugin_options are optional.
860 Plugin policy_plugin sudoers.so
861 Plugin io_plugin sudoers.so
869 keyword, followed by the
873 to the shared object containing the plugin.
877 \fRstruct policy_plugin\fR
879 \fRstruct io_plugin\fR
880 in the plugin shared object.
883 may be fully qualified or relative.
884 If not fully qualified it is relative to the
885 \fI@prefix@/libexec\fR
887 Any additional parameters after the
889 are passed as arguments to the plugin's
892 Lines that don't begin with
898 are silently ignored.
900 For more information, see the
901 sudo_plugin(@mansectsu@)
908 keyword, followed by the name of the path to set and its value.
913 Path noexec @noexec_file@
914 Path askpass /usr/X11R6/bin/ssh-askpass
918 The following plugin-agnostic paths may be set in the
919 \fI@sysconfdir@/sudo.conf\fR
923 The fully qualified path to a helper program used to read the user's
924 password when no terminal is available.
925 This may be the case when
927 is executed from a graphical (as opposed to text-based) application.
928 The program specified by
930 should display the argument passed to it as the prompt and write
931 the user's password to the standard output.
934 may be overridden by the
936 environment variable.
939 The fully-qualified path to a shared library containing dummy
945 library functions that just return an error.
946 This is used to implement the
948 functionality on systems that support
955 versions 1.8.4 and higher support a flexible debugging framework
956 that can help track down what
958 is doing internally if there is a problem.
964 keyword, followed by the name of the program to debug
965 (\fBsudo\fR, \fBvisudo\fR, \fBsudoreplay\fR),
966 the debug file name and a comma-separated list of debug flags.
967 The debug flag syntax used by
972 \fIsubsystem\fR@\fIpriority\fR
973 but the plugin is free to use a different format so long as it does
981 Debug sudo /var/log/sudo_debug all@warn,plugin@info
985 would log all debugging statements at the
987 level and higher in addition to those at the
989 level for the plugin subsystem.
993 entry per program is supported.
997 entry is shared by the
1002 A future release may add support for per-plugin
1004 lines and/or support for multiple debugging files for a single
1007 The priorities used by the
1009 front end, in order of decreasing severity, are:
1010 \fIcrit\fR, \fIerr\fR, \fIwarn\fR, \fInotice\fR, \fIdiag\fR, \fIinfo\fR, \fItrace\fR
1013 Each priority, when specified, also includes all priorities higher
1015 For example, a priority of
1017 would include debug messages logged at
1021 The following subsystems are used by the
1026 matches every subsystem
1029 command line argument processing
1045 network interface handling
1048 communication with the plugin
1051 plugin configuration
1054 pseudo-tty related code
1057 SELinux-specific handling
1065 Upon successful execution of a program, the exit status from
1067 will simply be the exit status of the program that was executed.
1071 exits with a value of 1 if there is a configuration/permission
1074 cannot execute the given command.
1075 In the latter case the error string is printed to the standard error.
1080 one or more entries in the user's
1082 an error is printed on stderr.
1083 (If the directory does not exist or if it is not really a directory,
1084 the entry is ignored and no error is printed.)
1085 This should not happen under normal circumstances.
1086 The most common reason for
1089 ``permission denied''
1090 is if you are running an automounter and one of the directories in
1093 is on a machine that is currently unreachable.
1094 .SH "SECURITY NOTES"
1096 tries to be safe when executing external commands.
1098 To prevent command spoofing,
1100 checks "." and "" (both denoting current directory) last when
1101 searching for a command in the user's
1103 (if one or both are in the
1105 Note, however, that the actual
1107 environment variable is
1109 modified and is passed unchanged to the program that
1115 will normally only log the command it explicitly runs.
1116 If a user runs a command such as
1120 subsequent commands run from that shell are not subject to
1123 The same is true for commands that offer shell escapes (including
1125 If I/O logging is enabled, subsequent commands will have their input and/or
1126 output logged, but there will not be traditional logs for those commands.
1127 Because of this, care must be taken when giving users access to commands via
1129 to verify that the command does not inadvertently give the user an
1130 effective root shell.
1131 For more information, please see the
1132 \fIPREVENTING SHELL ESCAPES\fR
1134 sudoers(@mansectform@).
1136 To prevent the disclosure of potentially sensitive information,
1138 disables core dumps by default while it is executing (they are
1139 re-enabled for the command that is run).
1142 crashes, you may wish to re-enable core dumps by setting
1143 ``disable_coredump''
1145 \fI@sysconfdir@/sudo.conf\fR
1150 Set disable_coredump false
1154 Note that by default, most operating systems disable core dumps
1155 from setuid programs, which includes
1159 core file you may need to enable core dumps for setuid processes.
1160 On BSD and Linux systems this is accomplished via the sysctl command,
1161 on Solaris the coreadm command can be used.
1164 utilizes the following environment variables.
1165 The security policy has control over the actual content of the command's
1169 Default editor to use in
1171 (sudoedit) mode if neither
1184 set to the mail spool of the target user.
1187 Set to the home directory of the target user if
1194 \fIalways_set_home\fR
1199 option is specified and
1205 May be overridden by the security policy.
1208 Used to determine shell to run with
1213 Specifies the path to a helper program used to read the password
1214 if no terminal is available or if the
1216 option is specified.
1219 Set to the command run by sudo.
1222 Default editor to use in
1227 Set to the group ID of the user who invoked sudo.
1230 Used as the default password prompt.
1235 will be set to its value for the program being run.
1238 Set to the user ID of the user who invoked sudo.
1241 Set to the login name of the user who invoked sudo.
1244 Set to the target user (root unless the
1246 option is specified).
1249 Default editor to use in
1256 \fI@sysconfdir@/sudo.conf\fR
1258 front end configuration
1260 Note: the following examples assume a properly configured security
1263 To get a file listing of an unreadable directory:
1267 $ sudo ls /usr/local/protected
1271 To list the home directory of user yaz on a machine where the file
1272 system holding ~yaz is not exported as root:
1276 $ sudo -u yaz ls ~yaz
1286 $ sudo -u www vi ~www/htdocs/index.html
1290 To view system logs only accessible to root and users in the adm
1295 $ sudo -g adm view /var/log/syslog
1299 To run an editor as jim with a different primary group:
1303 $ sudo -u jim -g audio vi ~jim/sound.txt
1307 To shut down a machine:
1311 $ sudo shutdown -r +15 "quick reboot"
1315 To make a usage listing of the directories in the /home partition.
1316 Note that this runs the commands in a sub-shell to make the
1318 and file redirection work.
1322 $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
1330 passwd(@mansectform@),
1331 sudoers(@mansectform@),
1332 sudo_plugin(@mansectsu@),
1333 sudoreplay(@mansectsu@),
1336 See the HISTORY file in the
1338 distribution (http://www.sudo.ws/sudo/history.html) for a brief
1341 Many people have worked on
1343 over the years; this version consists of code written primarily by:
1349 See the CONTRIBUTORS file in the
1351 distribution (http://www.sudo.ws/sudo/contributors.html) for an
1352 exhaustive list of people who have contributed to
1355 There is no easy way to prevent a user from gaining a root shell
1356 if that user is allowed to run arbitrary commands via
1358 Also, many programs (such as editors) allow the user to run commands
1359 via shell escapes, thus avoiding
1362 However, on most systems it is possible to prevent shell escapes with the
1363 sudoers(@mansectform@)
1368 It is not meaningful to run the
1370 command directly via sudo, e.g.,
1374 $ sudo cd /usr/local/protected
1378 since when the command exits the parent process (your shell) will
1382 section for more information.
1384 Running shell scripts via
1386 can expose the same kernel bugs that make setuid shell scripts
1387 unsafe on some operating systems (if your OS has a /dev/fd/ directory,
1388 setuid shell scripts are generally safe).
1390 If you feel you have found a bug in
1392 please submit a bug report at http://www.sudo.ws/sudo/bugs/
1394 Limited free support is available via the sudo-users mailing list,
1395 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1396 search the archives.
1401 and any express or implied warranties, including, but not limited
1402 to, the implied warranties of merchantability and fitness for a
1403 particular purpose are disclaimed.
1404 See the LICENSE file distributed with
1406 or http://www.sudo.ws/sudo/license.html for complete details.
projects / debian / sudo / blob