2 .\" Copyright (c) 1994-1996, 1998-2005, 2007-2013
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 .Xr sudo.conf @mansectform@
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 environment 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 function and exits.
735 If an I/O logging plugin is configured or if the security policy
736 explicitly requests it, a new pseudo-terminal
738 is created and a second
740 process is used to relay job control signals between the user's
741 existing pty and the new pty the command is being run in.
742 This extra process makes it possible to, for example, suspend
743 and resume the command.
744 Without it, the command would be in what POSIX terms an
745 .Dq orphaned process group
746 and it would not receive any job control signals.
747 As a special case, if the policy plugin does not define a close
748 function and no pty is required,
750 will execute the command directly instead of calling
754 Because the command is run as a child of the
758 will relay signals it receives to the command.
759 Unless the command is being run in a new pty, the
764 signals are not relayed unless they are sent by a user process,
766 Otherwise, the command would receive
768 twice every time the user entered control-C.
769 Some signals, such as
773 cannot be caught and thus will not be relayed to the command.
776 should be used instead of
778 when you wish to suspend a command being run by
783 will not relay signals that were sent by the command it is running.
784 This prevents the command from accidentally killing itself.
786 .Xr reboot @mansectsu@
789 to all non-system processes other than itself before rebooting
795 signal it received back to
796 .Xr reboot @mansectsu@ ,
797 which might then exit before the system was actually rebooted,
798 leaving it in a half-dead state similar to single user mode.
799 Note, however, that this check only applies to the command run by
801 and not any other processes that the command may create.
802 As a result, running a script that calls
803 .Xr reboot @mansectsu@
805 .Xr shutdown @mansectsu@
808 may cause the system to end up in this undefined state unless the
809 .Xr reboot @mansectsu@
811 .Xr shutdown @mansectsu@
814 family of functions instead of
816 (which interposes a shell between the command and the calling process).
818 If no I/O logging plugins are loaded and the policy plugin has not
821 function, set a command timeout or required that the command be
824 may execute the command directly instead of running it as a child process.
826 Plugins are dynamically loaded based on the contents of the
827 .Xr sudo.conf @mansectform@
830 .Xr sudo.conf @mansectform@
831 file is present, or it contains no
835 will use the traditional
837 security policy and I/O logging.
839 .Xr sudo.conf @mansectform@
840 manual for details of the
841 .Pa @sysconfdir@/sudo.conf
843 .Xr sudo_plugin @mansectsu@
844 manual for more information about the
848 Upon successful execution of a program, the exit status from
850 will simply be the exit status of the program that was executed.
854 exits with a value of 1 if there is a configuration/permission
857 cannot execute the given command.
858 In the latter case the error string is printed to the standard error.
863 one or more entries in the user's
865 an error is printed on stderr.
866 (If the directory does not exist or if it is not really a directory,
867 the entry is ignored and no error is printed.)
868 This should not happen under normal circumstances.
869 The most common reason for
872 .Dq permission denied
873 is if you are running an automounter and one of the directories in
876 is on a machine that is currently unreachable.
879 tries to be safe when executing external commands.
881 To prevent command spoofing,
883 checks "." and "" (both denoting current directory) last when
884 searching for a command in the user's
886 (if one or both are in the
888 Note, however, that the actual
890 environment variable is
892 modified and is passed unchanged to the program that
898 will normally only log the command it explicitly runs.
899 If a user runs a command such as
903 subsequent commands run from that shell are not subject to
906 The same is true for commands that offer shell escapes (including
908 If I/O logging is enabled, subsequent commands will have their input and/or
909 output logged, but there will not be traditional logs for those commands.
910 Because of this, care must be taken when giving users access to commands via
912 to verify that the command does not inadvertently give the user an
913 effective root shell.
914 For more information, please see the
915 .Em PREVENTING SHELL ESCAPES
917 .Xr sudoers @mansectform@ .
919 To prevent the disclosure of potentially sensitive information,
921 disables core dumps by default while it is executing (they are
922 re-enabled for the command that is run).
925 crashes, you may wish to re-enable core dumps by setting
928 .Xr sudo.conf @mansectform@
930 .Bd -literal -offset indent
931 Set disable_coredump false
935 .Xr sudo.conf @mansectform@
936 manual for more information.
939 utilizes the following environment variables.
940 The security policy has control over the actual content of the command's
944 Default editor to use in
946 (sudoedit) mode if neither
958 set to the mail spool of the target user.
960 Set to the home directory of the target user if
972 option is specified and
977 May be overridden by the security policy.
979 Used to determine shell to run with
983 Specifies the path to a helper program used to read the password
984 if no terminal is available or if the
988 Set to the command run by sudo.
990 Default editor to use in
994 Set to the group ID of the user who invoked sudo.
996 Used as the default password prompt.
1000 will be set to its value for the program being run.
1002 Set to the user ID of the user who invoked sudo.
1004 Set to the login name of the user who invoked sudo.
1006 Set to the target user (root unless the
1008 option is specified).
1010 Default editor to use in
1018 .It Pa @sysconfdir@/sudo.conf
1020 front end configuration
1023 Note: the following examples assume a properly configured security
1026 To get a file listing of an unreadable directory:
1027 .Bd -literal -offset indent
1028 $ sudo ls /usr/local/protected
1031 To list the home directory of user yaz on a machine where the file
1032 system holding ~yaz is not exported as root:
1033 .Bd -literal -offset indent
1034 $ sudo -u yaz ls ~yaz
1040 .Bd -literal -offset indent
1041 $ sudo -u www vi ~www/htdocs/index.html
1044 To view system logs only accessible to root and users in the adm
1046 .Bd -literal -offset indent
1047 $ sudo -g adm view /var/log/syslog
1050 To run an editor as jim with a different primary group:
1051 .Bd -literal -offset indent
1052 $ sudo -u jim -g audio vi ~jim/sound.txt
1055 To shut down a machine:
1056 .Bd -literal -offset indent
1057 $ sudo shutdown -r +15 "quick reboot"
1060 To make a usage listing of the directories in the /home partition.
1061 Note that this runs the commands in a sub-shell to make the
1063 and file redirection work.
1064 .Bd -literal -offset indent
1065 $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
1071 .Xr passwd @mansectform@ ,
1072 .Xr sudo.conf @mansectform@ ,
1073 .Xr sudoers @mansectform@ ,
1074 .Xr sudo_plugin @mansectsu@ ,
1075 .Xr sudoreplay @mansectsu@ ,
1076 .Xr visudo @mansectsu@
1078 See the HISTORY file in the
1080 distribution (http://www.sudo.ws/sudo/history.html) for a brief
1083 Many people have worked on
1085 over the years; this version consists of code written primarily by:
1086 .Bd -ragged -offset indent
1090 See the CONTRIBUTORS file in the
1092 distribution (http://www.sudo.ws/sudo/contributors.html) for an
1093 exhaustive list of people who have contributed to
1096 There is no easy way to prevent a user from gaining a root shell
1097 if that user is allowed to run arbitrary commands via
1099 Also, many programs (such as editors) allow the user to run commands
1100 via shell escapes, thus avoiding
1103 However, on most systems it is possible to prevent shell escapes with the
1104 .Xr sudoers @mansectform@
1109 It is not meaningful to run the
1111 command directly via sudo, e.g.,
1112 .Bd -literal -offset indent
1113 $ sudo cd /usr/local/protected
1116 since when the command exits the parent process (your shell) will
1120 section for more information.
1122 Running shell scripts via
1124 can expose the same kernel bugs that make setuid shell scripts
1125 unsafe on some operating systems (if your OS has a /dev/fd/ directory,
1126 setuid shell scripts are generally safe).
1128 If you feel you have found a bug in
1130 please submit a bug report at http://www.sudo.ws/sudo/bugs/
1132 Limited free support is available via the sudo-users mailing list,
1133 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1134 search the archives.
1139 and any express or implied warranties, including, but not limited
1140 to, the implied warranties of merchantability and fitness for a
1141 particular purpose are disclaimed.
1142 See the LICENSE file distributed with
1144 or http://www.sudo.ws/sudo/license.html for complete details.
projects / debian / sudo / blob