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