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