Annotation of embedaddon/sudo/doc/sudo.man.in, revision 1.1
1.1 ! misho 1: .\" Copyright (c) 1994-1996, 1998-2005, 2007-2011
! 2: .\" Todd C. Miller <Todd.Miller@courtesan.com>
! 3: .\"
! 4: .\" Permission to use, copy, modify, and distribute this software for any
! 5: .\" purpose with or without fee is hereby granted, provided that the above
! 6: .\" copyright notice and this permission notice appear in all copies.
! 7: .\"
! 8: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 9: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 10: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 11: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 12: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 13: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 14: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 15: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
! 16: .\"
! 17: .\" Sponsored in part by the Defense Advanced Research Projects
! 18: .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
! 19: .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
! 20: .\"
! 21: .nr SL @SEMAN@
! 22: .nr BA @BAMAN@
! 23: .nr LC @LCMAN@
! 24: .nr PT @password_timeout@
! 25: .\"
! 26: .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
! 27: .\"
! 28: .\" Standard preamble:
! 29: .\" ========================================================================
! 30: .de Sp \" Vertical space (when we can't use .PP)
! 31: .if t .sp .5v
! 32: .if n .sp
! 33: ..
! 34: .de Vb \" Begin verbatim text
! 35: .ft CW
! 36: .nf
! 37: .ne \\$1
! 38: ..
! 39: .de Ve \" End verbatim text
! 40: .ft R
! 41: .fi
! 42: ..
! 43: .\" Set up some character translations and predefined strings. \*(-- will
! 44: .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
! 45: .\" double quote, and \*(R" will give a right double quote. \*(C+ will
! 46: .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
! 47: .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
! 48: .\" nothing in troff, for use with C<>.
! 49: .tr \(*W-
! 50: .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
! 51: .ie n \{\
! 52: . ds -- \(*W-
! 53: . ds PI pi
! 54: . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
! 55: . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
! 56: . ds L" ""
! 57: . ds R" ""
! 58: . ds C`
! 59: . ds C'
! 60: 'br\}
! 61: .el\{\
! 62: . ds -- \|\(em\|
! 63: . ds PI \(*p
! 64: . ds L" ``
! 65: . ds R" ''
! 66: 'br\}
! 67: .\"
! 68: .\" Escape single quotes in literal strings from groff's Unicode transform.
! 69: .ie \n(.g .ds Aq \(aq
! 70: .el .ds Aq '
! 71: .\"
! 72: .\" If the F register is turned on, we'll generate index entries on stderr for
! 73: .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
! 74: .\" entries marked with X<> in POD. Of course, you'll have to process the
! 75: .\" output yourself in some meaningful fashion.
! 76: .ie \nF \{\
! 77: . de IX
! 78: . tm Index:\\$1\t\\n%\t"\\$2"
! 79: ..
! 80: . nr % 0
! 81: . rr F
! 82: .\}
! 83: .el \{\
! 84: . de IX
! 85: ..
! 86: .\}
! 87: .\"
! 88: .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
! 89: .\" Fear. Run. Save yourself. No user-serviceable parts.
! 90: . \" fudge factors for nroff and troff
! 91: .if n \{\
! 92: . ds #H 0
! 93: . ds #V .8m
! 94: . ds #F .3m
! 95: . ds #[ \f1
! 96: . ds #] \fP
! 97: .\}
! 98: .if t \{\
! 99: . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
! 100: . ds #V .6m
! 101: . ds #F 0
! 102: . ds #[ \&
! 103: . ds #] \&
! 104: .\}
! 105: . \" simple accents for nroff and troff
! 106: .if n \{\
! 107: . ds ' \&
! 108: . ds ` \&
! 109: . ds ^ \&
! 110: . ds , \&
! 111: . ds ~ ~
! 112: . ds /
! 113: .\}
! 114: .if t \{\
! 115: . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
! 116: . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
! 117: . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
! 118: . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
! 119: . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
! 120: . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
! 121: .\}
! 122: . \" troff and (daisy-wheel) nroff accents
! 123: .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
! 124: .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
! 125: .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
! 126: .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
! 127: .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
! 128: .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
! 129: .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
! 130: .ds ae a\h'-(\w'a'u*4/10)'e
! 131: .ds Ae A\h'-(\w'A'u*4/10)'E
! 132: . \" corrections for vroff
! 133: .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
! 134: .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
! 135: . \" for low resolution devices (crt and lpr)
! 136: .if \n(.H>23 .if \n(.V>19 \
! 137: \{\
! 138: . ds : e
! 139: . ds 8 ss
! 140: . ds o a
! 141: . ds d- d\h'-1'\(ga
! 142: . ds D- D\h'-1'\(hy
! 143: . ds th \o'bp'
! 144: . ds Th \o'LP'
! 145: . ds ae ae
! 146: . ds Ae AE
! 147: .\}
! 148: .rm #[ #] #H #V #F C
! 149: .\" ========================================================================
! 150: .\"
! 151: .IX Title "SUDO @mansectsu@"
! 152: .TH SUDO @mansectsu@ "September 16, 2011" "1.8.3" "MAINTENANCE COMMANDS"
! 153: .\" For nroff, turn off justification. Always turn off hyphenation; it makes
! 154: .\" way too many mistakes in technical documents.
! 155: .if n .ad l
! 156: .nh
! 157: .SH "NAME"
! 158: sudo, sudoedit \- execute a command as another user
! 159: .SH "SYNOPSIS"
! 160: .IX Header "SYNOPSIS"
! 161: \&\fBsudo\fR [\fB\-D\fR\ \fIlevel\fR] \fB\-h\fR | \fB\-K\fR | \fB\-k\fR | \fB\-V\fR
! 162: .PP
! 163: \&\fBsudo\fR \fB\-v\fR [\fB\-AknS\fR]
! 164: .if \n(BA [\fB\-a\fR\ \fIauth_type\fR]
! 165: [\fB\-D\fR\ \fIlevel\fR]
! 166: [\fB\-g\fR\ \fIgroup\ name\fR|\fI#gid\fR] [\fB\-p\fR\ \fIprompt\fR]
! 167: [\fB\-u\fR\ \fIuser\ name\fR|\fI#uid\fR]
! 168: .PP
! 169: \&\fBsudo\fR \fB\-l[l]\fR [\fB\-AknS\fR]
! 170: .if \n(BA [\fB\-a\fR\ \fIauth_type\fR]
! 171: [\fB\-D\fR\ \fIlevel\fR]
! 172: [\fB\-g\fR\ \fIgroup\ name\fR|\fI#gid\fR] [\fB\-p\fR\ \fIprompt\fR]
! 173: [\fB\-U\fR\ \fIuser\ name\fR] [\fB\-u\fR\ \fIuser\ name\fR|\fI#uid\fR] [\fIcommand\fR]
! 174: .PP
! 175: \&\fBsudo\fR [\fB\-AbEHnPS\fR]
! 176: .if \n(BA [\fB\-a\fR\ \fIauth_type\fR]
! 177: [\fB\-C\fR\ \fIfd\fR]
! 178: [\fB\-D\fR\ \fIlevel\fR]
! 179: .if \n(LC [\fB\-c\fR\ \fIclass\fR|\fI\-\fR]
! 180: [\fB\-g\fR\ \fIgroup\ name\fR|\fI#gid\fR] [\fB\-p\fR\ \fIprompt\fR]
! 181: .if \n(SL [\fB\-r\fR\ \fIrole\fR] [\fB\-t\fR\ \fItype\fR]
! 182: [\fB\-u\fR\ \fIuser\ name\fR|\fI#uid\fR]
! 183: [\fB\s-1VAR\s0\fR=\fIvalue\fR] [\fB\-i\fR\ |\ \fB\-s\fR] [\fIcommand\fR]
! 184: .PP
! 185: \&\fBsudoedit\fR [\fB\-AnS\fR]
! 186: .if \n(BA [\fB\-a\fR\ \fIauth_type\fR]
! 187: [\fB\-C\fR\ \fIfd\fR]
! 188: .if \n(LC [\fB\-c\fR\ \fIclass\fR|\fI\-\fR]
! 189: [\fB\-D\fR\ \fIlevel\fR]
! 190: [\fB\-g\fR\ \fIgroup\ name\fR|\fI#gid\fR] [\fB\-p\fR\ \fIprompt\fR]
! 191: [\fB\-u\fR\ \fIuser\ name\fR|\fI#uid\fR] file ...
! 192: .SH "DESCRIPTION"
! 193: .IX Header "DESCRIPTION"
! 194: \&\fBsudo\fR allows a permitted user to execute a \fIcommand\fR as the
! 195: superuser or another user, as specified by the security policy.
! 196: The real and effective uid and gid are set to match those of the
! 197: target user, as specified in the password database, and the group
! 198: vector is initialized based on the group database (unless the \fB\-P\fR
! 199: option was specified).
! 200: .PP
! 201: \&\fBsudo\fR supports a plugin architecture for security policies and
! 202: input/output logging. Third parties can develop and distribute
! 203: their own policy and I/O logging modules to work seemlessly with
! 204: the \fBsudo\fR front end. The default security policy is \fIsudoers\fR,
! 205: which is configured via the file \fI@sysconfdir@/sudoers\fR, or via
! 206: \&\s-1LDAP\s0. See the \s-1PLUGINS\s0 section for more information.
! 207: .PP
! 208: The security policy determines what privileges, if any, a user has
! 209: to run \fBsudo\fR. The policy may require that users authenticate
! 210: themselves with a password or another authentication mechanism. If
! 211: authentication is required, \fBsudo\fR will exit if the user's password
! 212: is not entered within a configurable time limit. This limit is
! 213: policy-specific; the default password prompt timeout for the
! 214: \&\fIsudoers\fR security policy is
! 215: .ie \n(PT \f(CW\*(C`@password_timeout@\*(C'\fR minutes.
! 216: .el unlimited.
! 217: .PP
! 218: Security policies may support credential caching to allow the user
! 219: to run \fBsudo\fR again for a period of time without requiring
! 220: authentication. The \fIsudoers\fR policy caches credentials for
! 221: \&\f(CW\*(C`@timeout@\*(C'\fR minutes, unless overridden in \fIsudoers\fR\|(@mansectform@). By
! 222: running \fBsudo\fR with the \fB\-v\fR option, a user can update the cached
! 223: credentials without running a \fIcommand\fR.
! 224: .PP
! 225: When invoked as \fBsudoedit\fR, the \fB\-e\fR option (described below),
! 226: is implied.
! 227: .PP
! 228: Security policies may log successful and failed attempts to use
! 229: \&\fBsudo\fR. If an I/O plugin is configured, the running command's
! 230: input and output may be logged as well.
! 231: .SH "OPTIONS"
! 232: .IX Header "OPTIONS"
! 233: \&\fBsudo\fR accepts the following command line options:
! 234: .IP "\-A" 12
! 235: .IX Item "-A"
! 236: Normally, if \fBsudo\fR requires a password, it will read it from the
! 237: user's terminal. If the \fB\-A\fR (\fIaskpass\fR) option is specified,
! 238: a (possibly graphical) helper program is executed to read the user's
! 239: password and output the password to the standard output. If the
! 240: \&\f(CW\*(C`SUDO_ASKPASS\*(C'\fR environment variable is set, it specifies the path
! 241: to the helper program. Otherwise, if \fI@sysconfdir@/sudo.conf\fR
! 242: contains a line specifying the askpass program, that value will be
! 243: used. For example:
! 244: .Sp
! 245: .Vb 2
! 246: \& # Path to askpass helper program
! 247: \& Path askpass /usr/X11R6/bin/ssh\-askpass
! 248: .Ve
! 249: .Sp
! 250: If no askpass program is available, sudo will exit with an error.
! 251: .if \n(BA \{\
! 252: .IP "\-a \fItype\fR" 12
! 253: .IX Item "-a type"
! 254: The \fB\-a\fR (\fIauthentication type\fR) option causes \fBsudo\fR to use the
! 255: specified authentication type when validating the user, as allowed
! 256: by \fI/etc/login.conf\fR. The system administrator may specify a list
! 257: of sudo-specific authentication methods by adding an \*(L"auth-sudo\*(R"
! 258: entry in \fI/etc/login.conf\fR. This option is only available on systems
! 259: that support \s-1BSD\s0 authentication.
! 260: \}
! 261: .IP "\-b" 12
! 262: .IX Item "-b"
! 263: The \fB\-b\fR (\fIbackground\fR) option tells \fBsudo\fR to run the given
! 264: command in the background. Note that if you use the \fB\-b\fR
! 265: option you cannot use shell job control to manipulate the process.
! 266: Most interactive commands will fail to work properly in background
! 267: mode.
! 268: .IP "\-C \fIfd\fR" 12
! 269: .IX Item "-C fd"
! 270: Normally, \fBsudo\fR will close all open file descriptors other than
! 271: standard input, standard output and standard error. The \fB\-C\fR
! 272: (\fIclose from\fR) option allows the user to specify a starting point
! 273: above the standard error (file descriptor three). Values less than
! 274: three are not permitted. The security policy may restrict the
! 275: user's ability to use the \fB\-C\fR option. The \fIsudoers\fR policy only
! 276: permits use of the \fB\-C\fR option when the administrator has enabled
! 277: the \fIclosefrom_override\fR option.
! 278: .if \n(LC \{\
! 279: .IP "\-c \fIclass\fR" 12
! 280: .IX Item "-c class"
! 281: The \fB\-c\fR (\fIclass\fR) option causes \fBsudo\fR to run the specified command
! 282: with resources limited by the specified login class. The \fIclass\fR
! 283: argument can be either a class name as defined in \fI/etc/login.conf\fR,
! 284: or a single '\-' character. Specifying a \fIclass\fR of \f(CW\*(C`\-\*(C'\fR indicates
! 285: that the command should be run restricted by the default login
! 286: capabilities for the user the command is run as. If the \fIclass\fR
! 287: argument specifies an existing user class, the command must be run
! 288: as root, or the \fBsudo\fR command must be run from a shell that is already
! 289: root. This option is only available on systems with \s-1BSD\s0 login classes.
! 290: \}
! 291: .IP "\-D \fIlevel\fR" 12
! 292: .IX Item "-D level"
! 293: Enable debugging of \fBsudo\fR plugins and \fBsudo\fR itself. The \fIlevel\fR
! 294: may be a value from 1 through 9.
! 295: .IP "\-E" 12
! 296: .IX Item "-E"
! 297: The \fB\-E\fR (\fIpreserve\fR \fIenvironment\fR) option indicates to the
! 298: security policy that the user wishes to preserve their existing
! 299: environment variables. The security policy may return an error if
! 300: the \fB\-E\fR option is specified and the user does not have permission
! 301: to preserve the environment.
! 302: .IP "\-e" 12
! 303: .IX Item "-e"
! 304: The \fB\-e\fR (\fIedit\fR) option indicates that, instead of running a
! 305: command, the user wishes to edit one or more files. In lieu of a
! 306: command, the string \*(L"sudoedit\*(R" is used when consulting the security
! 307: policy. If the user is authorized by the policy, the following
! 308: steps are taken:
! 309: .RS 12
! 310: .IP "1." 4
! 311: Temporary copies are made of the files to be edited with the owner
! 312: set to the invoking user.
! 313: .IP "2." 4
! 314: The editor specified by the policy is run to edit the temporary files.
! 315: 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
! 316: environment variables (in that order). If none of \f(CW\*(C`SUDO_EDITOR\*(C'\fR,
! 317: \&\f(CW\*(C`VISUAL\*(C'\fR or \f(CW\*(C`EDITOR\*(C'\fR are set, the first program listed in the
! 318: \&\fIeditor\fR \fIsudoers\fR\|(@mansectform@) option is used.
! 319: .IP "3." 4
! 320: If they have been modified, the temporary files are copied back to
! 321: their original location and the temporary versions are removed.
! 322: .RE
! 323: .RS 12
! 324: .Sp
! 325: If the specified file does not exist, it will be created. Note
! 326: that unlike most commands run by \fBsudo\fR, the editor is run with
! 327: the invoking user's environment unmodified. If, for some reason,
! 328: \&\fBsudo\fR is unable to update a file with its edited version, the
! 329: user will receive a warning and the edited copy will remain in a
! 330: temporary file.
! 331: .RE
! 332: .IP "\-g \fIgroup\fR" 12
! 333: .IX Item "-g group"
! 334: Normally, \fBsudo\fR runs a command with the primary group set to the
! 335: one specified by the password database for the user the command is
! 336: being run as (by default, root). The \fB\-g\fR (\fIgroup\fR) option causes
! 337: \&\fBsudo\fR to run the command with the primary group set to \fIgroup\fR
! 338: instead. To specify a \fIgid\fR instead of a \fIgroup name\fR, use
! 339: \&\fI#gid\fR. When running commands as a \fIgid\fR, many shells require
! 340: that the '#' be escaped with a backslash ('\e'). If no \fB\-u\fR option
! 341: is specified, the command will be run as the invoking user (not
! 342: root). In either case, the primary group will be set to \fIgroup\fR.
! 343: .IP "\-H" 12
! 344: .IX Item "-H"
! 345: The \fB\-H\fR (\fI\s-1HOME\s0\fR) option requests that the security policy set
! 346: the \f(CW\*(C`HOME\*(C'\fR environment variable to the home directory of the target
! 347: user (root by default) as specified by the password database.
! 348: Depending on the policy, this may be the default behavior.
! 349: .IP "\-h" 12
! 350: .IX Item "-h"
! 351: The \fB\-h\fR (\fIhelp\fR) option causes \fBsudo\fR to print a short help message
! 352: to the standard output and exit.
! 353: .IP "\-i [command]" 12
! 354: .IX Item "-i [command]"
! 355: The \fB\-i\fR (\fIsimulate initial login\fR) option runs the shell specified
! 356: by the password database entry of the target user as a login shell.
! 357: This means that login-specific resource files such as \f(CW\*(C`.profile\*(C'\fR
! 358: or \f(CW\*(C`.login\*(C'\fR will be read by the shell. If a command is specified,
! 359: it is passed to the shell for execution via the shell's \fB\-c\fR option.
! 360: If no command is specified, an interactive shell is executed.
! 361: \&\fBsudo\fR attempts to change to that user's home directory before
! 362: running the shell. The security policy shall initialize the
! 363: environment to a minimal set of variables, similar to what is present
! 364: when a user logs in. The \fICommand Environment\fR section in the
! 365: \&\fIsudoers\fR\|(@mansectform@) manual documents how the \fB\-i\fR option affects the
! 366: environment in which a command is run when the \fIsudoers\fR policy
! 367: is in use.
! 368: .IP "\-K" 12
! 369: .IX Item "-K"
! 370: The \fB\-K\fR (sure \fIkill\fR) option is like \fB\-k\fR except that it removes
! 371: the user's cached credentials entirely and may not be used in
! 372: conjunction with a command or other option. This option does not
! 373: require a password. Not all security policies support credential
! 374: caching.
! 375: .IP "\-k [command]" 12
! 376: .IX Item "-k [command]"
! 377: When used alone, the \fB\-k\fR (\fIkill\fR) option to \fBsudo\fR invalidates
! 378: the user's cached credentials. The next time \fBsudo\fR is run a
! 379: password will be required. This option does not require a password
! 380: and was added to allow a user to revoke \fBsudo\fR permissions from a
! 381: \&.logout file. Not all security policies support credential
! 382: caching.
! 383: .Sp
! 384: When used in conjunction with a command or an option that may require
! 385: a password, the \fB\-k\fR option will cause \fBsudo\fR to ignore the user's
! 386: cached credentials. As a result, \fBsudo\fR will prompt for a password
! 387: (if one is required by the security policy) and will not update the
! 388: user's cached credentials.
! 389: .IP "\-l[l] [\fIcommand\fR]" 12
! 390: .IX Item "-l[l] [command]"
! 391: If no \fIcommand\fR is specified, the \fB\-l\fR (\fIlist\fR) option will list
! 392: the allowed (and forbidden) commands for the invoking user (or the
! 393: user specified by the \fB\-U\fR option) on the current host. If a
! 394: \&\fIcommand\fR is specified and is permitted by the security policy,
! 395: the fully-qualified path to the command is displayed along with any
! 396: command line arguments. If \fIcommand\fR is specified but not allowed,
! 397: \&\fBsudo\fR will exit with a status value of 1. If the \fB\-l\fR option
! 398: is specified with an \fBl\fR argument (i.e. \fB\-ll\fR), or if \fB\-l\fR is
! 399: specified multiple times, a longer list format is used.
! 400: .IP "\-n" 12
! 401: .IX Item "-n"
! 402: The \fB\-n\fR (\fInon-interactive\fR) option prevents \fBsudo\fR from prompting
! 403: the user for a password. If a password is required for the command
! 404: to run, \fBsudo\fR will display an error messages and exit.
! 405: .IP "\-P" 12
! 406: .IX Item "-P"
! 407: The \fB\-P\fR (\fIpreserve\fR \fIgroup vector\fR) option causes \fBsudo\fR to
! 408: preserve the invoking user's group vector unaltered. By default,
! 409: the \fIsudoers\fR policy will initialize the group vector to the list
! 410: of groups the target user is in. The real and effective group IDs,
! 411: however, are still set to match the target user.
! 412: .IP "\-p \fIprompt\fR" 12
! 413: .IX Item "-p prompt"
! 414: The \fB\-p\fR (\fIprompt\fR) option allows you to override the default
! 415: password prompt and use a custom one. The following percent (`\f(CW\*(C`%\*(C'\fR')
! 416: escapes are supported by the \fIsudoers\fR policy:
! 417: .RS 12
! 418: .ie n .IP "%H" 4
! 419: .el .IP "\f(CW%H\fR" 4
! 420: .IX Item "%H"
! 421: expanded to the host name including the domain name (on if
! 422: the machine's host name is fully qualified or the \fIfqdn\fR option
! 423: is set in \fIsudoers\fR\|(@mansectform@))
! 424: .ie n .IP "%h" 4
! 425: .el .IP "\f(CW%h\fR" 4
! 426: .IX Item "%h"
! 427: expanded to the local host name without the domain name
! 428: .ie n .IP "%p" 4
! 429: .el .IP "\f(CW%p\fR" 4
! 430: .IX Item "%p"
! 431: expanded to the name of the user whose password is being requested
! 432: (respects the \fIrootpw\fR, \fItargetpw\fR and \fIrunaspw\fR flags in
! 433: \&\fIsudoers\fR\|(@mansectform@))
! 434: .ie n .IP "%U" 4
! 435: .el .IP "\f(CW%U\fR" 4
! 436: .IX Item "%U"
! 437: expanded to the login name of the user the command will be run as
! 438: (defaults to root unless the \f(CW\*(C`\-u\*(C'\fR option is also specified)
! 439: .ie n .IP "%u" 4
! 440: .el .IP "\f(CW%u\fR" 4
! 441: .IX Item "%u"
! 442: expanded to the invoking user's login name
! 443: .ie n .IP "\*(C`%%\*(C'" 4
! 444: .el .IP "\f(CW\*(C`%%\*(C'\fR" 4
! 445: .IX Item "%%"
! 446: two consecutive \f(CW\*(C`%\*(C'\fR characters are collapsed into a single \f(CW\*(C`%\*(C'\fR character
! 447: .RE
! 448: .RS 12
! 449: .Sp
! 450: The prompt specified by the \fB\-p\fR option will override the system
! 451: password prompt on systems that support \s-1PAM\s0 unless the
! 452: \&\fIpassprompt_override\fR flag is disabled in \fIsudoers\fR.
! 453: .RE
! 454: .if \n(SL \{\
! 455: .IP "\-r \fIrole\fR" 12
! 456: .IX Item "-r role"
! 457: The \fB\-r\fR (\fIrole\fR) option causes the new (SELinux) security context to
! 458: have the role specified by \fIrole\fR.
! 459: \}
! 460: .IP "\-S" 12
! 461: .IX Item "-S"
! 462: The \fB\-S\fR (\fIstdin\fR) option causes \fBsudo\fR to read the password from
! 463: the standard input instead of the terminal device. The password must
! 464: be followed by a newline character.
! 465: .IP "\-s [command]" 12
! 466: .IX Item "-s [command]"
! 467: The \fB\-s\fR (\fIshell\fR) option runs the shell specified by the \fI\s-1SHELL\s0\fR
! 468: environment variable if it is set or the shell as specified in the
! 469: password database. If a command is specified, it is passed to the
! 470: shell for execution via the shell's \fB\-c\fR option. If no command
! 471: is specified, an interactive shell is executed.
! 472: .if \n(SL \{\
! 473: .IP "\-t \fItype\fR" 12
! 474: .IX Item "-t type"
! 475: The \fB\-t\fR (\fItype\fR) option causes the new (SELinux) security context to
! 476: have the type specified by \fItype\fR. If no type is specified, the default
! 477: type is derived from the specified role.
! 478: \}
! 479: .IP "\-U \fIuser\fR" 12
! 480: .IX Item "-U user"
! 481: The \fB\-U\fR (\fIother user\fR) option is used in conjunction with the
! 482: \&\fB\-l\fR option to specify the user whose privileges should be listed.
! 483: The security policy may restrict listing other users' privileges.
! 484: The \fIsudoers\fR policy only allows root or a user with the \f(CW\*(C`ALL\*(C'\fR
! 485: privilege on the current host to use this option.
! 486: .IP "\-u \fIuser\fR" 12
! 487: .IX Item "-u user"
! 488: The \fB\-u\fR (\fIuser\fR) option causes \fBsudo\fR to run the specified
! 489: command as a user other than \fIroot\fR. To specify a \fIuid\fR instead
! 490: of a \fIuser name\fR, use \fI#uid\fR. When running commands as a \fIuid\fR,
! 491: many shells require that the '#' be escaped with a backslash ('\e').
! 492: Security policies may restrict \fIuid\fRs to those listed in the
! 493: password database. The \fIsudoers\fR policy allows \fIuid\fRs that are
! 494: not in the password database as long as the \fItargetpw\fR option is
! 495: not set. Other security policies may not support this.
! 496: .IP "\-V" 12
! 497: .IX Item "-V"
! 498: The \fB\-V\fR (\fIversion\fR) option causes \fBsudo\fR to print its version
! 499: string and the version string of the security policy plugin and any
! 500: I/O plugins. If the invoking user is already root the \fB\-V\fR option
! 501: will display the arguments passed to configure when \fIsudo\fR was
! 502: built and plugins may display more verbose information such as
! 503: default options.
! 504: .IP "\-v" 12
! 505: .IX Item "-v"
! 506: When given the \fB\-v\fR (\fIvalidate\fR) option, \fBsudo\fR will update the
! 507: user's cached credentials, authenticating the user's password if
! 508: necessary. For the \fIsudoers\fR plugin, this extends the \fBsudo\fR
! 509: timeout for another \f(CW\*(C`@timeout@\*(C'\fR minutes (or whatever the timeout
! 510: is set to in \fIsudoers\fR) but does not run a command. Not all
! 511: security policies support cached credentials.
! 512: .IP "\-\-" 12
! 513: The \fB\-\-\fR option indicates that \fBsudo\fR should stop processing command
! 514: line arguments.
! 515: .PP
! 516: Environment variables to be set for the command may also be passed
! 517: on the command line in the form of \fB\s-1VAR\s0\fR=\fIvalue\fR, e.g.
! 518: \&\fB\s-1LD_LIBRARY_PATH\s0\fR=\fI/usr/local/pkg/lib\fR. Variables passed on the
! 519: command line are subject to the same restrictions as normal environment
! 520: variables with one important exception. If the \fIsetenv\fR option
! 521: is set in \fIsudoers\fR, the command to be run has the \f(CW\*(C`SETENV\*(C'\fR tag
! 522: set or the command matched is \f(CW\*(C`ALL\*(C'\fR, the user may set variables
! 523: that would overwise be forbidden. See \fIsudoers\fR\|(@mansectform@) for more information.
! 524: .SH "PLUGINS"
! 525: .IX Header "PLUGINS"
! 526: Plugins are dynamically loaded based on the contents of the
! 527: \&\fI@sysconfdir@/sudo.conf\fR file. If no \fI@sysconfdir@/sudo.conf\fR
! 528: file is present, or it contains no \f(CW\*(C`Plugin\*(C'\fR lines, \fBsudo\fR
! 529: will use the traditional \fIsudoers\fR security policy and I/O logging,
! 530: which corresponds to the following \fI@sysconfdir@/sudo.conf\fR file.
! 531: .PP
! 532: .Vb 10
! 533: \& #
! 534: \& # Default @sysconfdir@/sudo.conf file
! 535: \& #
! 536: \& # Format:
! 537: \& # Plugin plugin_name plugin_path
! 538: \& # Path askpass /path/to/askpass
! 539: \& # Path noexec /path/to/noexec.so
! 540: \& #
! 541: \& # The plugin_path is relative to @prefix@/libexec unless
! 542: \& # fully qualified.
! 543: \& # The plugin_name corresponds to a global symbol in the plugin
! 544: \& # that contains the plugin interface structure.
! 545: \& #
! 546: \& Plugin policy_plugin sudoers.so
! 547: \& Plugin io_plugin sudoers.so
! 548: .Ve
! 549: .PP
! 550: A \f(CW\*(C`Plugin\*(C'\fR line consists of the \f(CW\*(C`Plugin\*(C'\fR keyword, followed by the
! 551: \&\fIsymbol_name\fR and the \fIpath\fR to the shared object containing the
! 552: plugin. The \fIsymbol_name\fR is the name of the \f(CW\*(C`struct policy_plugin\*(C'\fR
! 553: or \f(CW\*(C`struct io_plugin\*(C'\fR in the plugin shared object. The \fIpath\fR
! 554: may be fully qualified or relative. If not fully qualified it is
! 555: relative to the \fI@prefix@/libexec\fR directory. Any additional
! 556: parameters after the \fIpath\fR are ignored. Lines that don't begin
! 557: with \f(CW\*(C`Plugin\*(C'\fR or \f(CW\*(C`Path\*(C'\fR are silently ignored
! 558: .PP
! 559: For more information, see the \fIsudo_plugin\fR\|(@mansectsu@) manual.
! 560: .SH "PATHS"
! 561: .IX Header "PATHS"
! 562: A \f(CW\*(C`Path\*(C'\fR line consists of the \f(CW\*(C`Path\*(C'\fR keyword, followed by the
! 563: name of the path to set and its value. E.g.
! 564: .PP
! 565: .Vb 2
! 566: \& Path noexec @noexec_file@
! 567: \& Path askpass /usr/X11R6/bin/ssh\-askpass
! 568: .Ve
! 569: .PP
! 570: The following plugin-agnostic paths may be set in the
! 571: \&\fI@sysconfdir@/sudo.conf\fR file.
! 572: .IP "askpass" 16
! 573: .IX Item "askpass"
! 574: The fully qualified path to a helper program used to read the user's
! 575: password when no terminal is available. This may be the case when
! 576: \&\fBsudo\fR is executed from a graphical (as opposed to text-based)
! 577: application. The program specified by \fIaskpass\fR should display
! 578: the argument passed to it as the prompt and write the user's password
! 579: to the standard output. The value of \fIaskpass\fR may be overridden
! 580: by the \f(CW\*(C`SUDO_ASKPASS\*(C'\fR environment variable.
! 581: .IP "noexec" 16
! 582: .IX Item "noexec"
! 583: The fully-qualified path to a shared library containing dummy
! 584: versions of the \fIexecv()\fR, \fIexecve()\fR and \fIfexecve()\fR library functions
! 585: that just return an error. This is used to implement the \fInoexec\fR
! 586: functionality on systems that support \f(CW\*(C`LD_PRELOAD\*(C'\fR or its equivalent.
! 587: Defaults to \fI@noexec_file@\fR.
! 588: .SH "RETURN VALUES"
! 589: .IX Header "RETURN VALUES"
! 590: Upon successful execution of a program, the exit status from \fBsudo\fR
! 591: will simply be the exit status of the program that was executed.
! 592: .PP
! 593: Otherwise, \fBsudo\fR exits with a value of 1 if there is a
! 594: configuration/permission problem or if \fBsudo\fR cannot execute the
! 595: given command. In the latter case the error string is printed to
! 596: the standard error. If \fBsudo\fR cannot \fIstat\fR\|(2) one or more entries
! 597: in the user's \f(CW\*(C`PATH\*(C'\fR, an error is printed on stderr. (If the
! 598: directory does not exist or if it is not really a directory, the
! 599: entry is ignored and no error is printed.) This should not happen
! 600: under normal circumstances. The most common reason for \fIstat\fR\|(2)
! 601: to return \*(L"permission denied\*(R" is if you are running an automounter
! 602: and one of the directories in your \f(CW\*(C`PATH\*(C'\fR is on a machine that is
! 603: currently unreachable.
! 604: .SH "SECURITY NOTES"
! 605: .IX Header "SECURITY NOTES"
! 606: \&\fBsudo\fR tries to be safe when executing external commands.
! 607: .PP
! 608: To prevent command spoofing, \fBsudo\fR checks \*(L".\*(R" and "" (both denoting
! 609: current directory) last when searching for a command in the user's
! 610: \&\s-1PATH\s0 (if one or both are in the \s-1PATH\s0). Note, however, that the
! 611: actual \f(CW\*(C`PATH\*(C'\fR environment variable is \fInot\fR modified and is passed
! 612: unchanged to the program that \fBsudo\fR executes.
! 613: .PP
! 614: Please note that \fBsudo\fR will normally only log the command it
! 615: explicitly runs. If a user runs a command such as \f(CW\*(C`sudo su\*(C'\fR or
! 616: \&\f(CW\*(C`sudo sh\*(C'\fR, subsequent commands run from that shell are not subject
! 617: to \fBsudo\fR's security policy. The same is true for commands that
! 618: offer shell escapes (including most editors). If I/O logging is
! 619: enabled, subsequent commands will have their input and/or output
! 620: logged, but there will not be traditional logs for those commands.
! 621: Because of this, care must be taken when giving users access to
! 622: commands via \fBsudo\fR to verify that the command does not inadvertently
! 623: give the user an effective root shell. For more information, please
! 624: see the \f(CW\*(C`PREVENTING SHELL ESCAPES\*(C'\fR section in \fIsudoers\fR\|(@mansectform@).
! 625: .SH "ENVIRONMENT"
! 626: .IX Header "ENVIRONMENT"
! 627: \&\fBsudo\fR utilizes the following environment variables. The security
! 628: policy has control over the content of the command's environment.
! 629: .ie n .IP "\*(C`EDITOR\*(C'" 16
! 630: .el .IP "\f(CW\*(C`EDITOR\*(C'\fR" 16
! 631: .IX Item "EDITOR"
! 632: Default editor to use in \fB\-e\fR (sudoedit) mode if neither \f(CW\*(C`SUDO_EDITOR\*(C'\fR
! 633: nor \f(CW\*(C`VISUAL\*(C'\fR is set
! 634: .ie n .IP "\*(C`MAIL\*(C'" 16
! 635: .el .IP "\f(CW\*(C`MAIL\*(C'\fR" 16
! 636: .IX Item "MAIL"
! 637: In \fB\-i\fR mode or when \fIenv_reset\fR is enabled in \fIsudoers\fR, set
! 638: to the mail spool of the target user
! 639: .ie n .IP "\*(C`HOME\*(C'" 16
! 640: .el .IP "\f(CW\*(C`HOME\*(C'\fR" 16
! 641: .IX Item "HOME"
! 642: Set to the home directory of the target user if \fB\-i\fR or \fB\-H\fR are
! 643: specified, \fIenv_reset\fR or \fIalways_set_home\fR are set in \fIsudoers\fR,
! 644: or when the \fB\-s\fR option is specified and \fIset_home\fR is set in
! 645: \&\fIsudoers\fR
! 646: .ie n .IP "\*(C`PATH\*(C'" 16
! 647: .el .IP "\f(CW\*(C`PATH\*(C'\fR" 16
! 648: .IX Item "PATH"
! 649: May be overridden by the security policy.
! 650: .ie n .IP "\*(C`SHELL\*(C'" 16
! 651: .el .IP "\f(CW\*(C`SHELL\*(C'\fR" 16
! 652: .IX Item "SHELL"
! 653: Used to determine shell to run with \f(CW\*(C`\-s\*(C'\fR option
! 654: .ie n .IP "\*(C`SUDO_ASKPASS\*(C'" 16
! 655: .el .IP "\f(CW\*(C`SUDO_ASKPASS\*(C'\fR" 16
! 656: .IX Item "SUDO_ASKPASS"
! 657: Specifies the path to a helper program used to read the password
! 658: if no terminal is available or if the \f(CW\*(C`\-A\*(C'\fR option is specified.
! 659: .ie n .IP "\*(C`SUDO_COMMAND\*(C'" 16
! 660: .el .IP "\f(CW\*(C`SUDO_COMMAND\*(C'\fR" 16
! 661: .IX Item "SUDO_COMMAND"
! 662: Set to the command run by sudo
! 663: .ie n .IP "\*(C`SUDO_EDITOR\*(C'" 16
! 664: .el .IP "\f(CW\*(C`SUDO_EDITOR\*(C'\fR" 16
! 665: .IX Item "SUDO_EDITOR"
! 666: Default editor to use in \fB\-e\fR (sudoedit) mode
! 667: .ie n .IP "\*(C`SUDO_GID\*(C'" 16
! 668: .el .IP "\f(CW\*(C`SUDO_GID\*(C'\fR" 16
! 669: .IX Item "SUDO_GID"
! 670: Set to the group \s-1ID\s0 of the user who invoked sudo
! 671: .ie n .IP "\*(C`SUDO_PROMPT\*(C'" 16
! 672: .el .IP "\f(CW\*(C`SUDO_PROMPT\*(C'\fR" 16
! 673: .IX Item "SUDO_PROMPT"
! 674: Used as the default password prompt
! 675: .ie n .IP "\*(C`SUDO_PS1\*(C'" 16
! 676: .el .IP "\f(CW\*(C`SUDO_PS1\*(C'\fR" 16
! 677: .IX Item "SUDO_PS1"
! 678: If set, \f(CW\*(C`PS1\*(C'\fR will be set to its value for the program being run
! 679: .ie n .IP "\*(C`SUDO_UID\*(C'" 16
! 680: .el .IP "\f(CW\*(C`SUDO_UID\*(C'\fR" 16
! 681: .IX Item "SUDO_UID"
! 682: Set to the user \s-1ID\s0 of the user who invoked sudo
! 683: .ie n .IP "\*(C`SUDO_USER\*(C'" 16
! 684: .el .IP "\f(CW\*(C`SUDO_USER\*(C'\fR" 16
! 685: .IX Item "SUDO_USER"
! 686: Set to the login of the user who invoked sudo
! 687: .ie n .IP "\*(C`USER\*(C'" 16
! 688: .el .IP "\f(CW\*(C`USER\*(C'\fR" 16
! 689: .IX Item "USER"
! 690: Set to the target user (root unless the \fB\-u\fR option is specified)
! 691: .ie n .IP "\*(C`VISUAL\*(C'" 16
! 692: .el .IP "\f(CW\*(C`VISUAL\*(C'\fR" 16
! 693: .IX Item "VISUAL"
! 694: Default editor to use in \fB\-e\fR (sudoedit) mode if \f(CW\*(C`SUDO_EDITOR\*(C'\fR
! 695: is not set
! 696: .SH "FILES"
! 697: .IX Header "FILES"
! 698: .ie n .IP "\fI@sysconfdir@/sudo.conf\fR" 24
! 699: .el .IP "\fI@sysconfdir@/sudo.conf\fR" 24
! 700: .IX Item "@sysconfdir@/sudo.conf"
! 701: \&\fBsudo\fR plugin and path configuration
! 702: .SH "EXAMPLES"
! 703: .IX Header "EXAMPLES"
! 704: Note: the following examples assume a properly configured security policy.
! 705: .PP
! 706: To get a file listing of an unreadable directory:
! 707: .PP
! 708: .Vb 1
! 709: \& $ sudo ls /usr/local/protected
! 710: .Ve
! 711: .PP
! 712: To list the home directory of user yaz on a machine where the
! 713: file system holding ~yaz is not exported as root:
! 714: .PP
! 715: .Vb 1
! 716: \& $ sudo \-u yaz ls ~yaz
! 717: .Ve
! 718: .PP
! 719: To edit the \fIindex.html\fR file as user www:
! 720: .PP
! 721: .Vb 1
! 722: \& $ sudo \-u www vi ~www/htdocs/index.html
! 723: .Ve
! 724: .PP
! 725: To view system logs only accessible to root and users in the adm group:
! 726: .PP
! 727: .Vb 1
! 728: \& $ sudo \-g adm view /var/log/syslog
! 729: .Ve
! 730: .PP
! 731: To run an editor as jim with a different primary group:
! 732: .PP
! 733: .Vb 1
! 734: \& $ sudo \-u jim \-g audio vi ~jim/sound.txt
! 735: .Ve
! 736: .PP
! 737: To shutdown a machine:
! 738: .PP
! 739: .Vb 1
! 740: \& $ sudo shutdown \-r +15 "quick reboot"
! 741: .Ve
! 742: .PP
! 743: To make a usage listing of the directories in the /home
! 744: partition. Note that this runs the commands in a sub-shell
! 745: to make the \f(CW\*(C`cd\*(C'\fR and file redirection work.
! 746: .PP
! 747: .Vb 1
! 748: \& $ sudo sh \-c "cd /home ; du \-s * | sort \-rn > USAGE"
! 749: .Ve
! 750: .SH "SEE ALSO"
! 751: .IX Header "SEE ALSO"
! 752: \&\fIgrep\fR\|(1), \fIsu\fR\|(1), \fIstat\fR\|(2),
! 753: .if \n(LC \&\fIlogin_cap\fR\|(3),
! 754: \&\fIpasswd\fR\|(@mansectform@), \fIsudoers\fR\|(@mansectform@), \fIsudo_plugin\fR\|(@mansectsu@), \fIsudoreplay\fR\|(@mansectsu@), \fIvisudo\fR\|(@mansectsu@)
! 755: .SH "AUTHORS"
! 756: .IX Header "AUTHORS"
! 757: Many people have worked on \fBsudo\fR over the years; this
! 758: version consists of code written primarily by:
! 759: .PP
! 760: .Vb 1
! 761: \& Todd C. Miller
! 762: .Ve
! 763: .PP
! 764: See the \s-1HISTORY\s0 file in the \fBsudo\fR distribution or visit
! 765: http://www.sudo.ws/sudo/history.html for a short history
! 766: of \fBsudo\fR.
! 767: .SH "CAVEATS"
! 768: .IX Header "CAVEATS"
! 769: There is no easy way to prevent a user from gaining a root shell
! 770: if that user is allowed to run arbitrary commands via \fBsudo\fR.
! 771: Also, many programs (such as editors) allow the user to run commands
! 772: via shell escapes, thus avoiding \fBsudo\fR's checks. However, on
! 773: most systems it is possible to prevent shell escapes with the
! 774: \&\fIsudoers\fR\|(@mansectform@) module's \fInoexec\fR functionality.
! 775: .PP
! 776: It is not meaningful to run the \f(CW\*(C`cd\*(C'\fR command directly via sudo, e.g.,
! 777: .PP
! 778: .Vb 1
! 779: \& $ sudo cd /usr/local/protected
! 780: .Ve
! 781: .PP
! 782: since when the command exits the parent process (your shell) will
! 783: still be the same. Please see the \s-1EXAMPLES\s0 section for more information.
! 784: .PP
! 785: Running shell scripts via \fBsudo\fR can expose the same kernel bugs that
! 786: make setuid shell scripts unsafe on some operating systems (if your \s-1OS\s0
! 787: has a /dev/fd/ directory, setuid shell scripts are generally safe).
! 788: .SH "BUGS"
! 789: .IX Header "BUGS"
! 790: If you feel you have found a bug in \fBsudo\fR, please submit a bug report
! 791: at http://www.sudo.ws/sudo/bugs/
! 792: .SH "SUPPORT"
! 793: .IX Header "SUPPORT"
! 794: Limited free support is available via the sudo-users mailing list,
! 795: see http://www.sudo.ws/mailman/listinfo/sudo\-users to subscribe or
! 796: search the archives.
! 797: .SH "DISCLAIMER"
! 798: .IX Header "DISCLAIMER"
! 799: \&\fBsudo\fR is provided ``\s-1AS\s0 \s-1IS\s0'' and any express or implied warranties,
! 800: including, but not limited to, the implied warranties of merchantability
! 801: and fitness for a particular purpose are disclaimed. See the \s-1LICENSE\s0
! 802: file distributed with \fBsudo\fR or http://www.sudo.ws/sudo/license.html
! 803: for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sudo.man.in CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sudo / doc