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