X-Git-Url: https://git.gag.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fsudo.man.in;fp=doc%2Fsudo.man.in;h=856164e35e1f05927bee086827bf8752782ca42f;hb=6ad45aa23af5f5f3b54468937d6a13089201b891;hp=0000000000000000000000000000000000000000;hpb=97bd3ae46779c69fcdab82d0c64bdf05be009ec3;p=debian%2Fsudo diff --git a/doc/sudo.man.in b/doc/sudo.man.in new file mode 100644 index 0000000..856164e --- /dev/null +++ b/doc/sudo.man.in @@ -0,0 +1,893 @@ +.\" Copyright (c) 1994-1996, 1998-2005, 2007-2012 +.\" Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.nr SL @SEMAN@ +.nr BA @BAMAN@ +.nr LC @LCMAN@ +.nr PT @password_timeout@ +.\" +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` +. ds C' +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SUDO @mansectsu@" +.TH SUDO @mansectsu@ "March 15, 2012" "1.8.5" "MAINTENANCE COMMANDS" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +sudo, sudoedit \- execute a command as another user +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBsudo\fR \fB\-h\fR | \fB\-K\fR | \fB\-k\fR | \fB\-V\fR +.PP +\&\fBsudo\fR \fB\-v\fR [\fB\-AknS\fR] +.if \n(BA [\fB\-a\fR\ \fIauth_type\fR] +[\fB\-g\fR\ \fIgroup\ name\fR|\fI#gid\fR] [\fB\-p\fR\ \fIprompt\fR] +[\fB\-u\fR\ \fIuser\ name\fR|\fI#uid\fR] +.PP +\&\fBsudo\fR \fB\-l[l]\fR [\fB\-AknS\fR] +.if \n(BA [\fB\-a\fR\ \fIauth_type\fR] +[\fB\-g\fR\ \fIgroup\ name\fR|\fI#gid\fR] [\fB\-p\fR\ \fIprompt\fR] +[\fB\-U\fR\ \fIuser\ name\fR] [\fB\-u\fR\ \fIuser\ name\fR|\fI#uid\fR] [\fIcommand\fR] +.PP +\&\fBsudo\fR [\fB\-AbEHnPS\fR] +.if \n(BA [\fB\-a\fR\ \fIauth_type\fR] +[\fB\-C\fR\ \fIfd\fR] +.if \n(LC [\fB\-c\fR\ \fIclass\fR|\fI\-\fR] +[\fB\-g\fR\ \fIgroup\ name\fR|\fI#gid\fR] [\fB\-p\fR\ \fIprompt\fR] +.if \n(SL [\fB\-r\fR\ \fIrole\fR] [\fB\-t\fR\ \fItype\fR] +[\fB\-u\fR\ \fIuser\ name\fR|\fI#uid\fR] +[\fB\s-1VAR\s0\fR=\fIvalue\fR] [\fB\-i\fR\ |\ \fB\-s\fR] [\fIcommand\fR] +.PP +\&\fBsudoedit\fR [\fB\-AnS\fR] +.if \n(BA [\fB\-a\fR\ \fIauth_type\fR] +[\fB\-C\fR\ \fIfd\fR] +.if \n(LC [\fB\-c\fR\ \fIclass\fR|\fI\-\fR] +[\fB\-g\fR\ \fIgroup\ name\fR|\fI#gid\fR] [\fB\-p\fR\ \fIprompt\fR] +[\fB\-u\fR\ \fIuser\ name\fR|\fI#uid\fR] file ... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBsudo\fR allows a permitted user to execute a \fIcommand\fR as the +superuser or another user, as specified by the security policy. +The real and effective uid and gid are set to match those of the +target user, as specified in the password database, and the group +vector is initialized based on the group database (unless the \fB\-P\fR +option was specified). +.PP +\&\fBsudo\fR supports a plugin architecture for security policies and +input/output logging. Third parties can develop and distribute +their own policy and I/O logging modules to work seamlessly with +the \fBsudo\fR front end. The default security policy is \fIsudoers\fR, +which is configured via the file \fI@sysconfdir@/sudoers\fR, or via +\&\s-1LDAP\s0. See the \s-1PLUGINS\s0 section for more information. +.PP +The security policy determines what privileges, if any, a user has +to run \fBsudo\fR. The policy may require that users authenticate +themselves with a password or another authentication mechanism. If +authentication is required, \fBsudo\fR will exit if the user's password +is not entered within a configurable time limit. This limit is +policy-specific; the default password prompt timeout for the +\&\fIsudoers\fR security policy is +.ie \n(PT \f(CW\*(C`@password_timeout@\*(C'\fR minutes. +.el unlimited. +.PP +Security policies may support credential caching to allow the user +to run \fBsudo\fR again for a period of time without requiring +authentication. The \fIsudoers\fR policy caches credentials for +\&\f(CW\*(C`@timeout@\*(C'\fR minutes, unless overridden in \fIsudoers\fR\|(@mansectform@). By +running \fBsudo\fR with the \fB\-v\fR option, a user can update the cached +credentials without running a \fIcommand\fR. +.PP +When invoked as \fBsudoedit\fR, the \fB\-e\fR option (described below), +is implied. +.PP +Security policies may log successful and failed attempts to use +\&\fBsudo\fR. If an I/O plugin is configured, the running command's +input and output may be logged as well. +.SH "OPTIONS" +.IX Header "OPTIONS" +\&\fBsudo\fR accepts the following command line options: +.IP "\-A" 12 +.IX Item "-A" +Normally, if \fBsudo\fR requires a password, it will read it from the +user's terminal. If the \fB\-A\fR (\fIaskpass\fR) option is specified, +a (possibly graphical) helper program is executed to read the user's +password and output the password to the standard output. If the +\&\f(CW\*(C`SUDO_ASKPASS\*(C'\fR environment variable is set, it specifies the path +to the helper program. Otherwise, if \fI@sysconfdir@/sudo.conf\fR +contains a line specifying the askpass program, that value will be +used. For example: +.Sp +.Vb 2 +\& # Path to askpass helper program +\& Path askpass /usr/X11R6/bin/ssh\-askpass +.Ve +.Sp +If no askpass program is available, sudo will exit with an error. +.if \n(BA \{\ +.IP "\-a \fItype\fR" 12 +.IX Item "-a type" +The \fB\-a\fR (\fIauthentication type\fR) option causes \fBsudo\fR to use the +specified authentication type when validating the user, as allowed +by \fI/etc/login.conf\fR. The system administrator may specify a list +of sudo-specific authentication methods by adding an \*(L"auth-sudo\*(R" +entry in \fI/etc/login.conf\fR. This option is only available on systems +that support \s-1BSD\s0 authentication. +\} +.IP "\-b" 12 +.IX Item "-b" +The \fB\-b\fR (\fIbackground\fR) option tells \fBsudo\fR to run the given +command in the background. Note that if you use the \fB\-b\fR +option you cannot use shell job control to manipulate the process. +Most interactive commands will fail to work properly in background +mode. +.IP "\-C \fIfd\fR" 12 +.IX Item "-C fd" +Normally, \fBsudo\fR will close all open file descriptors other than +standard input, standard output and standard error. The \fB\-C\fR +(\fIclose from\fR) option allows the user to specify a starting point +above the standard error (file descriptor three). Values less than +three are not permitted. The security policy may restrict the +user's ability to use the \fB\-C\fR option. The \fIsudoers\fR policy only +permits use of the \fB\-C\fR option when the administrator has enabled +the \fIclosefrom_override\fR option. +.if \n(LC \{\ +.IP "\-c \fIclass\fR" 12 +.IX Item "-c class" +The \fB\-c\fR (\fIclass\fR) option causes \fBsudo\fR to run the specified command +with resources limited by the specified login class. The \fIclass\fR +argument can be either a class name as defined in \fI/etc/login.conf\fR, +or a single '\-' character. Specifying a \fIclass\fR of \f(CW\*(C`\-\*(C'\fR indicates +that the command should be run restricted by the default login +capabilities for the user the command is run as. If the \fIclass\fR +argument specifies an existing user class, the command must be run +as root, or the \fBsudo\fR command must be run from a shell that is already +root. This option is only available on systems with \s-1BSD\s0 login classes. +\} +.IP "\-E" 12 +.IX Item "-E" +The \fB\-E\fR (\fIpreserve\fR \fIenvironment\fR) option indicates to the +security policy that the user wishes to preserve their existing +environment variables. The security policy may return an error if +the \fB\-E\fR option is specified and the user does not have permission +to preserve the environment. +.IP "\-e" 12 +.IX Item "-e" +The \fB\-e\fR (\fIedit\fR) option indicates that, instead of running a +command, the user wishes to edit one or more files. In lieu of a +command, the string \*(L"sudoedit\*(R" is used when consulting the security +policy. If the user is authorized by the policy, the following +steps are taken: +.RS 12 +.IP "1." 4 +Temporary copies are made of the files to be edited with the owner +set to the invoking user. +.IP "2." 4 +The editor specified by the policy is run to edit the temporary files. +The \fIsudoers\fR policy uses the \f(CW\*(C`SUDO_EDITOR\*(C'\fR, \f(CW\*(C`VISUAL\*(C'\fR and \f(CW\*(C`EDITOR\*(C'\fR +environment variables (in that order). If none of \f(CW\*(C`SUDO_EDITOR\*(C'\fR, +\&\f(CW\*(C`VISUAL\*(C'\fR or \f(CW\*(C`EDITOR\*(C'\fR are set, the first program listed in the +\&\fIeditor\fR \fIsudoers\fR\|(@mansectform@) option is used. +.IP "3." 4 +If they have been modified, the temporary files are copied back to +their original location and the temporary versions are removed. +.RE +.RS 12 +.Sp +If the specified file does not exist, it will be created. Note +that unlike most commands run by \fBsudo\fR, the editor is run with +the invoking user's environment unmodified. If, for some reason, +\&\fBsudo\fR is unable to update a file with its edited version, the +user will receive a warning and the edited copy will remain in a +temporary file. +.RE +.IP "\-g \fIgroup\fR" 12 +.IX Item "-g group" +Normally, \fBsudo\fR runs a command with the primary group set to the +one specified by the password database for the user the command is +being run as (by default, root). The \fB\-g\fR (\fIgroup\fR) option causes +\&\fBsudo\fR to run the command with the primary group set to \fIgroup\fR +instead. To specify a \fIgid\fR instead of a \fIgroup name\fR, use +\&\fI#gid\fR. When running commands as a \fIgid\fR, many shells require +that the '#' be escaped with a backslash ('\e'). If no \fB\-u\fR option +is specified, the command will be run as the invoking user (not +root). In either case, the primary group will be set to \fIgroup\fR. +.IP "\-H" 12 +.IX Item "-H" +The \fB\-H\fR (\fI\s-1HOME\s0\fR) option requests that the security policy set +the \f(CW\*(C`HOME\*(C'\fR environment variable to the home directory of the target +user (root by default) as specified by the password database. +Depending on the policy, this may be the default behavior. +.IP "\-h" 12 +.IX Item "-h" +The \fB\-h\fR (\fIhelp\fR) option causes \fBsudo\fR to print a short help message +to the standard output and exit. +.IP "\-i [command]" 12 +.IX Item "-i [command]" +The \fB\-i\fR (\fIsimulate initial login\fR) option runs the shell specified +by the password database entry of the target user as a login shell. +This means that login-specific resource files such as \f(CW\*(C`.profile\*(C'\fR +or \f(CW\*(C`.login\*(C'\fR will be read by the shell. If a command is specified, +it is passed to the shell for execution via the shell's \fB\-c\fR option. +If no command is specified, an interactive shell is executed. +\&\fBsudo\fR attempts to change to that user's home directory before +running the shell. The security policy shall initialize the +environment to a minimal set of variables, similar to what is present +when a user logs in. The \fICommand Environment\fR section in the +\&\fIsudoers\fR\|(@mansectform@) manual documents how the \fB\-i\fR option affects the +environment in which a command is run when the \fIsudoers\fR policy +is in use. +.IP "\-K" 12 +.IX Item "-K" +The \fB\-K\fR (sure \fIkill\fR) option is like \fB\-k\fR except that it removes +the user's cached credentials entirely and may not be used in +conjunction with a command or other option. This option does not +require a password. Not all security policies support credential +caching. +.IP "\-k [command]" 12 +.IX Item "-k [command]" +When used alone, the \fB\-k\fR (\fIkill\fR) option to \fBsudo\fR invalidates +the user's cached credentials. The next time \fBsudo\fR is run a +password will be required. This option does not require a password +and was added to allow a user to revoke \fBsudo\fR permissions from a +\&.logout file. Not all security policies support credential +caching. +.Sp +When used in conjunction with a command or an option that may require +a password, the \fB\-k\fR option will cause \fBsudo\fR to ignore the user's +cached credentials. As a result, \fBsudo\fR will prompt for a password +(if one is required by the security policy) and will not update the +user's cached credentials. +.IP "\-l[l] [\fIcommand\fR]" 12 +.IX Item "-l[l] [command]" +If no \fIcommand\fR is specified, the \fB\-l\fR (\fIlist\fR) option will list +the allowed (and forbidden) commands for the invoking user (or the +user specified by the \fB\-U\fR option) on the current host. If a +\&\fIcommand\fR is specified and is permitted by the security policy, +the fully-qualified path to the command is displayed along with any +command line arguments. If \fIcommand\fR is specified but not allowed, +\&\fBsudo\fR will exit with a status value of 1. If the \fB\-l\fR option +is specified with an \fBl\fR argument (i.e. \fB\-ll\fR), or if \fB\-l\fR is +specified multiple times, a longer list format is used. +.IP "\-n" 12 +.IX Item "-n" +The \fB\-n\fR (\fInon-interactive\fR) option prevents \fBsudo\fR from prompting +the user for a password. If a password is required for the command +to run, \fBsudo\fR will display an error messages and exit. +.IP "\-P" 12 +.IX Item "-P" +The \fB\-P\fR (\fIpreserve\fR \fIgroup vector\fR) option causes \fBsudo\fR to +preserve the invoking user's group vector unaltered. By default, +the \fIsudoers\fR policy will initialize the group vector to the list +of groups the target user is in. The real and effective group IDs, +however, are still set to match the target user. +.IP "\-p \fIprompt\fR" 12 +.IX Item "-p prompt" +The \fB\-p\fR (\fIprompt\fR) option allows you to override the default +password prompt and use a custom one. The following percent (`\f(CW\*(C`%\*(C'\fR') +escapes are supported by the \fIsudoers\fR policy: +.RS 12 +.ie n .IP "%H" 4 +.el .IP "\f(CW%H\fR" 4 +.IX Item "%H" +expanded to the host name including the domain name (on if +the machine's host name is fully qualified or the \fIfqdn\fR option +is set in \fIsudoers\fR\|(@mansectform@)) +.ie n .IP "%h" 4 +.el .IP "\f(CW%h\fR" 4 +.IX Item "%h" +expanded to the local host name without the domain name +.ie n .IP "%p" 4 +.el .IP "\f(CW%p\fR" 4 +.IX Item "%p" +expanded to the name of the user whose password is being requested +(respects the \fIrootpw\fR, \fItargetpw\fR and \fIrunaspw\fR flags in +\&\fIsudoers\fR\|(@mansectform@)) +.ie n .IP "%U" 4 +.el .IP "\f(CW%U\fR" 4 +.IX Item "%U" +expanded to the login name of the user the command will be run as +(defaults to root unless the \f(CW\*(C`\-u\*(C'\fR option is also specified) +.ie n .IP "%u" 4 +.el .IP "\f(CW%u\fR" 4 +.IX Item "%u" +expanded to the invoking user's login name +.ie n .IP "\*(C`%%\*(C'" 4 +.el .IP "\f(CW\*(C`%%\*(C'\fR" 4 +.IX Item "%%" +two consecutive \f(CW\*(C`%\*(C'\fR characters are collapsed into a single \f(CW\*(C`%\*(C'\fR character +.RE +.RS 12 +.Sp +The prompt specified by the \fB\-p\fR option will override the system +password prompt on systems that support \s-1PAM\s0 unless the +\&\fIpassprompt_override\fR flag is disabled in \fIsudoers\fR. +.RE +.if \n(SL \{\ +.IP "\-r \fIrole\fR" 12 +.IX Item "-r role" +The \fB\-r\fR (\fIrole\fR) option causes the new (SELinux) security context to +have the role specified by \fIrole\fR. +\} +.IP "\-S" 12 +.IX Item "-S" +The \fB\-S\fR (\fIstdin\fR) option causes \fBsudo\fR to read the password from +the standard input instead of the terminal device. The password must +be followed by a newline character. +.IP "\-s [command]" 12 +.IX Item "-s [command]" +The \fB\-s\fR (\fIshell\fR) option runs the shell specified by the \fI\s-1SHELL\s0\fR +environment variable if it is set or the shell as specified in the +password database. If a command is specified, it is passed to the +shell for execution via the shell's \fB\-c\fR option. If no command +is specified, an interactive shell is executed. +.if \n(SL \{\ +.IP "\-t \fItype\fR" 12 +.IX Item "-t type" +The \fB\-t\fR (\fItype\fR) option causes the new (SELinux) security context to +have the type specified by \fItype\fR. If no type is specified, the default +type is derived from the specified role. +\} +.IP "\-U \fIuser\fR" 12 +.IX Item "-U user" +The \fB\-U\fR (\fIother user\fR) option is used in conjunction with the +\&\fB\-l\fR option to specify the user whose privileges should be listed. +The security policy may restrict listing other users' privileges. +The \fIsudoers\fR policy only allows root or a user with the \f(CW\*(C`ALL\*(C'\fR +privilege on the current host to use this option. +.IP "\-u \fIuser\fR" 12 +.IX Item "-u user" +The \fB\-u\fR (\fIuser\fR) option causes \fBsudo\fR to run the specified +command as a user other than \fIroot\fR. To specify a \fIuid\fR instead +of a \fIuser name\fR, use \fI#uid\fR. When running commands as a \fIuid\fR, +many shells require that the '#' be escaped with a backslash ('\e'). +Security policies may restrict \fIuid\fRs to those listed in the +password database. The \fIsudoers\fR policy allows \fIuid\fRs that are +not in the password database as long as the \fItargetpw\fR option is +not set. Other security policies may not support this. +.IP "\-V" 12 +.IX Item "-V" +The \fB\-V\fR (\fIversion\fR) option causes \fBsudo\fR to print its version +string and the version string of the security policy plugin and any +I/O plugins. If the invoking user is already root the \fB\-V\fR option +will display the arguments passed to configure when \fIsudo\fR was +built and plugins may display more verbose information such as +default options. +.IP "\-v" 12 +.IX Item "-v" +When given the \fB\-v\fR (\fIvalidate\fR) option, \fBsudo\fR will update the +user's cached credentials, authenticating the user's password if +necessary. For the \fIsudoers\fR plugin, this extends the \fBsudo\fR +timeout for another \f(CW\*(C`@timeout@\*(C'\fR minutes (or whatever the timeout +is set to in \fIsudoers\fR) but does not run a command. Not all +security policies support cached credentials. +.IP "\-\-" 12 +The \fB\-\-\fR option indicates that \fBsudo\fR should stop processing command +line arguments. +.PP +Environment variables to be set for the command may also be passed +on the command line in the form of \fB\s-1VAR\s0\fR=\fIvalue\fR, e.g. +\&\fB\s-1LD_LIBRARY_PATH\s0\fR=\fI/usr/local/pkg/lib\fR. Variables passed on the +command line are subject to the same restrictions as normal environment +variables with one important exception. If the \fIsetenv\fR option +is set in \fIsudoers\fR, the command to be run has the \f(CW\*(C`SETENV\*(C'\fR tag +set or the command matched is \f(CW\*(C`ALL\*(C'\fR, the user may set variables +that would otherwise be forbidden. See \fIsudoers\fR\|(@mansectform@) for more information. +.SH "PLUGINS" +.IX Header "PLUGINS" +Plugins are dynamically loaded based on the contents of the +\&\fI@sysconfdir@/sudo.conf\fR file. If no \fI@sysconfdir@/sudo.conf\fR +file is present, or it contains no \f(CW\*(C`Plugin\*(C'\fR lines, \fBsudo\fR +will use the traditional \fIsudoers\fR security policy and I/O logging, +which corresponds to the following \fI@sysconfdir@/sudo.conf\fR file. +.PP +.Vb 10 +\& # +\& # Default @sysconfdir@/sudo.conf file +\& # +\& # Format: +\& # Plugin plugin_name plugin_path plugin_options ... +\& # Path askpass /path/to/askpass +\& # Path noexec /path/to/sudo_noexec.so +\& # Debug sudo /var/log/sudo_debug all@warn +\& # Set disable_coredump true +\& # +\& # The plugin_path is relative to @prefix@/libexec unless +\& # fully qualified. +\& # The plugin_name corresponds to a global symbol in the plugin +\& # that contains the plugin interface structure. +\& # The plugin_options are optional. +\& # +\& Plugin policy_plugin sudoers.so +\& Plugin io_plugin sudoers.so +.Ve +.PP +A \f(CW\*(C`Plugin\*(C'\fR line consists of the \f(CW\*(C`Plugin\*(C'\fR keyword, followed by the +\&\fIsymbol_name\fR and the \fIpath\fR to the shared object containing the +plugin. The \fIsymbol_name\fR is the name of the \f(CW\*(C`struct policy_plugin\*(C'\fR +or \f(CW\*(C`struct io_plugin\*(C'\fR in the plugin shared object. The \fIpath\fR +may be fully qualified or relative. If not fully qualified it is +relative to the \fI@prefix@/libexec\fR directory. Any additional +parameters after the \fIpath\fR are passed as arguments to the plugin's +\&\fIopen\fR function. Lines that don't begin with \f(CW\*(C`Plugin\*(C'\fR, \f(CW\*(C`Path\*(C'\fR, +\&\f(CW\*(C`Debug\*(C'\fR or \f(CW\*(C`Set\*(C'\fR are silently ignored. +.PP +For more information, see the \fIsudo_plugin\fR\|(@mansectsu@) manual. +.SH "PATHS" +.IX Header "PATHS" +A \f(CW\*(C`Path\*(C'\fR line consists of the \f(CW\*(C`Path\*(C'\fR keyword, followed by the +name of the path to set and its value. E.g. +.PP +.Vb 2 +\& Path noexec @noexec_file@ +\& Path askpass /usr/X11R6/bin/ssh\-askpass +.Ve +.PP +The following plugin-agnostic paths may be set in the +\&\fI@sysconfdir@/sudo.conf\fR file. +.IP "askpass" 16 +.IX Item "askpass" +The fully qualified path to a helper program used to read the user's +password when no terminal is available. This may be the case when +\&\fBsudo\fR is executed from a graphical (as opposed to text-based) +application. The program specified by \fIaskpass\fR should display +the argument passed to it as the prompt and write the user's password +to the standard output. The value of \fIaskpass\fR may be overridden +by the \f(CW\*(C`SUDO_ASKPASS\*(C'\fR environment variable. +.IP "noexec" 16 +.IX Item "noexec" +The fully-qualified path to a shared library containing dummy +versions of the \fIexecv()\fR, \fIexecve()\fR and \fIfexecve()\fR library functions +that just return an error. This is used to implement the \fInoexec\fR +functionality on systems that support \f(CW\*(C`LD_PRELOAD\*(C'\fR or its equivalent. +Defaults to \fI@noexec_file@\fR. +.SH "DEBUG FLAGS" +.IX Header "DEBUG FLAGS" +\&\fBsudo\fR versions 1.8.4 and higher support a flexible debugging +framework that can help track down what \fBsudo\fR is doing internally +if there is a problem. +.PP +A \f(CW\*(C`Debug\*(C'\fR line consists of the \f(CW\*(C`Debug\*(C'\fR keyword, followed by the +name of the program to debug (\fBsudo\fR, \fBvisudo\fR, \fBsudoreplay\fR), +the debug file name and a comma-separated list of debug flags. +The debug flag syntax used by \fBsudo\fR and the \fIsudoers\fR plugin is +\&\fIsubsystem\fR@\fIpriority\fR but the plugin is free to use a different +format so long as it does not include a command \f(CW\*(C`,\*(C'\fR. +.PP +For instance: +.PP +.Vb 1 +\& Debug sudo /var/log/sudo_debug all@warn,plugin@info +.Ve +.PP +would log all debugging statements at the \fIwarn\fR level and higher +in addition to those at the \fIinfo\fR level for the plugin subsystem. +.PP +Currently, only one \f(CW\*(C`Debug\*(C'\fR entry per program is supported. The +\&\f(CW\*(C`sudo\*(C'\fR \f(CW\*(C`Debug\*(C'\fR entry is shared by the \fBsudo\fR front end, \fBsudoedit\fR +and the plugins. A future release may add support for per-plugin +\&\f(CW\*(C`Debug\*(C'\fR lines and/or support for multiple debugging files for a +single program. +.PP +The priorities used by the \fBsudo\fR front end, in order of decreasing +severity, are: \fIcrit\fR, \fIerr\fR, \fIwarn\fR, \fInotice\fR, \fIdiag\fR, \fIinfo\fR, +\&\fItrace\fR and \fIdebug\fR. Each priority, when specified, also includes +all priorities higher than it. For example, a priority of \fInotice\fR +would include debug messages logged at \fInotice\fR and higher. +.PP +The following subsystems are used by \fBsudo\fR: +.IP "\fIall\fR" 10 +.IX Item "all" +matches every subsystem +.IP "\fIargs\fR" 10 +.IX Item "args" +command line argument processing +.IP "\fIconv\fR" 10 +.IX Item "conv" +user conversation +.IP "\fIedit\fR" 10 +.IX Item "edit" +sudoedit +.IP "\fIexec\fR" 10 +.IX Item "exec" +command execution +.IP "\fImain\fR" 10 +.IX Item "main" +\&\fBsudo\fR main function +.IP "\fInetif\fR" 10 +.IX Item "netif" +network interface handling +.IP "\fIpcomm\fR" 10 +.IX Item "pcomm" +communication with the plugin +.IP "\fIplugin\fR" 10 +.IX Item "plugin" +plugin configuration +.IP "\fIpty\fR" 10 +.IX Item "pty" +pseudo-tty related code +.IP "\fIselinux\fR" 10 +.IX Item "selinux" +SELinux-specific handling +.IP "\fIutil\fR" 10 +.IX Item "util" +utility functions +.IP "\fIutmp\fR" 10 +.IX Item "utmp" +utmp handling +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Upon successful execution of a program, the exit status from \fBsudo\fR +will simply be the exit status of the program that was executed. +.PP +Otherwise, \fBsudo\fR exits with a value of 1 if there is a +configuration/permission problem or if \fBsudo\fR cannot execute the +given command. In the latter case the error string is printed to +the standard error. If \fBsudo\fR cannot \fIstat\fR\|(2) one or more entries +in the user's \f(CW\*(C`PATH\*(C'\fR, an error is printed on stderr. (If the +directory does not exist or if it is not really a directory, the +entry is ignored and no error is printed.) This should not happen +under normal circumstances. The most common reason for \fIstat\fR\|(2) +to return \*(L"permission denied\*(R" is if you are running an automounter +and one of the directories in your \f(CW\*(C`PATH\*(C'\fR is on a machine that is +currently unreachable. +.SH "SECURITY NOTES" +.IX Header "SECURITY NOTES" +\&\fBsudo\fR tries to be safe when executing external commands. +.PP +To prevent command spoofing, \fBsudo\fR checks \*(L".\*(R" and "" (both denoting +current directory) last when searching for a command in the user's +\&\s-1PATH\s0 (if one or both are in the \s-1PATH\s0). Note, however, that the +actual \f(CW\*(C`PATH\*(C'\fR environment variable is \fInot\fR modified and is passed +unchanged to the program that \fBsudo\fR executes. +.PP +Please note that \fBsudo\fR will normally only log the command it +explicitly runs. If a user runs a command such as \f(CW\*(C`sudo su\*(C'\fR or +\&\f(CW\*(C`sudo sh\*(C'\fR, subsequent commands run from that shell are not subject +to \fBsudo\fR's security policy. The same is true for commands that +offer shell escapes (including most editors). If I/O logging is +enabled, subsequent commands will have their input and/or output +logged, but there will not be traditional logs for those commands. +Because of this, care must be taken when giving users access to +commands via \fBsudo\fR to verify that the command does not inadvertently +give the user an effective root shell. For more information, please +see the \f(CW\*(C`PREVENTING SHELL ESCAPES\*(C'\fR section in \fIsudoers\fR\|(@mansectform@). +.PP +To prevent the disclosure of potentially sensitive information, +\&\fBsudo\fR disables core dumps by default while it is executing (they +are re-enabled for the command that is run). To aid in debugging +\&\fBsudo\fR crashes, you may wish to re-enable core dumps by setting +\&\*(L"disable_coredump\*(R" to false in the \fI@sysconfdir@/sudo.conf\fR file. +.PP +.Vb 1 +\& Set disable_coredump false +.Ve +.PP +Note that by default, most operating systems disable core dumps +from setuid programs, which includes \fBsudo\fR. To actually get a +\&\fBsudo\fR core file you may need to enable core dumps for setuid +processes. On \s-1BSD\s0 and Linux systems this is accomplished via the +sysctl command, on Solaris the coreadm command can be used. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +\&\fBsudo\fR utilizes the following environment variables. The security +policy has control over the content of the command's environment. +.ie n .IP "\*(C`EDITOR\*(C'" 16 +.el .IP "\f(CW\*(C`EDITOR\*(C'\fR" 16 +.IX Item "EDITOR" +Default editor to use in \fB\-e\fR (sudoedit) mode if neither \f(CW\*(C`SUDO_EDITOR\*(C'\fR +nor \f(CW\*(C`VISUAL\*(C'\fR is set +.ie n .IP "\*(C`MAIL\*(C'" 16 +.el .IP "\f(CW\*(C`MAIL\*(C'\fR" 16 +.IX Item "MAIL" +In \fB\-i\fR mode or when \fIenv_reset\fR is enabled in \fIsudoers\fR, set +to the mail spool of the target user +.ie n .IP "\*(C`HOME\*(C'" 16 +.el .IP "\f(CW\*(C`HOME\*(C'\fR" 16 +.IX Item "HOME" +Set to the home directory of the target user if \fB\-i\fR or \fB\-H\fR are +specified, \fIenv_reset\fR or \fIalways_set_home\fR are set in \fIsudoers\fR, +or when the \fB\-s\fR option is specified and \fIset_home\fR is set in +\&\fIsudoers\fR +.ie n .IP "\*(C`PATH\*(C'" 16 +.el .IP "\f(CW\*(C`PATH\*(C'\fR" 16 +.IX Item "PATH" +May be overridden by the security policy. +.ie n .IP "\*(C`SHELL\*(C'" 16 +.el .IP "\f(CW\*(C`SHELL\*(C'\fR" 16 +.IX Item "SHELL" +Used to determine shell to run with \f(CW\*(C`\-s\*(C'\fR option +.ie n .IP "\*(C`SUDO_ASKPASS\*(C'" 16 +.el .IP "\f(CW\*(C`SUDO_ASKPASS\*(C'\fR" 16 +.IX Item "SUDO_ASKPASS" +Specifies the path to a helper program used to read the password +if no terminal is available or if the \f(CW\*(C`\-A\*(C'\fR option is specified. +.ie n .IP "\*(C`SUDO_COMMAND\*(C'" 16 +.el .IP "\f(CW\*(C`SUDO_COMMAND\*(C'\fR" 16 +.IX Item "SUDO_COMMAND" +Set to the command run by sudo +.ie n .IP "\*(C`SUDO_EDITOR\*(C'" 16 +.el .IP "\f(CW\*(C`SUDO_EDITOR\*(C'\fR" 16 +.IX Item "SUDO_EDITOR" +Default editor to use in \fB\-e\fR (sudoedit) mode +.ie n .IP "\*(C`SUDO_GID\*(C'" 16 +.el .IP "\f(CW\*(C`SUDO_GID\*(C'\fR" 16 +.IX Item "SUDO_GID" +Set to the group \s-1ID\s0 of the user who invoked sudo +.ie n .IP "\*(C`SUDO_PROMPT\*(C'" 16 +.el .IP "\f(CW\*(C`SUDO_PROMPT\*(C'\fR" 16 +.IX Item "SUDO_PROMPT" +Used as the default password prompt +.ie n .IP "\*(C`SUDO_PS1\*(C'" 16 +.el .IP "\f(CW\*(C`SUDO_PS1\*(C'\fR" 16 +.IX Item "SUDO_PS1" +If set, \f(CW\*(C`PS1\*(C'\fR will be set to its value for the program being run +.ie n .IP "\*(C`SUDO_UID\*(C'" 16 +.el .IP "\f(CW\*(C`SUDO_UID\*(C'\fR" 16 +.IX Item "SUDO_UID" +Set to the user \s-1ID\s0 of the user who invoked sudo +.ie n .IP "\*(C`SUDO_USER\*(C'" 16 +.el .IP "\f(CW\*(C`SUDO_USER\*(C'\fR" 16 +.IX Item "SUDO_USER" +Set to the login of the user who invoked sudo +.ie n .IP "\*(C`USER\*(C'" 16 +.el .IP "\f(CW\*(C`USER\*(C'\fR" 16 +.IX Item "USER" +Set to the target user (root unless the \fB\-u\fR option is specified) +.ie n .IP "\*(C`VISUAL\*(C'" 16 +.el .IP "\f(CW\*(C`VISUAL\*(C'\fR" 16 +.IX Item "VISUAL" +Default editor to use in \fB\-e\fR (sudoedit) mode if \f(CW\*(C`SUDO_EDITOR\*(C'\fR +is not set +.SH "FILES" +.IX Header "FILES" +.ie n .IP "\fI@sysconfdir@/sudo.conf\fR" 24 +.el .IP "\fI@sysconfdir@/sudo.conf\fR" 24 +.IX Item "@sysconfdir@/sudo.conf" +\&\fBsudo\fR front end configuration +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Note: the following examples assume a properly configured security policy. +.PP +To get a file listing of an unreadable directory: +.PP +.Vb 1 +\& $ sudo ls /usr/local/protected +.Ve +.PP +To list the home directory of user yaz on a machine where the +file system holding ~yaz is not exported as root: +.PP +.Vb 1 +\& $ sudo \-u yaz ls ~yaz +.Ve +.PP +To edit the \fIindex.html\fR file as user www: +.PP +.Vb 1 +\& $ sudo \-u www vi ~www/htdocs/index.html +.Ve +.PP +To view system logs only accessible to root and users in the adm group: +.PP +.Vb 1 +\& $ sudo \-g adm view /var/log/syslog +.Ve +.PP +To run an editor as jim with a different primary group: +.PP +.Vb 1 +\& $ sudo \-u jim \-g audio vi ~jim/sound.txt +.Ve +.PP +To shutdown a machine: +.PP +.Vb 1 +\& $ sudo shutdown \-r +15 "quick reboot" +.Ve +.PP +To make a usage listing of the directories in the /home +partition. Note that this runs the commands in a sub-shell +to make the \f(CW\*(C`cd\*(C'\fR and file redirection work. +.PP +.Vb 1 +\& $ sudo sh \-c "cd /home ; du \-s * | sort \-rn > USAGE" +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgrep\fR\|(1), \fIsu\fR\|(1), \fIstat\fR\|(2), +.if \n(LC \&\fIlogin_cap\fR\|(3), +\&\fIpasswd\fR\|(@mansectform@), \fIsudoers\fR\|(@mansectform@), \fIsudo_plugin\fR\|(@mansectsu@), \fIsudoreplay\fR\|(@mansectsu@), \fIvisudo\fR\|(@mansectsu@) +.SH "AUTHORS" +.IX Header "AUTHORS" +Many people have worked on \fBsudo\fR over the years; this +version consists of code written primarily by: +.PP +.Vb 1 +\& Todd C. Miller +.Ve +.PP +See the \s-1CONTRIBUTORS\s0 file in the \fBsudo\fR distribution +(http://www.sudo.ws/sudo/contributors.html) for a list of people +who have contributed to \fBsudo\fR. +.SH "HISTORY" +.IX Header "HISTORY" +See the \s-1HISTORY\s0 file in the \fBsudo\fR distribution +(http://www.sudo.ws/sudo/history.html) for a brief history of sudo. +.SH "CAVEATS" +.IX Header "CAVEATS" +There is no easy way to prevent a user from gaining a root shell +if that user is allowed to run arbitrary commands via \fBsudo\fR. +Also, many programs (such as editors) allow the user to run commands +via shell escapes, thus avoiding \fBsudo\fR's checks. However, on +most systems it is possible to prevent shell escapes with the +\&\fIsudoers\fR\|(@mansectform@) module's \fInoexec\fR functionality. +.PP +It is not meaningful to run the \f(CW\*(C`cd\*(C'\fR command directly via sudo, e.g., +.PP +.Vb 1 +\& $ sudo cd /usr/local/protected +.Ve +.PP +since when the command exits the parent process (your shell) will +still be the same. Please see the \s-1EXAMPLES\s0 section for more information. +.PP +Running shell scripts via \fBsudo\fR can expose the same kernel bugs that +make setuid shell scripts unsafe on some operating systems (if your \s-1OS\s0 +has a /dev/fd/ directory, setuid shell scripts are generally safe). +.SH "BUGS" +.IX Header "BUGS" +If you feel you have found a bug in \fBsudo\fR, please submit a bug report +at http://www.sudo.ws/sudo/bugs/ +.SH "SUPPORT" +.IX Header "SUPPORT" +Limited free support is available via the sudo-users mailing list, +see http://www.sudo.ws/mailman/listinfo/sudo\-users to subscribe or +search the archives. +.SH "DISCLAIMER" +.IX Header "DISCLAIMER" +\&\fBsudo\fR is provided ``\s-1AS\s0 \s-1IS\s0'' and any express or implied warranties, +including, but not limited to, the implied warranties of merchantability +and fitness for a particular purpose are disclaimed. See the \s-1LICENSE\s0 +file distributed with \fBsudo\fR or http://www.sudo.ws/sudo/license.html +for complete details.