2 .\" Copyright (c) 1994-1996, 1998-2005, 2007-2012
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.
24 .Os Sudo @PACKAGE_VERSION@
28 .Nd execute a command as another user
31 .Fl h No | Fl K No | Fl k No | Fl V
39 .Op Fl g Ar group name No | Ar #gid
45 .Op Fl u Ar user name No | Ar #uid
54 .Op Fl g Ar group name No | Ar #gid
63 .Op Fl u Ar user name No | Ar #uid
75 .Op Fl c Ar class No | Ar -
78 .Op Fl g Ar group name No | Ar #gid
90 .Op Fl u Ar user name No | Ar #uid
93 .Op Sy VAR Ns = Ns Ar value
102 .Op Fl a Ar auth_type
108 .Op Fl c Ar class No | Ar -
111 .Op Fl g Ar group name No | Ar #gid
117 .Op Fl u Ar user name No | Ar #uid
124 allows a permitted user to execute a
126 as the superuser or another user, as specified by the security
130 supports a plugin architecture for security policies and input/output
132 Third parties can develop and distribute their own policy and I/O
133 logging plugins to work seamlessly with the
136 The default security policy is
138 which is configured via the file
139 .Pa @sysconfdir@/sudoers ,
143 section for more information.
145 The security policy determines what privileges, if any, a user has
148 The policy may require that users authenticate themselves with a
149 password or another authentication mechanism.
150 If authentication is required,
152 will exit if the user's password is not entered within a configurable
154 This limit is policy-specific; the default password prompt timeout
158 .Li @password_timeout@
161 Security policies may support credential caching to allow the user
164 again for a period of time without requiring authentication.
167 policy caches credentials for
169 minutes, unless overridden in
170 .Xr sudoers @mansectform@ .
175 option, a user can update the cached credentials without running a
182 option (described below), is implied.
184 Security policies may log successful and failed attempts to use
186 If an I/O plugin is configured, the running command's input and
187 output may be logged as well.
189 The options are as follows:
194 requires a password, it will read it from the user's terminal.
196 .Fl A No ( Em askpass Ns No )
197 option is specified, a (possibly graphical) helper program is
198 executed to read the user's password and output the password to the
202 environment variable is set, it specifies the path to the helper
205 .Pa @sysconfdir@/sudo.conf
206 contains a line specifying the askpass program, that value will be
209 .Bd -literal -offset 4n
210 # Path to askpass helper program
211 Path askpass /usr/X11R6/bin/ssh-askpass
214 If no askpass program is available,
216 will exit with an error.
219 .Fl a No ( Em "authentication type" Ns No )
222 to use the specified authentication type when validating the user,
224 .Pa /etc/login.conf .
225 The system administrator may specify a list of sudo-specific
226 authentication methods by adding an
229 .Pa /etc/login.conf .
230 This option is only available on systems that support BSD authentication.
233 .Fl b No ( Em background Ns No )
236 to run the given command in the background.
237 Note that if you use the
239 option you cannot use shell job control to manipulate the process.
240 Most interactive commands will fail to work properly in background
245 will close all open file descriptors other than standard input,
246 standard output and standard error.
248 .Fl C No ( Em close from Ns No )
249 option allows the user to specify a starting point above the standard
250 error (file descriptor three).
251 Values less than three are not permitted.
252 The security policy may restrict the user's ability to use the
257 policy only permits use of the
259 option when the administrator has enabled the
260 .Em closefrom_override
264 .Fl c No ( Em class Ns No )
267 to run the specified command with resources limited by the specified
271 argument can be either a class name as defined in
272 .Pa /etc/login.conf ,
280 indicates that the command should be run restricted by the default
281 login capabilities for the user the command is run as.
284 argument specifies an existing user class, the command must be run
287 command must be run from a shell that is already root.
288 This option is only available on systems with BSD login classes.
291 .Fl E No ( Em preserve environment Ns No )
292 option indicates to the security policy that the user wishes to
293 preserve their existing environment variables.
294 The security policy may return an error if the
296 option is specified and the user does not have permission to preserve
300 .Fl e No ( Em edit Ns No )
301 option indicates that, instead of running a command, the user wishes
302 to edit one or more files.
303 In lieu of a command, the string "sudoedit" is used when consulting
305 If the user is authorized by the policy, the following steps are
309 Temporary copies are made of the files to be edited with the owner
310 set to the invoking user.
312 The editor specified by the policy is run to edit the temporary
321 environment variables (in that order).
327 are set, the first program listed in the
329 .Xr sudoers @mansectform@
332 If they have been modified, the temporary files are copied back to
333 their original location and the temporary versions are removed.
336 If the specified file does not exist, it will be created.
337 Note that unlike most commands run by
339 the editor is run with the invoking user's environment unmodified.
342 is unable to update a file with its edited version, the user will
343 receive a warning and the edited copy will remain in a temporary
348 runs a command with the primary group set to the one specified by
349 the password database for the user the command is being run as (by
352 .Fl g No ( Em group Ns No )
355 to run the command with the primary group set to
364 When running commands as a
366 many shells require that the
368 be escaped with a backslash
372 option is specified, the command will be run as the invoking user
374 In either case, the primary group will be set to
378 .Fl H No ( Em HOME Ns No )
379 option requests that the security policy set the
381 environment variable to the home directory of the target user (root
382 by default) as specified by the password database.
383 Depending on the policy, this may be the default behavior.
386 .Fl h No ( Em help Ns No )
389 to print a short help message to the standard output and exit.
390 .It Fl i Op Ar command
392 .Fl i No ( Em simulate initial login Ns No )
393 option runs the shell specified by the password database entry of
394 the target user as a login shell.
395 This means that login-specific resource files such as
399 will be read by the shell.
400 If a command is specified, it is passed to the shell for execution
404 If no command is specified, an interactive shell is executed.
406 attempts to change to that user's home directory before running the
408 The security policy shall initialize the environment to a minimal
409 set of variables, similar to what is present when a user logs in.
411 .Em Command Environment
413 .Xr sudoers @mansectform@
414 manual documents how the
416 option affects the environment in which a command is run when the
421 .Fl K No ( sure Em kill Ns No )
424 except that it removes the user's cached credentials entirely and
425 may not be used in conjunction with a command or other option.
426 This option does not require a password.
427 Not all security policies support credential caching.
428 .It Fl k Op Ar command
430 .Fl k No ( Em kill Ns No )
433 invalidates the user's cached credentials.
436 is run a password will be required.
437 This option does not require a password and was added to allow a
443 Not all security policies support credential caching.
445 When used in conjunction with a command or an option that may require
450 to ignore the user's cached credentials.
453 will prompt for a password (if one is required by the security
454 policy) and will not update the user's cached credentials.
455 .It Fl l Ns Oo Sy l Oc Op Ar command
459 .Fl l No ( Em list Ns No )
460 option will list the allowed (and forbidden) commands for the
461 invoking user (or the user specified by the
463 option) on the current host.
466 is specified and is permitted by the security policy, the fully-qualified
467 path to the command is displayed along with any command line
471 is specified but not allowed,
473 will exit with a status value of 1.
476 option is specified with an
482 is specified multiple times, a longer list format is used.
485 .Fl n No ( Em non-interactive Ns No )
488 from prompting the user for a password.
489 If a password is required for the command to run,
491 will display an error message and exit.
494 .Fl P No ( Em preserve group vector Ns No )
497 to preserve the invoking user's group vector unaltered.
500 policy will initialize the group vector to the list of groups the
502 The real and effective group IDs, however, are still set to match
506 .Fl p No ( Em prompt Ns No )
507 option allows you to override the default password prompt and use
509 The following percent
511 escapes are supported by the
516 expanded to the host name including the domain name (on if the
517 machine's host name is fully qualified or the
520 .Xr sudoers @mansectform@ )
522 expanded to the local host name without the domain name
524 expanded to the name of the user whose password is being requested
531 .Xr sudoers @mansectform@ )
533 expanded to the login name of the user the command will be run as
534 (defaults to root unless the
536 option is also specified)
538 expanded to the invoking user's login name
542 characters are collapsed into a single
547 The prompt specified by the
549 option will override the system password prompt on systems that
550 support PAM unless the
551 .Em passprompt_override
556 .Fl r No ( Em role Ns No )
557 option causes the new (SELinux) security context to have the role
562 .Fl S ( Em stdin Ns No )
565 to read the password from the standard input instead of the terminal
567 The password must be followed by a newline character.
568 .It Fl s Op Ar command
570 .Fl s ( Em shell Ns No )
571 option runs the shell specified by the
573 environment variable if it is set or the shell as specified in the
575 If a command is specified, it is passed to the shell for execution
579 If no command is specified, an interactive shell is executed.
582 .Fl t ( Em type Ns No )
583 option causes the new (SELinux) security context to have the type
586 If no type is specified, the default type is derived from the
590 .Fl U ( Em other user Ns No )
591 option is used in conjunction with the
593 option to specify the user whose privileges should be listed.
594 The security policy may restrict listing other users' privileges.
597 policy only allows root or a user with the
599 privilege on the current host to use this option.
602 .Fl u ( Em user Ns No )
605 to run the specified command as a user other than
612 When running commands as a
614 many shells require that the
616 be escaped with a backslash
618 Security policies may restrict
620 to those listed in the password database.
625 that are not in the password database as long as the
628 Other security policies may not support this.
631 .Fl V ( Em version Ns No )
634 to print its version string and the version string of the security
635 policy plugin and any I/O plugins.
636 If the invoking user is already root the
638 option will display the arguments passed to configure when
640 was built and plugins may display more verbose information such as
644 .Fl v ( Em validate Ns No )
647 will update the user's cached credentials, authenticating the user's
648 password if necessary.
651 plugin, this extends the
655 minutes (or whatever the timeout is set to by the security policy)
656 but does not run a command.
657 Not all security policies support cached credentials.
661 option indicates that
663 should stop processing command line arguments.
666 Environment variables to be set for the command may also be passed
667 on the command line in the form of
668 .Sy VAR Ns No = Ns Em value ,
670 .Sy LD_LIBRARY_PATH Ns No = Ns Em /usr/local/pkg/lib .
671 Variables passed on the command line are subject to the same
672 restrictions as normal environment variables with one important
678 the command to be run has the
680 tag set or the command matched is
682 the user may set variables that would otherwise be forbidden.
684 .Xr sudoers @mansectform@
685 for more information.
686 .Sh COMMAND EXECUTION
689 executes a command, the security policy specifies the execution
690 envionment for the command.
691 Typically, the real and effective uid and gid are set to
692 match those of the target user, as specified in the password database,
693 and the group vector is initialized based on the group database
696 option was specified).
698 The following parameters may be specified by security policy:
701 real and effective user ID
703 real and effective group ID
705 supplementary group IDs
709 current working directory
711 file creation mode mask (umask)
713 SELinux role and type
721 scheduling priority (aka nice value)
726 runs a command, it calls
728 sets up the execution environment as described above, and calls the
730 system call in the child process.
733 process waits until the command has completed, then passes the
734 command's exit status to the security policy's close method and exits.
735 If an I/O logging plugin is configured, a new pseudo-terminal
737 is created and a second
739 process is used to relay job control signals between the user's
740 existing pty and the new pty the command is being run in.
741 This extra process makes it possible to, for example, suspend
742 and resume the command.
743 Without it, the command would be in what POSIX terms an
744 .Dq orphaned process group
745 and it would not receive any job control signals.
747 Because the command is run as a child of the
751 will relay signals it receives to the command.
752 Unless the command is being run in a new pty, the
757 signals are not relayed unless they are sent by a user process,
759 Otherwise, the command would receive
761 twice every time the user entered control-C.
762 Some signals, such as
766 cannot be caught and thus will not be relayed to the command.
769 should be used instead of
771 when you wish to suspend a command being run by
776 will not relay signals that were sent by the command it is running.
777 This prevents the command from accidentally killing itself.
779 .Xr reboot @mansectsu@
782 to all non-system processes other than itself before rebooting
788 signal it received back to
789 .Xr reboot @mansectsu@ ,
790 which might then exit before the system was actually rebooted,
791 leaving it in a half-dead state similar to single user mode.
792 Note, however, that this check only applies to the command run by
794 and not any other processes that the command may create.
795 As a result, running a script that calls
796 .Xr reboot @mansectsu@
798 .Xr shutdown @mansectsu@
801 may cause the system to end up in this undefined state unless the
802 .Xr reboot @mansectsu@
804 .Xr shutdown @mansectsu@
807 family of functions instead of
809 (which interposes a shell between the command and the calling process).
811 Plugins are dynamically loaded based on the contents of the
812 .Pa @sysconfdir@/sudo.conf
815 .Pa @sysconfdir@/sudo.conf
816 file is present, or it contains no
820 will use the traditional
822 security policy and I/O logging, which corresponds to the following
823 .Pa @sysconfdir@/sudo.conf
827 # Default @sysconfdir@/sudo.conf file
830 # Plugin plugin_name plugin_path plugin_options ...
831 # Path askpass /path/to/askpass
832 # Path noexec /path/to/sudo_noexec.so
833 # Debug sudo /var/log/sudo_debug all@warn
834 # Set disable_coredump true
836 # The plugin_path is relative to @prefix@/libexec unless
838 # The plugin_name corresponds to a global symbol in the plugin
839 # that contains the plugin interface structure.
840 # The plugin_options are optional.
842 Plugin policy_plugin sudoers.so
843 Plugin io_plugin sudoers.so
850 keyword, followed by the
854 to the shared object containing the plugin.
858 .Li struct policy_plugin
861 in the plugin shared object.
864 may be fully qualified or relative.
865 If not fully qualified it is relative to the
868 Any additional parameters after the
870 are passed as arguments to the plugin's
873 Lines that don't begin with
879 are silently ignored.
881 For more information, see the
882 .Xr sudo_plugin @mansectsu@
889 keyword, followed by the name of the path to set and its value.
891 .Bd -literal -offset indent
892 Path noexec @noexec_file@
893 Path askpass /usr/X11R6/bin/ssh-askpass
896 The following plugin-agnostic paths may be set in the
897 .Pa @sysconfdir@/sudo.conf
901 The fully qualified path to a helper program used to read the user's
902 password when no terminal is available.
903 This may be the case when
905 is executed from a graphical (as opposed to text-based) application.
906 The program specified by
908 should display the argument passed to it as the prompt and write
909 the user's password to the standard output.
912 may be overridden by the
914 environment variable.
916 The fully-qualified path to a shared library containing dummy
922 library functions that just return an error.
923 This is used to implement the
925 functionality on systems that support
933 versions 1.8.4 and higher support a flexible debugging framework
934 that can help track down what
936 is doing internally if there is a problem.
942 keyword, followed by the name of the program to debug
943 .Pq Nm sudo , Nm visudo , Nm sudoreplay ,
944 the debug file name and a comma-separated list of debug flags.
945 The debug flag syntax used by
950 .Em subsystem Ns No @ Ns Em priority
951 but the plugin is free to use a different format so long as it does
956 .Bd -literal -offset indent
957 Debug sudo /var/log/sudo_debug all@warn,plugin@info
960 would log all debugging statements at the
962 level and higher in addition to those at the
964 level for the plugin subsystem.
968 entry per program is supported.
972 entry is shared by the
977 A future release may add support for per-plugin
979 lines and/or support for multiple debugging files for a single
982 The priorities used by the
984 front end, in order of decreasing severity, are:
985 .Em crit , err , warn , notice , diag , info , trace
988 Each priority, when specified, also includes all priorities higher
990 For example, a priority of
992 would include debug messages logged at
996 The following subsystems are used by the
1001 matches every subsystem
1003 command line argument processing
1014 network interface handling
1016 communication with the plugin
1018 plugin configuration
1020 pseudo-tty related code
1022 SELinux-specific handling
1029 Upon successful execution of a program, the exit status from
1031 will simply be the exit status of the program that was executed.
1035 exits with a value of 1 if there is a configuration/permission
1038 cannot execute the given command.
1039 In the latter case the error string is printed to the standard error.
1044 one or more entries in the user's
1046 an error is printed on stderr.
1047 (If the directory does not exist or if it is not really a directory,
1048 the entry is ignored and no error is printed.)
1049 This should not happen under normal circumstances.
1050 The most common reason for
1053 .Dq permission denied
1054 is if you are running an automounter and one of the directories in
1057 is on a machine that is currently unreachable.
1060 tries to be safe when executing external commands.
1062 To prevent command spoofing,
1064 checks "." and "" (both denoting current directory) last when
1065 searching for a command in the user's
1067 (if one or both are in the
1069 Note, however, that the actual
1071 environment variable is
1073 modified and is passed unchanged to the program that
1079 will normally only log the command it explicitly runs.
1080 If a user runs a command such as
1084 subsequent commands run from that shell are not subject to
1087 The same is true for commands that offer shell escapes (including
1089 If I/O logging is enabled, subsequent commands will have their input and/or
1090 output logged, but there will not be traditional logs for those commands.
1091 Because of this, care must be taken when giving users access to commands via
1093 to verify that the command does not inadvertently give the user an
1094 effective root shell.
1095 For more information, please see the
1096 .Em PREVENTING SHELL ESCAPES
1098 .Xr sudoers @mansectform@ .
1100 To prevent the disclosure of potentially sensitive information,
1102 disables core dumps by default while it is executing (they are
1103 re-enabled for the command that is run).
1106 crashes, you may wish to re-enable core dumps by setting
1107 .Dq disable_coredump
1109 .Pa @sysconfdir@/sudo.conf
1111 .Bd -literal -offset indent
1112 Set disable_coredump false
1115 Note that by default, most operating systems disable core dumps
1116 from setuid programs, which includes
1120 core file you may need to enable core dumps for setuid processes.
1121 On BSD and Linux systems this is accomplished via the sysctl command,
1122 on Solaris the coreadm command can be used.
1125 utilizes the following environment variables.
1126 The security policy has control over the actual content of the command's
1130 Default editor to use in
1132 (sudoedit) mode if neither
1144 set to the mail spool of the target user.
1146 Set to the home directory of the target user if
1158 option is specified and
1163 May be overridden by the security policy.
1165 Used to determine shell to run with
1169 Specifies the path to a helper program used to read the password
1170 if no terminal is available or if the
1172 option is specified.
1174 Set to the command run by sudo.
1176 Default editor to use in
1180 Set to the group ID of the user who invoked sudo.
1182 Used as the default password prompt.
1186 will be set to its value for the program being run.
1188 Set to the user ID of the user who invoked sudo.
1190 Set to the login name of the user who invoked sudo.
1192 Set to the target user (root unless the
1194 option is specified).
1196 Default editor to use in
1204 .It Pa @sysconfdir@/sudo.conf
1206 front end configuration
1209 Note: the following examples assume a properly configured security
1212 To get a file listing of an unreadable directory:
1213 .Bd -literal -offset indent
1214 $ sudo ls /usr/local/protected
1217 To list the home directory of user yaz on a machine where the file
1218 system holding ~yaz is not exported as root:
1219 .Bd -literal -offset indent
1220 $ sudo -u yaz ls ~yaz
1226 .Bd -literal -offset indent
1227 $ sudo -u www vi ~www/htdocs/index.html
1230 To view system logs only accessible to root and users in the adm
1232 .Bd -literal -offset indent
1233 $ sudo -g adm view /var/log/syslog
1236 To run an editor as jim with a different primary group:
1237 .Bd -literal -offset indent
1238 $ sudo -u jim -g audio vi ~jim/sound.txt
1241 To shut down a machine:
1242 .Bd -literal -offset indent
1243 $ sudo shutdown -r +15 "quick reboot"
1246 To make a usage listing of the directories in the /home partition.
1247 Note that this runs the commands in a sub-shell to make the
1249 and file redirection work.
1250 .Bd -literal -offset indent
1251 $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
1258 .Xr passwd @mansectform@ ,
1259 .Xr sudoers @mansectform@ ,
1260 .Xr sudo_plugin @mansectsu@ ,
1261 .Xr sudoreplay @mansectsu@ ,
1262 .Xr visudo @mansectsu@
1264 See the HISTORY file in the
1266 distribution (http://www.sudo.ws/sudo/history.html) for a brief
1269 Many people have worked on
1271 over the years; this version consists of code written primarily by:
1272 .Bd -ragged -offset indent
1276 See the CONTRIBUTORS file in the
1278 distribution (http://www.sudo.ws/sudo/contributors.html) for an
1279 exhaustive list of people who have contributed to
1282 There is no easy way to prevent a user from gaining a root shell
1283 if that user is allowed to run arbitrary commands via
1285 Also, many programs (such as editors) allow the user to run commands
1286 via shell escapes, thus avoiding
1289 However, on most systems it is possible to prevent shell escapes with the
1290 .Xr sudoers @mansectform@
1295 It is not meaningful to run the
1297 command directly via sudo, e.g.,
1298 .Bd -literal -offset indent
1299 $ sudo cd /usr/local/protected
1302 since when the command exits the parent process (your shell) will
1306 section for more information.
1308 Running shell scripts via
1310 can expose the same kernel bugs that make setuid shell scripts
1311 unsafe on some operating systems (if your OS has a /dev/fd/ directory,
1312 setuid shell scripts are generally safe).
1314 If you feel you have found a bug in
1316 please submit a bug report at http://www.sudo.ws/sudo/bugs/
1318 Limited free support is available via the sudo-users mailing list,
1319 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1320 search the archives.
1325 and any express or implied warranties, including, but not limited
1326 to, the implied warranties of merchantability and fitness for a
1327 particular purpose are disclaimed.
1328 See the LICENSE file distributed with
1330 or http://www.sudo.ws/sudo/license.html for complete details.
projects / debian / sudo / blob