Annotation of embedaddon/sudo/doc/sudo.man.in, revision 1.1.1.5
1.1.1.3 misho 1: .\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!
2: .\" IT IS GENERATED AUTOMATICALLY FROM sudo.mdoc.in
3: .\"
1.1.1.4 misho 4: .\" Copyright (c) 1994-1996, 1998-2005, 2007-2013
1.1.1.3 misho 5: .\" Todd C. Miller <Todd.Miller@courtesan.com>
6: .\"
1.1 misho 7: .\" Permission to use, copy, modify, and distribute this software for any
8: .\" purpose with or without fee is hereby granted, provided that the above
9: .\" copyright notice and this permission notice appear in all copies.
1.1.1.3 misho 10: .\"
1.1 misho 11: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.1.1.3 misho 19: .\"
1.1 misho 20: .\" Sponsored in part by the Defense Advanced Research Projects
21: .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
22: .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
23: .\"
1.1.1.5 ! misho 24: .TH "SUDO" "@mansectsu@" "August 14, 2013" "Sudo @PACKAGE_VERSION@" "System Manager's Manual"
1.1 misho 25: .nh
1.1.1.3 misho 26: .if n .ad l
1.1 misho 27: .SH "NAME"
1.1.1.3 misho 28: \fBsudo\fR,
29: \fBsudoedit\fR
30: \- execute a command as another user
1.1 misho 31: .SH "SYNOPSIS"
1.1.1.3 misho 32: .HP 5n
33: \fBsudo\fR
34: \fB\-h\fR | \fB\-K\fR | \fB\-k\fR | \fB\-V\fR
35: .PD 0
36: .HP 5n
37: \fBsudo\fR
38: \fB\-v\fR
39: [\fB\-AknS\fR]
1.1.1.5 ! misho 40: [\fB\-a\fR\ \fItype\fR]
! 41: [\fB\-g\fR\ \fIgroup\fR]
! 42: [\fB\-h\fR\ \fIhost\fR]
1.1.1.3 misho 43: [\fB\-p\fR\ \fIprompt\fR]
1.1.1.5 ! misho 44: [\fB\-u\fR\ \fIuser\fR]
1.1.1.3 misho 45: .br
46: .HP 5n
47: \fBsudo\fR
1.1.1.5 ! misho 48: \fB\-l\fR
1.1.1.3 misho 49: [\fB\-AknS\fR]
1.1.1.5 ! misho 50: [\fB\-a\fR\ \fItype\fR]
! 51: [\fB\-g\fR\ \fIgroup\fR]
! 52: [\fB\-h\fR\ \fIhost\fR]
1.1.1.3 misho 53: [\fB\-p\fR\ \fIprompt\fR]
1.1.1.5 ! misho 54: [\fB\-U\fR\ \fIuser\fR]
! 55: [\fB\-u\fR\ \fIuser\fR]
1.1.1.3 misho 56: [\fIcommand\fR]
57: .br
58: .HP 5n
59: \fBsudo\fR
60: [\fB\-AbEHnPS\fR]
1.1.1.5 ! misho 61: [\fB\-a\fR\ \fItype\fR]
! 62: [\fB\-C\fR\ \fInum\fR]
! 63: [\fB\-c\fR\ \fIclass\fR]
! 64: [\fB\-g\fR\ \fIgroup\fR]
! 65: [\fB\-h\fR\ \fIhost\fR]
1.1.1.3 misho 66: [\fB\-p\fR\ \fIprompt\fR]
67: [\fB\-r\fR\ \fIrole\fR]
68: [\fB\-t\fR\ \fItype\fR]
1.1.1.5 ! misho 69: [\fB\-u\fR\ \fIuser\fR]
1.1.1.3 misho 70: [\fBVAR\fR=\fIvalue\fR]
1.1.1.5 ! misho 71: [\fB\-i\fR\ |\ \fB\-s\fR]
1.1.1.3 misho 72: [\fIcommand\fR]
73: .br
74: .HP 9n
75: \fBsudoedit\fR
1.1.1.5 ! misho 76: [\fB\-AknS\fR]
! 77: [\fB\-a\fR\ \fItype\fR]
! 78: [\fB\-C\fR\ \fInum\fR]
! 79: [\fB\-c\fR\ \fIclass\fR]
! 80: [\fB\-g\fR\ \fIgroup\fR]
! 81: [\fB\-h\fR\ \fIhost\fR]
1.1.1.3 misho 82: [\fB\-p\fR\ \fIprompt\fR]
1.1.1.5 ! misho 83: [\fB\-u\fR\ \fIuser\fR]
1.1.1.3 misho 84: file ...
85: .PD
1.1 misho 86: .SH "DESCRIPTION"
1.1.1.3 misho 87: \fBsudo\fR
88: allows a permitted user to execute a
89: \fIcommand\fR
90: as the superuser or another user, as specified by the security
91: policy.
92: .PP
93: \fBsudo\fR
94: supports a plugin architecture for security policies and input/output
95: logging.
96: Third parties can develop and distribute their own policy and I/O
97: logging plugins to work seamlessly with the
98: \fBsudo\fR
99: front end.
100: The default security policy is
101: \fIsudoers\fR,
102: which is configured via the file
103: \fI@sysconfdir@/sudoers\fR,
104: or via LDAP.
105: See the
1.1.1.4 misho 106: \fIPlugins\fR
1.1.1.3 misho 107: section for more information.
1.1 misho 108: .PP
109: The security policy determines what privileges, if any, a user has
1.1.1.3 misho 110: to run
111: \fBsudo\fR.
112: The policy may require that users authenticate themselves with a
113: password or another authentication mechanism.
114: If authentication is required,
115: \fBsudo\fR
116: will exit if the user's password is not entered within a configurable
117: time limit.
118: This limit is policy-specific; the default password prompt timeout
119: for the
120: \fIsudoers\fR
121: security policy is
122: \fR@password_timeout@\fR
123: minutes.
1.1 misho 124: .PP
125: Security policies may support credential caching to allow the user
1.1.1.3 misho 126: to run
127: \fBsudo\fR
128: again for a period of time without requiring authentication.
129: The
130: \fIsudoers\fR
131: policy caches credentials for
132: \fR@timeout@\fR
133: minutes, unless overridden in
134: sudoers(@mansectform@).
135: By running
136: \fBsudo\fR
137: with the
138: \fB\-v\fR
139: option, a user can update the cached credentials without running a
140: \fIcommand\fR.
141: .PP
142: When invoked as
143: \fBsudoedit\fR,
144: the
145: \fB\-e\fR
146: option (described below), is implied.
1.1 misho 147: .PP
148: Security policies may log successful and failed attempts to use
1.1.1.3 misho 149: \fBsudo\fR.
150: If an I/O plugin is configured, the running command's input and
151: output may be logged as well.
152: .PP
153: The options are as follows:
154: .TP 12n
1.1.1.5 ! misho 155: \fB\-A\fR, \fB\--askpass\fR
1.1.1.3 misho 156: Normally, if
157: \fBsudo\fR
158: requires a password, it will read it from the user's terminal.
159: If the
160: \fB\-A\fR (\fIaskpass\fR)
161: option is specified, a (possibly graphical) helper program is
162: executed to read the user's password and output the password to the
163: standard output.
164: If the
165: \fRSUDO_ASKPASS\fR
166: environment variable is set, it specifies the path to the helper
167: program.
168: Otherwise, if
1.1.1.4 misho 169: sudo.conf(@mansectform@)
1.1 misho 170: contains a line specifying the askpass program, that value will be
1.1.1.3 misho 171: used.
172: For example:
173: .RS
174: .nf
175: .sp
176: .RS 4n
177: # Path to askpass helper program
178: Path askpass /usr/X11R6/bin/ssh-askpass
179: .RE
180: .fi
181: .sp
182: If no askpass program is available,
183: \fBsudo\fR
184: will exit with an error.
185: .PP
186: .RE
187: .PD 0
188: .TP 12n
1.1.1.5 ! misho 189: \fB\-a\fR \fItype\fR, \fB\--auth-type\fR=\fItype\fR
! 190: Use the specified BSD authentication
! 191: \fItype\fR
! 192: when validating the user, if allowed by
1.1.1.3 misho 193: \fI/etc/login.conf\fR.
194: The system administrator may specify a list of sudo-specific
195: authentication methods by adding an
196: ``auth-sudo''
197: entry in
198: \fI/etc/login.conf\fR.
199: This option is only available on systems that support BSD authentication.
200: .PD
201: .TP 12n
1.1.1.5 ! misho 202: \fB\-b\fR, \fB\--background\fR
! 203: Run the given command in the background.
! 204: Note that it is not possible to use shell job control to manipulate
! 205: background processes started by
! 206: \fBsudo\fR.
1.1 misho 207: Most interactive commands will fail to work properly in background
208: mode.
1.1.1.3 misho 209: .TP 12n
1.1.1.5 ! misho 210: \fB\-C\fR \fInum\fR, \fB\--close-from\fR=\fInum\fR
! 211: Close all file descriptors greater than or equal to
! 212: \fInum\fR
! 213: before executing a command.
! 214: Values less than three are not permitted.
! 215: By default,
1.1.1.3 misho 216: \fBsudo\fR
217: will close all open file descriptors other than standard input,
1.1.1.5 ! misho 218: standard output and standard error when executing a command.
! 219: The security policy may restrict the user's ability to use this option.
1.1.1.3 misho 220: The
221: \fIsudoers\fR
222: policy only permits use of the
223: \fB\-C\fR
224: option when the administrator has enabled the
225: \fIclosefrom_override\fR
226: option.
227: .TP 12n
1.1.1.5 ! misho 228: \fB\-c\fR \fIclass\fR, \fB\--login-class\fR=\fIclass\fR
! 229: Run the command with resource limits and scheduling priority of
! 230: the specified login
! 231: \fIclass\fR.
1.1.1.3 misho 232: The
233: \fIclass\fR
234: argument can be either a class name as defined in
235: \fI/etc/login.conf\fR,
236: or a single
237: `\-'
238: character.
1.1.1.5 ! misho 239: If
1.1.1.3 misho 240: \fIclass\fR
1.1.1.5 ! misho 241: is
! 242: \fR-\fR,
! 243: the default login class of the target user will be used.
! 244: Otherwise, the command must be run as root, or
! 245: \fBsudo\fR
! 246: must be run from a shell that is already root.
! 247: If the command is being run as a login shell, additional
! 248: \fI/etc/login.conf\fR
! 249: settings, such as the umask and environment variables, will
! 250: be applied if present.
1.1.1.3 misho 251: This option is only available on systems with BSD login classes.
252: .TP 12n
1.1.1.5 ! misho 253: \fB\-E\fR, \fB\--preserve-env\fR
! 254: Indicates to the security policy that the user wishes to
1.1.1.3 misho 255: preserve their existing environment variables.
1.1.1.5 ! misho 256: The security policy may return an error if the user does not have
! 257: permission to preserve the environment.
1.1.1.3 misho 258: .TP 12n
1.1.1.5 ! misho 259: \fB\-e\fR, \fB\--edit\fR
! 260: Edit one or more files instead of running a command.
! 261: In lieu of a path name, the string "sudoedit" is used when consulting
1.1.1.3 misho 262: the security policy.
263: If the user is authorized by the policy, the following steps are
264: taken:
265: .RS
266: .TP 5n
267: 1.
1.1 misho 268: Temporary copies are made of the files to be edited with the owner
269: set to the invoking user.
1.1.1.3 misho 270: .TP 5n
271: 2.
272: The editor specified by the policy is run to edit the temporary
273: files.
274: The
275: \fIsudoers\fR
276: policy uses the
277: \fRSUDO_EDITOR\fR,
278: \fRVISUAL\fR
279: and
280: \fREDITOR\fR
281: environment variables (in that order).
282: If none of
283: \fRSUDO_EDITOR\fR,
284: \fRVISUAL\fR
285: or
286: \fREDITOR\fR
287: are set, the first program listed in the
288: \fIeditor\fR
289: sudoers(@mansectform@)
290: option is used.
291: .TP 5n
292: 3.
1.1 misho 293: If they have been modified, the temporary files are copied back to
294: their original location and the temporary versions are removed.
1.1.1.3 misho 295: .PP
296: If the specified file does not exist, it will be created.
297: Note that unlike most commands run by
298: \fIsudo\fR,
299: the editor is run with the invoking user's environment unmodified.
300: If, for some reason,
301: \fBsudo\fR
302: is unable to update a file with its edited version, the user will
303: receive a warning and the edited copy will remain in a temporary
304: file.
305: .PP
1.1 misho 306: .RE
1.1.1.3 misho 307: .PD 0
308: .TP 12n
1.1.1.5 ! misho 309: \fB\-g\fR \fIgroup\fR, \fB\--group\fR=\fIgroup\fR
! 310: Run the command with the primary group set to
! 311: \fIgroup\fR
! 312: instead of the primary group specified by the target
! 313: user's password database entry.
1.1.1.3 misho 314: The
315: \fIgroup\fR
1.1.1.5 ! misho 316: may be either a group name or a numeric group ID
! 317: (GID)
! 318: prefixed with the
! 319: `#'
! 320: character (e.g.
! 321: \fR#0\fR
! 322: for GID 0).
! 323: When running a command as a GID, many shells require that the
1.1.1.3 misho 324: `#'
325: be escaped with a backslash
326: (`\e').
327: If no
328: \fB\-u\fR
1.1.1.5 ! misho 329: option is specified, the command will be run as the invoking user.
1.1.1.3 misho 330: In either case, the primary group will be set to
331: \fIgroup\fR.
332: .PD
333: .TP 12n
1.1.1.5 ! misho 334: \fB\-H\fR, \fB\--set-home\fR
! 335: Request that the security policy set the
1.1.1.3 misho 336: \fRHOME\fR
1.1.1.5 ! misho 337: environment variable to the home directory specified by the target
! 338: user's password database entry.
1.1 misho 339: Depending on the policy, this may be the default behavior.
1.1.1.3 misho 340: .TP 12n
1.1.1.5 ! misho 341: \fB\-h\fR, \fB\--help\fR
! 342: Display a short help message to the standard output and exit.
1.1.1.3 misho 343: .TP 12n
1.1.1.5 ! misho 344: \fB\-h\fR \fIhost\fR, \fB\--host\fR=\fIhost\fR
! 345: Run the command on the specified
! 346: \fIhost\fR
! 347: if the security policy plugin supports remote commands.
! 348: Note that the
! 349: \fIsudoers\fR
! 350: plugin does not currently support running remote commands.
! 351: This may also be used in conjunction with the
! 352: \fB\-l\fR
! 353: option to list a user's privileges for the remote host.
! 354: .TP 12n
! 355: \fB\-i\fR, \fB\--login\fR
! 356: Run the shell specified by the target user's password database entry
! 357: as a login shell.
1.1.1.3 misho 358: This means that login-specific resource files such as
359: \fI.profile\fR
360: or
361: \fI.login\fR
362: will be read by the shell.
363: If a command is specified, it is passed to the shell for execution
364: via the shell's
365: \fB\-c\fR
366: option.
1.1 misho 367: If no command is specified, an interactive shell is executed.
1.1.1.3 misho 368: \fBsudo\fR
369: attempts to change to that user's home directory before running the
370: shell.
1.1.1.5 ! misho 371: The command is run with an environment similar to the one
! 372: a user would receive at log in.
1.1.1.3 misho 373: The
374: \fICommand Environment\fR
375: section in the
376: sudoers(@mansectform@)
377: manual documents how the
378: \fB\-i\fR
379: option affects the environment in which a command is run when the
380: \fIsudoers\fR
381: policy is in use.
382: .TP 12n
1.1.1.5 ! misho 383: \fB\-K\fR, \fB\--remove-timestamp\fR
! 384: Similar to the
1.1.1.3 misho 385: \fB\-k\fR
1.1.1.5 ! misho 386: option, except that it removes the user's cached credentials entirely
! 387: and may not be used in conjunction with a command or other option.
1.1.1.3 misho 388: This option does not require a password.
389: Not all security policies support credential caching.
390: .TP 12n
1.1.1.5 ! misho 391: \fB\-k\fR, \fB\--reset-timestamp\fR
! 392: When used without a command, invalidates the user's cached credentials.
! 393: In other words, the next time
1.1.1.3 misho 394: \fBsudo\fR
395: is run a password will be required.
396: This option does not require a password and was added to allow a
397: user to revoke
398: \fBsudo\fR
399: permissions from a
400: \fI.logout\fR
401: file.
402: .sp
1.1 misho 403: When used in conjunction with a command or an option that may require
1.1.1.5 ! misho 404: a password, this option will cause
1.1.1.3 misho 405: \fBsudo\fR
406: to ignore the user's cached credentials.
407: As a result,
408: \fBsudo\fR
409: will prompt for a password (if one is required by the security
410: policy) and will not update the user's cached credentials.
1.1.1.5 ! misho 411: .sp
! 412: Not all security policies support credential caching.
1.1.1.3 misho 413: .TP 12n
1.1.1.5 ! misho 414: \fB\-l\fR, \fB\--list\fR
1.1.1.3 misho 415: If no
416: \fIcommand\fR
1.1.1.5 ! misho 417: is specified,
! 418: list the allowed (and forbidden) commands for the
1.1.1.3 misho 419: invoking user (or the user specified by the
420: \fB\-U\fR
421: option) on the current host.
1.1.1.5 ! misho 422: A longer list format is used if this option is specified multiple times
! 423: and the security policy supports a verbose output format.
! 424: .sp
1.1.1.3 misho 425: If a
426: \fIcommand\fR
427: is specified and is permitted by the security policy, the fully-qualified
428: path to the command is displayed along with any command line
429: arguments.
430: If
431: \fIcommand\fR
432: is specified but not allowed,
433: \fBsudo\fR
434: will exit with a status value of 1.
435: .TP 12n
1.1.1.5 ! misho 436: \fB\-n\fR, \fB\--non-interactive\fR
! 437: Avoid prompting the user for input of any kind.
1.1.1.3 misho 438: If a password is required for the command to run,
439: \fBsudo\fR
440: will display an error message and exit.
441: .TP 12n
1.1.1.5 ! misho 442: \fB\-P\fR, \fB\--preserve-groups\fR
! 443: Preserve the invoking user's group vector unaltered.
1.1.1.3 misho 444: By default, the
445: \fIsudoers\fR
446: policy will initialize the group vector to the list of groups the
1.1.1.5 ! misho 447: target user is a member of.
1.1.1.3 misho 448: The real and effective group IDs, however, are still set to match
449: the target user.
450: .TP 12n
1.1.1.5 ! misho 451: \fB\-p\fR \fIprompt\fR, \fB\--prompt\fR=\fIprompt\fR
! 452: Use a custom password prompt with optional escape sequences.
1.1.1.3 misho 453: The following percent
454: (`%')
1.1.1.5 ! misho 455: escape sequences are supported by the
1.1.1.3 misho 456: \fIsudoers\fR
457: policy:
458: .RS
459: .TP 4n
460: \fR%H\fR
461: expanded to the host name including the domain name (on if the
462: machine's host name is fully qualified or the
463: \fIfqdn\fR
464: option is set in
465: sudoers(@mansectform@))
466: .TP 4n
467: \fR%h\fR
1.1 misho 468: expanded to the local host name without the domain name
1.1.1.3 misho 469: .TP 4n
470: \fR%p\fR
1.1 misho 471: expanded to the name of the user whose password is being requested
1.1.1.3 misho 472: (respects the
473: \fIrootpw\fR,
474: \fItargetpw\fR,
475: and
476: \fIrunaspw\fR
477: flags in
478: sudoers(@mansectform@))
479: .TP 4n
480: \fR\&%U\fR
1.1 misho 481: expanded to the login name of the user the command will be run as
1.1.1.3 misho 482: (defaults to root unless the
483: \fB\-u\fR
484: option is also specified)
485: .TP 4n
486: \fR%u\fR
1.1 misho 487: expanded to the invoking user's login name
1.1.1.3 misho 488: .TP 4n
489: \fR%%\fR
490: two consecutive
491: `%'
492: characters are collapsed into a single
493: `%'
494: character
495: .PP
1.1.1.5 ! misho 496: The custom prompt will override the system password prompt on systems that
1.1.1.3 misho 497: support PAM unless the
498: \fIpassprompt_override\fR
499: flag is disabled in
500: \fIsudoers\fR.
501: .PP
502: .RE
503: .PD 0
504: .TP 12n
1.1.1.5 ! misho 505: \fB\-r\fR \fIrole\fR, \fB\--role\fR=\fIrole\fR
! 506: Run the command with an SELinux security context that includes
! 507: the specified
1.1.1.3 misho 508: \fIrole\fR.
509: .PD
510: .TP 12n
1.1.1.5 ! misho 511: \fB\-S\fR, \fB\--stdin\fR
! 512: Write the prompt to the standard error and read the password from the
! 513: standard input instead of using the terminal device.
1.1.1.3 misho 514: The password must be followed by a newline character.
515: .TP 12n
1.1.1.5 ! misho 516: \fB\-s\fR, \fB\--shell\fR
! 517: Run the shell specified by the
1.1.1.3 misho 518: \fRSHELL\fR
1.1.1.5 ! misho 519: environment variable if it is set or the shell specified by the
! 520: invoking user's password database entry.
1.1.1.3 misho 521: If a command is specified, it is passed to the shell for execution
522: via the shell's
523: \fB\-c\fR
524: option.
525: If no command is specified, an interactive shell is executed.
526: .TP 12n
1.1.1.5 ! misho 527: \fB\-t\fR \fItype\fR, \fB\--type\fR=\fItype\fR
! 528: Run the command with an SELinux security context that includes
! 529: the specified
1.1.1.3 misho 530: \fItype\fR.
1.1.1.5 ! misho 531: If no
! 532: \fItype\fR
! 533: is specified, the default type is derived from the role.
1.1.1.3 misho 534: .TP 12n
1.1.1.5 ! misho 535: \fB\-U\fR \fIuser\fR, \fB\--other-user\fR=\fIuser\fR
! 536: Used in conjunction with the
1.1.1.3 misho 537: \fB\-l\fR
1.1.1.5 ! misho 538: option to list the privileges for
! 539: \fIuser\fR
! 540: instead of for the invoking user.
1.1 misho 541: The security policy may restrict listing other users' privileges.
1.1.1.3 misho 542: The
543: \fIsudoers\fR
544: policy only allows root or a user with the
545: \fRALL\fR
1.1 misho 546: privilege on the current host to use this option.
1.1.1.3 misho 547: .TP 12n
1.1.1.5 ! misho 548: \fB\-u\fR \fIuser\fR, \fB\--user\fR=\fIuser\fR
! 549: Run the command as a user other than the default target user
! 550: (usually
! 551: \fIroot ).\fR
! 552: The
! 553: \fIuser\fR
! 554: may be either a user name or a numeric user ID
! 555: (UID)
! 556: prefixed with the
! 557: `#'
! 558: character (e.g.
! 559: \fR#0\fR
! 560: for UID 0).
! 561: When running commands as a UID, many shells require that the
1.1.1.3 misho 562: `#'
563: be escaped with a backslash
564: (`\e').
1.1.1.5 ! misho 565: Some security policies may restrict UIDs
1.1.1.3 misho 566: to those listed in the password database.
567: The
568: \fIsudoers\fR
1.1.1.5 ! misho 569: policy allows UIDs that are not in the password database as long as the
1.1.1.3 misho 570: \fItargetpw\fR
571: option is not set.
572: Other security policies may not support this.
573: .TP 12n
1.1.1.5 ! misho 574: \fB\-V\fR, \fB\--version\fR
! 575: Print the
1.1.1.3 misho 576: \fBsudo\fR
1.1.1.5 ! misho 577: version string as well as the version string of the security
1.1.1.3 misho 578: policy plugin and any I/O plugins.
579: If the invoking user is already root the
580: \fB\-V\fR
581: option will display the arguments passed to configure when
582: \fBsudo\fR
583: was built and plugins may display more verbose information such as
1.1 misho 584: default options.
1.1.1.3 misho 585: .TP 12n
1.1.1.5 ! misho 586: \fB\-v\fR, \fB\--validate\fR
! 587: Update the user's cached credentials, authenticating the user
! 588: if necessary.
1.1.1.3 misho 589: For the
590: \fIsudoers\fR
591: plugin, this extends the
592: \fBsudo\fR
593: timeout for another
594: \fR@timeout@\fR
1.1.1.5 ! misho 595: minutes by default, but does not run a command.
1.1.1.3 misho 596: Not all security policies support cached credentials.
597: .TP 12n
598: \fB\--\fR
599: The
600: \fB\--\fR
601: option indicates that
602: \fBsudo\fR
603: should stop processing command line arguments.
1.1 misho 604: .PP
605: Environment variables to be set for the command may also be passed
1.1.1.3 misho 606: on the command line in the form of
607: \fBVAR\fR=\fIvalue\fR,
608: e.g.\&
609: \fBLD_LIBRARY_PATH\fR=\fI/usr/local/pkg/lib\fR.
1.1.1.5 ! misho 610: Variables passed on the command line are subject to restrictions
! 611: imposed by the security policy plugin.
! 612: The
! 613: \fIsudoers\fR
! 614: policy subjects variables passed on the command line to the same
1.1.1.3 misho 615: restrictions as normal environment variables with one important
616: exception.
617: If the
618: \fIsetenv\fR
619: option is set in
620: \fIsudoers\fR,
621: the command to be run has the
622: \fRSETENV\fR
623: tag set or the command matched is
624: \fRALL\fR,
625: the user may set variables that would otherwise be forbidden.
626: See
627: sudoers(@mansectform@)
628: for more information.
629: .SH "COMMAND EXECUTION"
630: When
631: \fBsudo\fR
632: executes a command, the security policy specifies the execution
1.1.1.4 misho 633: environment for the command.
1.1.1.5 ! misho 634: Typically, the real and effective user and group and IDs are set to
1.1.1.3 misho 635: match those of the target user, as specified in the password database,
636: and the group vector is initialized based on the group database
637: (unless the
638: \fB\-P\fR
639: option was specified).
640: .PP
641: The following parameters may be specified by security policy:
642: .TP 4n
643: \fBo\fR
644: real and effective user ID
645: .TP 4n
646: \fBo\fR
647: real and effective group ID
648: .TP 4n
649: \fBo\fR
650: supplementary group IDs
651: .TP 4n
652: \fBo\fR
653: the environment list
654: .TP 4n
655: \fBo\fR
656: current working directory
657: .TP 4n
658: \fBo\fR
659: file creation mode mask (umask)
660: .TP 4n
661: \fBo\fR
662: SELinux role and type
663: .TP 4n
664: \fBo\fR
665: Solaris project
666: .TP 4n
667: \fBo\fR
668: Solaris privileges
669: .TP 4n
670: \fBo\fR
671: BSD login class
672: .TP 4n
673: \fBo\fR
674: scheduling priority (aka nice value)
675: .SS "Process model"
676: When
677: \fBsudo\fR
678: runs a command, it calls
679: fork(2),
680: sets up the execution environment as described above, and calls the
681: execve
682: system call in the child process.
683: The main
684: \fBsudo\fR
685: process waits until the command has completed, then passes the
1.1.1.4 misho 686: command's exit status to the security policy's close function and exits.
687: If an I/O logging plugin is configured or if the security policy
688: explicitly requests it, a new pseudo-terminal
1.1.1.3 misho 689: (``pty'')
690: is created and a second
691: \fBsudo\fR
692: process is used to relay job control signals between the user's
693: existing pty and the new pty the command is being run in.
694: This extra process makes it possible to, for example, suspend
695: and resume the command.
696: Without it, the command would be in what POSIX terms an
697: ``orphaned process group''
698: and it would not receive any job control signals.
1.1.1.4 misho 699: As a special case, if the policy plugin does not define a close
700: function and no pty is required,
701: \fBsudo\fR
702: will execute the command directly instead of calling
703: fork(2)
704: first.
1.1.1.5 ! misho 705: The
! 706: \fIsudoers\fR
! 707: policy plugin will only define a close function when I/O logging
! 708: is enabled, a pty is required, or the
! 709: \fIpam_session\fR
! 710: or
! 711: \fIpam_setcred\fR
! 712: options are enabled.
! 713: Note that
! 714: \fIpam_session\fR
! 715: and
! 716: \fIpam_setcred\fR
! 717: are enabled by default on systems using PAM.
1.1.1.3 misho 718: .SS "Signal handling"
1.1.1.5 ! misho 719: When the command is run as a child of the
1.1.1.3 misho 720: \fBsudo\fR
721: process,
722: \fBsudo\fR
723: will relay signals it receives to the command.
724: Unless the command is being run in a new pty, the
725: \fRSIGHUP\fR,
726: \fRSIGINT\fR
727: and
728: \fRSIGQUIT\fR
729: signals are not relayed unless they are sent by a user process,
730: not the kernel.
731: Otherwise, the command would receive
732: \fRSIGINT\fR
733: twice every time the user entered control-C.
734: Some signals, such as
735: \fRSIGSTOP\fR
736: and
737: \fRSIGKILL\fR,
738: cannot be caught and thus will not be relayed to the command.
739: As a general rule,
740: \fRSIGTSTP\fR
741: should be used instead of
742: \fRSIGSTOP\fR
743: when you wish to suspend a command being run by
744: \fBsudo\fR.
745: .PP
746: As a special case,
747: \fBsudo\fR
748: will not relay signals that were sent by the command it is running.
749: This prevents the command from accidentally killing itself.
750: On some systems, the
751: reboot(@mansectsu@)
752: command sends
753: \fRSIGTERM\fR
754: to all non-system processes other than itself before rebooting
1.1.1.4 misho 755: the system.
1.1.1.3 misho 756: This prevents
757: \fBsudo\fR
758: from relaying the
759: \fRSIGTERM\fR
760: signal it received back to
761: reboot(@mansectsu@),
762: which might then exit before the system was actually rebooted,
763: leaving it in a half-dead state similar to single user mode.
764: Note, however, that this check only applies to the command run by
765: \fBsudo\fR
766: and not any other processes that the command may create.
767: As a result, running a script that calls
768: reboot(@mansectsu@)
769: or
770: shutdown(@mansectsu@)
771: via
772: \fBsudo\fR
773: may cause the system to end up in this undefined state unless the
774: reboot(@mansectsu@)
775: or
776: shutdown(@mansectsu@)
777: are run using the
778: \fBexec\fR()
779: family of functions instead of
780: \fBsystem\fR()
781: (which interposes a shell between the command and the calling process).
1.1.1.4 misho 782: .PP
783: If no I/O logging plugins are loaded and the policy plugin has not
784: defined a
785: \fBclose\fR()
786: function, set a command timeout or required that the command be
787: run in a new pty,
788: \fBsudo\fR
789: may execute the command directly instead of running it as a child process.
790: .SS "Plugins"
1.1 misho 791: Plugins are dynamically loaded based on the contents of the
1.1.1.4 misho 792: sudo.conf(@mansectform@)
1.1.1.3 misho 793: file.
794: If no
1.1.1.4 misho 795: sudo.conf(@mansectform@)
1.1.1.3 misho 796: file is present, or it contains no
797: \fRPlugin\fR
798: lines,
799: \fBsudo\fR
800: will use the traditional
801: \fIsudoers\fR
1.1.1.4 misho 802: security policy and I/O logging.
803: See the
804: sudo.conf(@mansectform@)
805: manual for details of the
1.1.1.3 misho 806: \fI@sysconfdir@/sudo.conf\fR
1.1.1.4 misho 807: file and the
1.1.1.3 misho 808: sudo_plugin(@mansectsu@)
1.1.1.4 misho 809: manual for more information about the
1.1.1.3 misho 810: \fBsudo\fR
1.1.1.4 misho 811: plugin architecture.
1.1.1.3 misho 812: .SH "EXIT VALUE"
813: Upon successful execution of a program, the exit status from
814: \fIsudo\fR
1.1 misho 815: will simply be the exit status of the program that was executed.
816: .PP
1.1.1.3 misho 817: Otherwise,
818: \fBsudo\fR
819: exits with a value of 1 if there is a configuration/permission
820: problem or if
821: \fBsudo\fR
822: cannot execute the given command.
823: In the latter case the error string is printed to the standard error.
824: If
825: \fBsudo\fR
826: cannot
827: stat(2)
828: one or more entries in the user's
829: \fRPATH\fR,
830: an error is printed on stderr.
831: (If the directory does not exist or if it is not really a directory,
832: the entry is ignored and no error is printed.)
833: This should not happen under normal circumstances.
834: The most common reason for
835: stat(2)
836: to return
837: ``permission denied''
838: is if you are running an automounter and one of the directories in
839: your
840: \fRPATH\fR
841: is on a machine that is currently unreachable.
1.1 misho 842: .SH "SECURITY NOTES"
1.1.1.3 misho 843: \fBsudo\fR
844: tries to be safe when executing external commands.
1.1 misho 845: .PP
1.1.1.3 misho 846: To prevent command spoofing,
847: \fBsudo\fR
848: checks "." and "" (both denoting current directory) last when
849: searching for a command in the user's
850: \fRPATH\fR
851: (if one or both are in the
852: \fRPATH\fR).
853: Note, however, that the actual
854: \fRPATH\fR
855: environment variable is
856: \fInot\fR
857: modified and is passed unchanged to the program that
858: \fBsudo\fR
859: executes.
860: .PP
861: Please note that
862: \fBsudo\fR
863: will normally only log the command it explicitly runs.
864: If a user runs a command such as
865: \fRsudo su\fR
866: or
867: \fRsudo sh\fR,
868: subsequent commands run from that shell are not subject to
869: \fBsudo\fR's
870: security policy.
871: The same is true for commands that offer shell escapes (including
872: most editors).
873: If I/O logging is enabled, subsequent commands will have their input and/or
874: output logged, but there will not be traditional logs for those commands.
875: Because of this, care must be taken when giving users access to commands via
876: \fBsudo\fR
877: to verify that the command does not inadvertently give the user an
878: effective root shell.
879: For more information, please see the
880: \fIPREVENTING SHELL ESCAPES\fR
881: section in
882: sudoers(@mansectform@).
1.1.1.2 misho 883: .PP
884: To prevent the disclosure of potentially sensitive information,
1.1.1.3 misho 885: \fBsudo\fR
886: disables core dumps by default while it is executing (they are
887: re-enabled for the command that is run).
888: To aid in debugging
889: \fBsudo\fR
890: crashes, you may wish to re-enable core dumps by setting
891: ``disable_coredump''
892: to false in the
1.1.1.4 misho 893: sudo.conf(@mansectform@)
1.1.1.3 misho 894: file as follows:
895: .nf
896: .sp
897: .RS 6n
898: Set disable_coredump false
899: .RE
900: .fi
1.1.1.2 misho 901: .PP
1.1.1.4 misho 902: See the
903: sudo.conf(@mansectform@)
904: manual for more information.
1.1 misho 905: .SH "ENVIRONMENT"
1.1.1.3 misho 906: \fBsudo\fR
907: utilizes the following environment variables.
908: The security policy has control over the actual content of the command's
909: environment.
910: .TP 17n
911: \fREDITOR\fR
912: Default editor to use in
913: \fB\-e\fR
914: (sudoedit) mode if neither
915: \fRSUDO_EDITOR\fR
916: nor
917: \fRVISUAL\fR
918: is set.
919: .TP 17n
920: \fRMAIL\fR
921: In
922: \fB\-i\fR
923: mode or when
924: \fIenv_reset\fR
925: is enabled in
926: \fIsudoers\fR,
927: set to the mail spool of the target user.
928: .TP 17n
929: \fRHOME\fR
930: Set to the home directory of the target user if
931: \fB\-i\fR
932: or
933: \fB\-H\fR
934: are specified,
935: \fIenv_reset\fR
936: or
937: \fIalways_set_home\fR
938: are set in
939: \fIsudoers\fR,
940: or when the
941: \fB\-s\fR
942: option is specified and
943: \fIset_home\fR
944: is set in
945: \fIsudoers\fR.
946: .TP 17n
947: \fRPATH\fR
1.1 misho 948: May be overridden by the security policy.
1.1.1.3 misho 949: .TP 17n
950: \fRSHELL\fR
951: Used to determine shell to run with
952: \fB\-s\fR
953: option.
954: .TP 17n
955: \fRSUDO_ASKPASS\fR
1.1 misho 956: Specifies the path to a helper program used to read the password
1.1.1.3 misho 957: if no terminal is available or if the
958: \fB\-A\fR
959: option is specified.
960: .TP 17n
961: \fRSUDO_COMMAND\fR
962: Set to the command run by sudo.
963: .TP 17n
964: \fRSUDO_EDITOR\fR
965: Default editor to use in
966: \fB\-e\fR
967: (sudoedit) mode.
968: .TP 17n
969: \fRSUDO_GID\fR
970: Set to the group ID of the user who invoked sudo.
971: .TP 17n
972: \fRSUDO_PROMPT\fR
973: Used as the default password prompt.
974: .TP 17n
975: \fRSUDO_PS1\fR
976: If set,
977: \fRPS1\fR
978: will be set to its value for the program being run.
979: .TP 17n
980: \fRSUDO_UID\fR
981: Set to the user ID of the user who invoked sudo.
982: .TP 17n
983: \fRSUDO_USER\fR
984: Set to the login name of the user who invoked sudo.
985: .TP 17n
986: \fRUSER\fR
987: Set to the target user (root unless the
988: \fB\-u\fR
989: option is specified).
990: .TP 17n
991: \fRVISUAL\fR
992: Default editor to use in
993: \fB\-e\fR
994: (sudoedit) mode if
995: \fRSUDO_EDITOR\fR
996: is not set.
1.1 misho 997: .SH "FILES"
1.1.1.3 misho 998: .TP 26n
999: \fI@sysconfdir@/sudo.conf\fR
1000: \fBsudo\fR
1001: front end configuration
1.1 misho 1002: .SH "EXAMPLES"
1.1.1.3 misho 1003: Note: the following examples assume a properly configured security
1004: policy.
1.1 misho 1005: .PP
1006: To get a file listing of an unreadable directory:
1.1.1.3 misho 1007: .nf
1008: .sp
1009: .RS 6n
1010: $ sudo ls /usr/local/protected
1011: .RE
1012: .fi
1.1 misho 1013: .PP
1.1.1.3 misho 1014: To list the home directory of user yaz on a machine where the file
1015: system holding ~yaz is not exported as root:
1016: .nf
1017: .sp
1018: .RS 6n
1019: $ sudo -u yaz ls ~yaz
1020: .RE
1021: .fi
1.1 misho 1022: .PP
1.1.1.3 misho 1023: To edit the
1024: \fIindex.html\fR
1025: file as user www:
1026: .nf
1027: .sp
1028: .RS 6n
1029: $ sudo -u www vi ~www/htdocs/index.html
1030: .RE
1031: .fi
1.1 misho 1032: .PP
1.1.1.3 misho 1033: To view system logs only accessible to root and users in the adm
1034: group:
1035: .nf
1036: .sp
1037: .RS 6n
1038: $ sudo -g adm view /var/log/syslog
1039: .RE
1040: .fi
1.1 misho 1041: .PP
1042: To run an editor as jim with a different primary group:
1.1.1.3 misho 1043: .nf
1044: .sp
1045: .RS 6n
1046: $ sudo -u jim -g audio vi ~jim/sound.txt
1047: .RE
1048: .fi
1049: .PP
1050: To shut down a machine:
1051: .nf
1052: .sp
1053: .RS 6n
1054: $ sudo shutdown -r +15 "quick reboot"
1055: .RE
1056: .fi
1.1 misho 1057: .PP
1.1.1.3 misho 1058: To make a usage listing of the directories in the /home partition.
1059: Note that this runs the commands in a sub-shell to make the
1060: \fRcd\fR
1061: and file redirection work.
1062: .nf
1063: .sp
1064: .RS 6n
1065: $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
1066: .RE
1067: .fi
1.1 misho 1068: .SH "SEE ALSO"
1.1.1.3 misho 1069: su(1),
1070: stat(2),
1071: login_cap(3),
1072: passwd(@mansectform@),
1.1.1.4 misho 1073: sudo.conf(@mansectform@),
1.1.1.3 misho 1074: sudoers(@mansectform@),
1075: sudo_plugin(@mansectsu@),
1076: sudoreplay(@mansectsu@),
1077: visudo(@mansectsu@)
1.1.1.2 misho 1078: .SH "HISTORY"
1.1.1.3 misho 1079: See the HISTORY file in the
1080: \fBsudo\fR
1081: distribution (http://www.sudo.ws/sudo/history.html) for a brief
1082: history of sudo.
1083: .SH "AUTHORS"
1084: Many people have worked on
1085: \fBsudo\fR
1086: over the years; this version consists of code written primarily by:
1087: .sp
1088: .RS 6n
1089: Todd C. Miller
1090: .RE
1091: .PP
1092: See the CONTRIBUTORS file in the
1093: \fBsudo\fR
1094: distribution (http://www.sudo.ws/sudo/contributors.html) for an
1095: exhaustive list of people who have contributed to
1096: \fBsudo\fR.
1.1 misho 1097: .SH "CAVEATS"
1098: There is no easy way to prevent a user from gaining a root shell
1.1.1.3 misho 1099: if that user is allowed to run arbitrary commands via
1100: \fBsudo\fR.
1.1 misho 1101: Also, many programs (such as editors) allow the user to run commands
1.1.1.3 misho 1102: via shell escapes, thus avoiding
1103: \fBsudo\fR's
1104: checks.
1105: However, on most systems it is possible to prevent shell escapes with the
1106: sudoers(@mansectform@)
1107: plugin's
1108: \fInoexec\fR
1109: functionality.
1110: .PP
1111: It is not meaningful to run the
1112: \fRcd\fR
1113: command directly via sudo, e.g.,
1114: .nf
1115: .sp
1116: .RS 6n
1117: $ sudo cd /usr/local/protected
1118: .RE
1119: .fi
1.1 misho 1120: .PP
1121: since when the command exits the parent process (your shell) will
1.1.1.3 misho 1122: still be the same.
1123: Please see the
1124: \fIEXAMPLES\fR
1125: section for more information.
1126: .PP
1127: Running shell scripts via
1128: \fBsudo\fR
1129: can expose the same kernel bugs that make setuid shell scripts
1130: unsafe on some operating systems (if your OS has a /dev/fd/ directory,
1131: setuid shell scripts are generally safe).
1.1 misho 1132: .SH "BUGS"
1.1.1.3 misho 1133: If you feel you have found a bug in
1134: \fBsudo\fR,
1135: please submit a bug report at http://www.sudo.ws/sudo/bugs/
1.1 misho 1136: .SH "SUPPORT"
1137: Limited free support is available via the sudo-users mailing list,
1.1.1.3 misho 1138: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1.1 misho 1139: search the archives.
1140: .SH "DISCLAIMER"
1.1.1.3 misho 1141: \fBsudo\fR
1142: is provided
1143: ``AS IS''
1144: and any express or implied warranties, including, but not limited
1145: to, the implied warranties of merchantability and fitness for a
1146: particular purpose are disclaimed.
1147: See the LICENSE file distributed with
1148: \fBsudo\fR
1149: or http://www.sudo.ws/sudo/license.html 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