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