Annotation of src/usr.bin/sudo/sudo.mdoc.in, Revision 1.5
1.1 millert 1: .\"
2: .\" Copyright (c) 1994-1996, 1998-2005, 2007-2012
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.4 millert 22: .Dd $Mdocdate: February 15 2014 $
1.1 millert 23: .Dt SUDO @mansectsu@
24: .Os
25: .Sh NAME
26: .Nm sudo ,
27: .Nm sudoedit
28: .Nd execute a command as another user
29: .Sh SYNOPSIS
30: .Nm sudo
1.5 ! schwarze 31: .Fl h | K | k | L | V
1.1 millert 32: .Nm sudo
33: .Fl v
34: .Op Fl AknS
35: .Op Fl a Ar auth_type
1.5 ! schwarze 36: .Op Fl g Ar group name | #gid
1.1 millert 37: .Op Fl p Ar prompt
1.5 ! schwarze 38: .Op Fl u Ar user name | #uid
1.1 millert 39: .Nm sudo
40: .Fl l Ns Op Ar l
41: .Op Fl AknS
42: .Op Fl a Ar auth_type
1.5 ! schwarze 43: .Op Fl g Ar group name | #gid
1.1 millert 44: .Op Fl p Ar prompt
45: .Op Fl U Ar user name
1.5 ! schwarze 46: .Op Fl u Ar user name | #uid
1.1 millert 47: .Op Ar command
48: .Nm sudo
49: .Op Fl AbEHnPS
50: .Op Fl a Ar auth_type
51: .Op Fl C Ar fd
1.5 ! schwarze 52: .Op Fl c Ar class | -
! 53: .Op Fl g Ar group name | #gid
1.1 millert 54: .Op Fl p Ar prompt
1.5 ! schwarze 55: .Op Fl u Ar user name | #uid
1.3 schwarze 56: .Op Ar VAR Ns = Ns Ar value
1.5 ! schwarze 57: .Fl i | s
1.1 millert 58: .Op Ar command
59: .Nm sudoedit
60: .Op Fl AnS
61: .Op Fl a Ar auth_type
62: .Op Fl C Ar fd
1.5 ! schwarze 63: .Op Fl c Ar class | -
! 64: .Op Fl g Ar group name | #gid
1.1 millert 65: .Op Fl p Ar prompt
1.5 ! schwarze 66: .Op Fl u Ar user name | #uid
! 67: .Ar
1.1 millert 68: .Sh DESCRIPTION
69: .Nm sudo
70: allows a permitted user to execute a
71: .Ar command
72: as the superuser or another user, as specified by the
73: .Em sudoers
74: file.
75: The real and effective uid and gid are set to match those of the
76: target user, as specified in the password database, and the group
77: vector is initialized based on the group database (unless the
78: .Fl P
79: option was specified).
80: See the
81: .Sx Command Environment
82: section below for more details.
83: .Pp
84: .Nm sudo
85: determines who is an authorized user by consulting the file
86: .Pa @sysconfdir@/sudoers .
87: By running
88: .Nm sudo
89: with the
90: .Fl v
91: option, a user can update the time stamp without running a
92: .Ar command .
93: If authentication is required,
94: .Nm sudo
95: will exit if the user's password is not entered within a configurable
96: time limit.
97: The default password prompt timeout is
98: .Li @password_timeout@
99: minutes.
100: .Pp
101: When invoked as
102: .Nm sudoedit ,
103: the
104: .Fl e
105: option (described below), is implied.
106: .Pp
107: The options are as follows:
108: .Bl -tag -width Fl
109: .It Fl A
110: Normally, if
111: .Nm sudo
112: requires a password, it will read it from the user's terminal.
113: If the
1.5 ! schwarze 114: .Fl A Pq Em askpass
1.1 millert 115: option is specified, a (possibly graphical) helper program is
116: executed to read the user's password and output the password to the
117: standard output.
118: If the
119: .Ev SUDO_ASKPASS
120: environment variable is set, it specifies the path to the helper
121: program.
122: Otherwise, the value specified by the
123: .Em askpass
124: option in
125: .Xr sudoers @mansectform@
126: is used.
127: If no askpass program is available,
128: .Nm sudo
129: will exit with an error.
130: .It Fl a Ar type
131: The
1.5 ! schwarze 132: .Fl a Pq Em authentication type
1.1 millert 133: option causes
134: .Nm sudo
135: to use the specified authentication type when validating the user,
136: as allowed by
137: .Pa /etc/login.conf .
138: The system administrator may specify a list of sudo-specific
139: authentication methods by adding an
140: .Dq auth-sudo
141: entry in
142: .Pa /etc/login.conf .
143: This option is only available on systems that support BSD authentication.
144: .It Fl b
145: The
1.5 ! schwarze 146: .Fl b Pq Em background
1.1 millert 147: option tells
148: .Nm sudo
149: to run the given command in the background.
150: Note that if you use the
151: .Fl b
152: option you cannot use shell job control to manipulate the process.
153: Most interactive commands will fail to work properly in background
154: mode.
155: .It Fl C Ar fd
156: Normally,
157: .Nm sudo
158: will close all open file descriptors other than standard input,
159: standard output and standard error.
160: The
1.5 ! schwarze 161: .Fl C Pq Em close from
1.1 millert 162: option allows the user to specify a starting point above the standard
163: error (file descriptor three).
164: Values less than three are not permitted.
165: This option is only available when the administrator has enabled the
166: .Em closefrom_override
167: option in
168: .Xr sudoers @mansectform@ .
169: .It Fl c Ar class
170: The
1.5 ! schwarze 171: .Fl c Pq Em class
1.1 millert 172: option causes
173: .Nm sudo
1.2 millert 174: to run the command with resource limits and scheduling priority of
175: the specified login
176: .Ar class .
1.1 millert 177: The
1.5 ! schwarze 178: .Ar class
1.1 millert 179: argument can be either a class name as defined in
180: .Pa /etc/login.conf ,
181: or a single
182: .Ql \-
183: character.
1.2 millert 184: If
1.1 millert 185: .Ar class
1.2 millert 186: is
187: .Li - ,
188: the default login class of the target user will be used.
189: Otherwise, the command must be run as the superuser (user ID 0), or
190: .Nm sudo
191: must be run from a shell that is already running as the superuser.
192: If the command is being run as a login shell, additional
193: .Pa /etc/login.conf
194: settings, such as the umask and environment variables, will
195: be applied, if present.
1.1 millert 196: This option is only available on systems with BSD login classes.
197: .It Fl E
198: The
1.5 ! schwarze 199: .Fl E Pq Em preserve environment
1.1 millert 200: option will override the
201: .Em env_reset
202: option in
203: .Xr sudoers @mansectform@ .
204: It is only available when either the matching command has the
205: .Li SETENV
206: tag or the
207: .Em setenv
208: option is set in
209: .Xr sudoers @mansectform@ .
210: .Nm sudo
211: will return an error if the
212: .Fl E
213: option is specified and the user does not have permission to preserve
214: the environment.
215: .It Fl e
216: The
1.5 ! schwarze 217: .Fl e Pq Em edit
1.1 millert 218: option indicates that, instead of running a command, the user wishes
219: to edit one or more files.
220: In lieu of a command, the string "sudoedit" is used when consulting the
221: .Em sudoers
222: file.
223: If the user is authorized by
224: .Em sudoers ,
225: the following steps are taken:
226: .Bl -enum -offset 4
227: .It
228: Temporary copies are made of the files to be edited with the owner
229: set to the invoking user.
230: .It
231: The editor specified by the
232: .Ev SUDO_EDITOR ,
233: .Ev VISUAL
234: or
235: .Ev EDITOR
236: environment variables (in that order) is run to edit the temporary files.
237: If none of
238: .Ev SUDO_EDITOR ,
239: .Ev VISUAL
240: or
241: .Ev EDITOR
242: are set, the first program listed in the
243: .Em editor
244: .Xr sudoers @mansectform@
245: option is used.
246: .It
247: If they have been modified, the temporary files are copied back to
248: their original location and the temporary versions are removed.
249: .El
250: .Pp
251: If the specified file does not exist, it will be created.
252: Note that unlike most commands run by
253: .Em sudo ,
254: the editor is run with the invoking user's environment unmodified.
255: If, for some reason,
256: .Nm sudo
257: is unable to update a file with its edited version, the user will
258: receive a warning and the edited copy will remain in a temporary
259: file.
260: .It Fl g Ar group
261: Normally,
262: .Nm sudo
263: runs a command with the primary group set to the one specified by
264: the password database for the user the command is being run as (by
265: default, root).
266: The
1.5 ! schwarze 267: .Fl g Pq Em group
1.1 millert 268: option causes
269: .Nm sudo
270: to run the command with the primary group set to
271: .Ar group
272: instead.
1.5 ! schwarze 273: To specify a gid instead of a group name, use
! 274: .Ar #gid .
1.1 millert 275: When running commands as a
276: .Em gid ,
277: many shells require that the
278: .Ql #
279: be escaped with a backslash
280: .Pq Ql \e .
281: If no
282: .Fl u
283: option is specified, the command will be run as the invoking user
284: (not root).
285: In either case, the primary group will be set to
286: .Em group .
287: .It Fl H
288: The
1.5 ! schwarze 289: .Fl H Pq Em HOME
1.1 millert 290: option option sets the
291: .Ev HOME
292: environment variable to the home directory of the target user (root
293: by default) as specified by the password database.
294: The default handling of the
295: .Ev HOME
296: environment variable depends on
297: .Xr sudoers @mansectform@
298: settings.
299: By default,
300: .Nm sudo
301: will not modify
302: .Ev HOME
303: (see
304: .Em set_home
305: and
306: .Em always_set_home
307: in
308: .Xr sudoers @mansectform@ ) .
309: .It Fl h
310: The
1.5 ! schwarze 311: .Fl h Pq Em help
1.1 millert 312: option causes
313: .Nm sudo
314: to print a short help message to the standard output and exit.
315: .It Fl i Op Ar command
316: The
1.5 ! schwarze 317: .Fl i Pq Em simulate initial login
1.1 millert 318: option runs the shell specified by the password database entry of
319: the target user as a login shell.
320: This means that login-specific resource files such as
321: .Pa .profile
322: or
323: .Pa .login
324: will be read by the shell.
325: If a command is specified, it is passed to the shell for execution
326: via the shell's
327: .Fl c
328: option.
329: If no command is specified, an interactive shell is executed.
330: .Nm sudo
331: attempts to change to that user's home directory before running the
332: shell.
333: It also initializes the environment to a minimal
334: set of variables, similar to what is present when a user logs in.
335: The
336: .Sx Command Environment
337: section below documents in detail how the
338: .Fl i
339: option affects the environment in which a command is run.
340: .It Fl K
341: The
1.5 ! schwarze 342: .Fl K Pq sure Em kill
1.1 millert 343: option is like
344: .Fl k
345: except that it removes the user's time stamp file entirely and
346: may not be used in conjunction with a command or other option.
347: This option does not require a password.
348: .It Fl k Op Ar command
349: When used alone, the
1.5 ! schwarze 350: .Fl k Pq Em kill
1.1 millert 351: option to
352: .Nm sudo
353: invalidates the user's time stamp file.
354: The next time
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
365: a password, the
366: .Fl k
367: option will cause
368: .Nm sudo
369: to ignore the user's time stamp file.
370: As a result,
371: .Nm sudo
372: will prompt for a password (if one is required by
373: .Em sudoers )
374: and will not update the user's time stamp file.
375: .It Fl L
376: The
1.5 ! schwarze 377: .Fl L Pq Em list defaults
1.1 millert 378: option will list the parameters that
379: may be set in a
380: .Em Defaults
381: line along with a short description for each.
382: This option will be removed from a future version of
383: .Nm sudo .
384: .It Fl l Ns Oo Sy l Oc Op Ar command
385: If no
386: .Ar command
387: is specified, the
1.5 ! schwarze 388: .Fl l Pq Em list
1.1 millert 389: option will list the allowed (and forbidden) commands for the
390: invoking user (or the user specified by the
391: .Fl U
392: option) on the current host.
393: If a
394: .Ar command
395: is specified and is permitted by
396: .Em sudoers ,
397: the fully-qualified
398: path to the command is displayed along with any command line
399: arguments.
400: If
401: .Ar command
402: is specified but not allowed,
403: .Nm sudo
404: will exit with a status value of 1.
405: If the
406: .Fl l
407: option is specified with an
408: .Ar l
409: argument
410: .Pq i.e.\& Fl ll ,
411: or if
412: .Fl l
413: is specified multiple times, a longer list format is used.
414: .It Fl n
415: The
1.5 ! schwarze 416: .Fl n Pq Em non-interactive
1.1 millert 417: option prevents
418: .Nm sudo
419: from prompting the user for a password.
420: If a password is required for the command to run,
421: .Nm sudo
422: will display an error message and exit.
423: .It Fl P
424: The
1.5 ! schwarze 425: .Fl P Pq Em preserve group vector
1.1 millert 426: option causes
427: .Nm sudo
428: to preserve the invoking user's group vector unaltered.
429: By default,
430: .Nm sudo
431: will initialize the group vector to the list of groups the
432: target user is in.
433: The real and effective group IDs, however, are still set to match
434: the target user.
435: .It Fl p Ar prompt
436: The
1.5 ! schwarze 437: .Fl p Pq Em prompt
1.1 millert 438: option allows you to override the default password prompt and use
439: a custom one.
440: The following percent
441: .Pq Ql %
442: escapes are supported:
443: .Bl -tag -width 2n
444: .It Li %H
445: expanded to the host name including the domain name (on if the
446: machine's host name is fully qualified or the
447: .Em fqdn
448: option is set in
449: .Xr sudoers @mansectform@ )
450: .It Li %h
451: expanded to the local host name without the domain name
452: .It Li %p
453: expanded to the name of the user whose password is being requested
454: (respects the
455: .Em rootpw ,
456: .Em targetpw ,
457: and
458: .Em runaspw
459: flags in
460: .Xr sudoers @mansectform@ )
461: .It Li \&%U
462: expanded to the login name of the user the command will be run as
463: (defaults to root unless the
464: .Fl u
465: option is also specified)
466: .It Li %u
467: expanded to the invoking user's login name
468: .It Li %%
469: two consecutive
470: .Ql %
471: characters are collapsed into a single
472: .Ql %
473: character
474: .El
475: .Pp
476: The prompt specified by the
477: .Fl p
478: option will override the system password prompt on systems that
479: support PAM unless the
480: .Em passprompt_override
481: flag is disabled in
482: .Em sudoers .
483: .It Fl S
484: The
1.5 ! schwarze 485: .Fl S Pq Em stdin
1.1 millert 486: option causes
487: .Nm sudo
488: to read the password from the standard input instead of the terminal
489: device.
490: The password must be followed by a newline character.
491: .It Fl s Op Ar command
492: The
1.5 ! schwarze 493: .Fl s Pq Em shell
1.1 millert 494: option runs the shell specified by the
495: .Ev SHELL
496: environment variable if it is set or the shell as specified in the
497: password database.
498: If a command is specified, it is passed to the shell for execution
499: via the shell's
500: .Fl c
501: option.
502: If no command is specified, an interactive shell is executed.
503: .It Fl U Ar user
504: The
1.5 ! schwarze 505: .Fl U Pq other Em user
1.1 millert 506: option is used in conjunction with the
507: .Fl l
508: option to specify the user whose privileges should be listed.
509: Only root or a user with the
510: .Li ALL
511: privilege on the current host may use this option.
512: .It Fl u Ar user
513: The
1.5 ! schwarze 514: .Fl u Pq Em user
1.1 millert 515: option causes
516: .Nm sudo
517: to run the specified command as a user other than
518: .Em root .
1.5 ! schwarze 519: To specify a uid instead of a user name, use
! 520: .Ar #uid .
1.1 millert 521: When running commands as a
522: .Em uid ,
523: many shells require that the
524: .Ql #
525: be escaped with a backslash
526: .Pq Ql \e .
527: Note that if the
528: .Em targetpw
529: Defaults option is set (see
530: .Xr sudoers @mansectform@ ) ,
531: it is not possible to run commands with a uid not listed in the
532: password database.
533: .It Fl V
534: The
1.5 ! schwarze 535: .Fl V Pq Em version
1.1 millert 536: option causes
537: .Nm sudo
538: to print its version string and exit.
539: If the invoking user is already root the
540: .Fl V
541: option will display the arguments passed to configure when
542: .Nm sudo
543: was built as well a list of the defaults
544: .Nm sudo
545: was compiled with as well as the machine's local network addresses.
546: .It Fl v
547: When given the
1.5 ! schwarze 548: .Fl v Pq Em validate
1.1 millert 549: option,
550: .Nm sudo
551: will update the user's time stamp file, authenticating the user's
552: password if necessary.
553: This extends the
554: .Nm sudo
555: timeout for another
556: .Li @timeout@
557: minutes (or whatever the timeout is set to in
558: .Em sudoers )
559: but does not run a command.
560: .It Fl -
561: The
562: .Fl -
563: option indicates that
564: .Nm sudo
565: should stop processing command line arguments.
566: .El
567: .Pp
568: Environment variables to be set for the command may also be passed
569: on the command line in the form of
1.3 schwarze 570: .Ar VAR Ns No = Ns Ar value ,
1.1 millert 571: e.g.\&
1.5 ! schwarze 572: .Ev LD_LIBRARY_PATH Ns = Ns Pa /usr/local/pkg/lib .
1.1 millert 573: Variables passed on the command line are subject to the same
574: restrictions as normal environment variables with one important
575: exception.
576: If the
577: .Em setenv
578: option is set in
579: .Em sudoers ,
580: the command to be run has the
581: .Li SETENV
582: tag set or the command matched is
583: .Li ALL ,
584: the user may set variables that would otherwise be forbidden.
585: See
586: .Xr sudoers @mansectform@
587: for more information.
588: .Ss Authentication and Logging
589: .Nm sudo
590: requires that most users authenticate themselves by default.
591: A password is not required
592: if the invoking user is root, if the target user is the same as the
593: invoking user, or if the authentication has been disabled for the
594: user or command in the
595: .Em sudoers
596: file.
597: Unlike
598: .Xr su 1 ,
599: when
600: .Nm sudo
601: requires
602: authentication, it validates the invoking user's credentials, not
603: the target user's (or root's) credentials.
604: This can be changed via
605: the
606: .Em rootpw ,
607: .Em targetpw
608: and
609: .Em runaspw
610: Defaults entries in
611: .Em sudoers .
612: .Pp
613: If a user who is not listed in
614: .Em sudoers
615: tries to run a command via
616: .Nm sudo ,
617: mail is sent to the proper authorities.
618: The address
619: used for such mail is configurable via the
620: .Em mailto
621: .Em sudoers
622: Defaults entry and defaults to
623: .Li @mailto@ .
624: .Pp
625: Note that mail will not be sent if an unauthorized user tries to
626: run
627: .Nm sudo
628: with the
629: .Fl l
630: or
631: .Fl v
632: option.
633: This allows users to
634: determine for themselves whether or not they are allowed to use
635: .Nm sudo .
636: .Pp
637: If
638: .Nm sudo
639: is run by root and the
640: .Ev SUDO_USER
641: environment variable
642: is set, its value will be used to determine who the actual user is.
643: This can be used by a user to log commands
644: through
645: .Nm sudo
646: even when a root shell has been invoked.
647: It also
648: allows the
649: .Fl e
650: option to remain useful even when invoked via a
651: sudo-run script or program.
652: Note, however, that the
653: .Em sudoers
654: lookup is still done for root, not the user specified by
655: .Ev SUDO_USER .
656: .Pp
657: .Nm sudo
658: uses time stamp files for credential caching.
659: Once a
660: user has been authenticated, the time stamp is updated and the user
661: may then use sudo without a password for a short period of time
662: .Po
663: .Li @timeout@
664: minutes unless overridden by the
665: .Em timeout
666: option
667: .Pc .
668: By default,
669: .Nm sudo
670: uses a tty-based time stamp which means that
671: there is a separate time stamp for each of a user's login sessions.
672: The
673: .Em tty_tickets
674: option can be disabled to force the use of a
675: single time stamp for all of a user's sessions.
676: .Pp
677: .Nm sudo
678: can log both successful and unsuccessful attempts (as well
679: as errors) to
680: .Xr syslog 3 ,
681: a log file, or both.
682: By default,
683: .Nm sudo
684: will log via
685: .Xr syslog 3
686: but this is changeable via the
687: .Em syslog
688: and
689: .Em logfile
690: Defaults settings.
691: .Pp
692: .Nm sudo
693: also supports logging a command's input and output
694: streams.
695: I/O logging is not on by default but can be enabled using
696: the
697: .Em log_input
698: and
699: .Em log_output
700: Defaults flags as well as the
701: .Li LOG_INPUT
702: and
703: .Li LOG_OUTPUT
704: command tags.
705: .Ss Command Environment
706: Since environment variables can influence program behavior,
707: .Nm sudo
708: provides a means to restrict which variables from the user's
709: environment are inherited by the command to be run.
710: There are two
711: distinct ways
712: .Em sudoers
713: can be configured to handle with environment variables.
714: .Pp
715: By default, the
716: .Em env_reset
717: option is enabled.
718: This causes commands
719: to be executed with a new, minimal environment.
720: On AIX (and Linux
721: systems without PAM), the environment is initialized with the
722: contents of the
723: .Pa /etc/environment
724: file.
725: On BSD systems, if the
726: .Em use_loginclass
727: option is enabled, the environment is initialized
728: based on the
729: .Em path
730: and
731: .Em setenv
732: settings in
733: .Pa /etc/login.conf .
734: The new environment contains the
735: .Ev TERM ,
736: .Ev PATH ,
737: .Ev HOME ,
738: .Ev MAIL ,
739: .Ev SHELL ,
740: .Ev LOGNAME ,
741: .Ev USER ,
742: .Ev USERNAME
743: and
744: .Ev SUDO_*
745: variables
746: in addition to variables from the invoking process permitted by the
747: .Em env_check
748: and
749: .Em env_keep
750: options.
751: This is effectively a whitelist
752: for environment variables.
753: .Pp
754: If, however, the
755: .Em env_reset
756: option is disabled, any variables not
757: explicitly denied by the
758: .Em env_check
759: and
760: .Em env_delete
761: options are
762: inherited from the invoking process.
763: In this case,
764: .Em env_check
765: and
766: .Em env_delete
767: behave like a blacklist.
768: Since it is not possible
769: to blacklist all potentially dangerous environment variables, use
770: of the default
771: .Em env_reset
772: behavior is encouraged.
773: .Pp
774: In all cases, environment variables with a value beginning with
775: .Li ()
776: are removed as they could be interpreted as
777: .Sy bash
778: functions.
779: The list of environment variables that
780: .Nm sudo
781: allows or denies is
782: contained in the output of
783: .Dq Li sudo -V
784: when run as root.
785: .Pp
786: Note that the dynamic linker on most operating systems will remove
787: variables that can control dynamic linking from the environment of
788: setuid executables, including
789: .Nm sudo .
790: Depending on the operating
791: system this may include
792: .Ev _RLD* ,
793: .Ev DYLD_* ,
794: .Ev LD_* ,
795: .Ev LDR_* ,
796: .Ev LIBPATH ,
797: .Ev SHLIB_PATH ,
798: and others.
799: These type of variables are
800: removed from the environment before
801: .Nm sudo
802: even begins execution
803: and, as such, it is not possible for
804: .Nm sudo
805: to preserve them.
806: .Pp
807: As a special case, if
1.5 ! schwarze 808: .Nm sudo Ns 's
1.1 millert 809: .Fl i
810: option (initial login) is
811: specified,
812: .Nm sudo
813: will initialize the environment regardless
814: of the value of
815: .Em env_reset .
816: The
817: .Ev DISPLAY ,
818: .Ev PATH
819: and
820: .Ev TERM
821: variables remain unchanged;
822: .Ev HOME ,
823: .Ev MAIL ,
824: .Ev SHELL ,
825: .Ev USER ,
826: and
827: .Ev LOGNAME
828: are set based on the target user.
829: On AIX (and Linux
830: systems without PAM), the contents of
831: .Pa /etc/environment
832: are also
833: included.
834: On BSD systems, if the
835: .Em use_loginclass
836: option is
837: enabled, the
838: .Em path
839: and
840: .Em setenv
841: variables in
842: .Pa /etc/login.conf
843: are also applied.
844: All other environment variables are removed.
845: .Pp
846: Finally, if the
847: .Em env_file
848: option is defined, any variables present
849: in that file will be set to their specified values as long as they
850: would not conflict with an existing environment variable.
851: .Sh EXIT VALUE
852: Upon successful execution of a program, the exit status from
853: .Em sudo
854: will simply be the exit status of the program that was executed.
855: .Pp
856: Otherwise,
857: .Nm sudo
858: exits with a value of 1 if there is a configuration/permission
859: problem or if
860: .Nm sudo
861: cannot execute the given command.
862: In the latter case the error string is printed to the standard error.
863: If
864: .Nm sudo
865: cannot
866: .Xr stat 2
867: one or more entries in the user's
868: .Ev PATH ,
869: an error is printed on stderr.
870: (If the directory does not exist or if it is not really a directory,
871: the entry is ignored and no error is printed.)
872: This should not happen under normal circumstances.
873: The most common reason for
874: .Xr stat 2
875: to return
876: .Dq permission denied
877: is if you are running an automounter and one of the directories in
878: your
879: .Ev PATH
880: is on a machine that is currently unreachable.
881: .Sh LOG FORMAT
882: .Nm sudo
883: can log events using either
884: .Xr syslog 3
885: or a simple log file.
886: In each case the log format is almost identical.
887: .Ss Accepted command log entries
888: Commands that sudo runs are logged using the following format (split
889: into multiple lines for readability):
890: .Bd -literal -offset 4n
891: date hostname progname: username : TTY=ttyname ; PWD=cwd ; \e
892: USER=runasuser ; GROUP=runasgroup ; TSID=logid ; \e
893: ENV=env_vars COMMAND=command
894: .Ed
895: .Pp
896: Where the fields are as follows:
897: .Bl -tag -width 12n
898: .It date
899: The date the command was run.
900: Typically, this is in the format
901: .Dq MMM, DD, HH:MM:SS .
902: If logging via
903: .Xr syslog 3 ,
904: the actual date format is controlled by the syslog daemon.
905: If logging to a file and the
906: .Em log_year
907: option is enabled,
908: the date will also include the year.
909: .It hostname
910: The name of the host
911: .Nm sudo
912: was run on.
913: This field is only present when logging via
914: .Xr syslog 3 .
915: .It progname
916: The name of the program, usually
917: .Em sudo
918: or
919: .Em sudoedit .
920: This field is only present when logging via
921: .Xr syslog 3 .
922: .It username
923: The login name of the user who ran
924: .Nm sudo .
925: .It ttyname
926: The short name of the terminal (e.g.\&
927: .Dq console ,
928: .Dq tty01 ,
929: or
930: .Dq pts/0 )
931: .Nm sudo
932: was run on, or
933: .Dq unknown
934: if there was no terminal present.
935: .It cwd
936: The current working directory that
937: .Nm sudo
938: was run in.
939: .It runasuser
940: The user the command was run as.
941: .It runasgroup
942: The group the command was run as if one was specified on the command line.
943: .It logid
944: An I/O log identifier that can be used to replay the command's output.
945: This is only present when the
946: .Em log_input
947: or
948: .Em log_output
949: option is enabled.
950: .It env_vars
951: A list of environment variables specified on the command line,
952: if specified.
953: .It command
954: The actual command that was executed.
955: .El
956: .Pp
957: Messages are logged using the locale specified by
958: .Em sudoers_locale ,
959: which defaults to the
960: .Dq Li C
961: locale.
962: .Ss Denied command log entries
963: If the user is not allowed to run the command, the reason for the denial
964: will follow the user name.
965: Possible reasons include:
966: .Bl -tag -width 4
967: .It user NOT in sudoers
968: The user is not listed in the
969: .Em sudoers
970: file.
971: .It user NOT authorized on host
972: The user is listed in the
973: .Em sudoers
974: file but is not allowed to run commands on the host.
975: .It command not allowed
976: The user is listed in the
977: .Em sudoers
978: file for the host but they are not allowed to run the specified command.
979: .It 3 incorrect password attempts
980: The user failed to enter their password after 3 tries.
981: The actual number of tries will vary based on the number of
982: failed attempts and the value of the
983: .Em passwd_tries
984: .Em sudoers
985: option.
986: .It a password is required
987: The
988: .Fl n
989: option was specified but a password was required.
990: .It sorry, you are not allowed to set the following environment variables
991: The user specified environment variables on the command line that
992: were not allowed by
993: .Em sudoers .
994: .El
995: .Ss Error log entries
996: If an error occurs,
997: .Nm sudo
998: will log a message and, in most cases, send a message to the
999: administrator via email.
1000: Possible errors include:
1001: .Bl -tag -width 4
1002: .It parse error in @sysconfdir@/sudoers near line N
1003: .Nm sudo
1004: encountered an error when parsing the specified file.
1005: In some cases, the actual error may be one line above or below the
1006: line number listed, depending on the type of error.
1007: .It problem with defaults entries
1008: The
1009: .Em sudoers
1010: file contains one or more unknown Defaults settings.
1011: This does not prevent
1012: .Nm sudo
1013: from running, but the
1014: .Em sudoers
1015: file should be checked using
1016: .Nm visudo .
1017: .It timestamp owner (username): \&No such user
1018: The time stamp directory owner, as specified by the
1019: .Em timestampowner
1020: setting, could not be found in the password database.
1021: .It unable to open/read @sysconfdir@/sudoers
1022: The
1023: .Em sudoers
1024: file could not be opened for reading.
1025: This can happen when the
1026: .Em sudoers
1027: file is located on a remote file system that maps user ID 0 to
1028: a different value.
1029: Normally,
1030: .Nm sudo
1031: tries to open
1032: .Em sudoers
1033: using group permissions to avoid this problem.
1034: .It unable to stat @sysconfdir@/sudoers
1035: The
1036: .Pa @sysconfdir@/sudoers
1037: file is missing.
1038: .It @sysconfdir@/sudoers is not a regular file
1039: The
1040: .Pa @sysconfdir@/sudoers
1041: file exists but is not a regular file or symbolic link.
1042: .It @sysconfdir@/sudoers is owned by uid N, should be 0
1043: The
1044: .Em sudoers
1045: file has the wrong owner.
1046: .It @sysconfdir@/sudoers is world writable
1047: The permissions on the
1048: .Em sudoers
1049: file allow all users to write to it.
1050: The
1051: .Em sudoers
1052: file must not be world-writable, the default file mode
1053: is 0440 (readable by owner and group, writable by none).
1054: .It @sysconfdir@/sudoers is owned by gid N, should be 1
1055: The
1056: .Em sudoers
1057: file has the wrong group ownership.
1058: .It unable to open @timedir@/username/ttyname
1059: .Em sudoers
1060: was unable to read or create the user's time stamp file.
1061: .It unable to write to @timedir@/username/ttyname
1062: .Em sudoers
1063: was unable to write to the user's time stamp file.
1064: .It unable to mkdir to @timedir@/username
1065: .Em sudoers
1066: was unable to create the user's time stamp directory.
1067: .El
1068: .Ss Notes on logging via syslog
1069: By default,
1070: .Em sudoers
1071: logs messages via
1072: .Xr syslog 3 .
1073: The
1074: .Em date ,
1075: .Em hostname ,
1076: and
1077: .Em progname
1078: fields are added by the syslog daemon, not
1079: .Em sudoers
1080: itself.
1081: As such, they may vary in format on different systems.
1082: .Pp
1083: On most systems,
1084: .Xr syslog 3
1085: has a relatively small log buffer.
1086: To prevent the command line arguments from being truncated,
1087: .Nm sudo
1088: will split up log messages that are larger than 960 characters
1089: (not including the date, hostname, and the string
1090: .Dq sudo ) .
1091: When a message is split, additional parts will include the string
1092: .Dq Pq command continued
1093: after the user name and before the continued command line arguments.
1094: .Ss Notes on logging to a file
1095: If the
1096: .Em logfile
1097: option is set,
1098: .Em sudoers
1099: will log to a local file, such as
1100: .Pa /var/log/sudo .
1101: When logging to a file,
1102: .Em sudoers
1103: uses a format similar to
1104: .Xr syslog 3 ,
1105: with a few important differences:
1106: .Bl -enum
1107: .It
1108: The
1109: .Em progname
1110: and
1111: .Em hostname
1112: fields are not present.
1113: .It
1114: If the
1115: .Em log_year
1116: .Em sudoers
1117: option is enabled,
1118: the date will also include the year.
1119: .It
1120: Lines that are longer than
1121: .Em loglinelen
1122: characters (80 by default) are word-wrapped and continued on the
1123: next line with a four character indent.
1124: This makes entries easier to read for a human being, but makes it
1125: more difficult to use
1126: .Xr grep 1
1127: on the log files.
1128: If the
1129: .Em loglinelen
1130: .Em sudoers
1131: option is set to 0 (or negated with a
1132: .Ql \&! ) ,
1133: word wrap will be disabled.
1134: .El
1135: .Sh SECURITY NOTES
1136: .Nm sudo
1137: tries to be safe when executing external commands.
1138: .Pp
1139: To prevent command spoofing,
1140: .Nm sudo
1141: checks "." and "" (both denoting current directory) last when
1142: searching for a command in the user's
1143: .Ev PATH
1144: (if one or both are in the
1145: .Ev PATH ) .
1146: Note, however, that the actual
1147: .Ev PATH
1148: environment variable is
1149: .Em not
1150: modified and is passed unchanged to the program that
1151: .Nm sudo
1152: executes.
1153: .Pp
1154: .Nm sudo
1155: will check the ownership of its time stamp directory
1156: .Po
1157: .Pa @timedir@
1158: by default
1159: .Pc
1160: and ignore the directory's contents if it is not owned by root or
1161: if it is writable by a user other than root.
1162: On systems that allow non-root users to give away files via
1163: .Xr chown 2 ,
1164: if the time stamp directory is located in a world-writable
1165: directory (e.g.\&,
1166: .Pa /tmp ) ,
1167: it is possible for a user to create the time stamp directory before
1168: .Nm sudo
1169: is run.
1170: However, because
1171: .Nm sudo
1172: checks the ownership and mode of the directory and its
1173: contents, the only damage that can be done is to
1174: .Dq hide
1175: files by putting them in the time stamp dir.
1176: This is unlikely to happen since once the time stamp dir is owned by root
1177: and inaccessible by any other user, the user placing files there would be
1178: unable to get them back out.
1179: .Pp
1180: .Nm sudo
1181: will not honor time stamps set far in the future.
1182: Time stamps with a date greater than current_time + 2 *
1183: .Li TIMEOUT
1184: will be ignored and sudo will log and complain.
1185: This is done to keep a user from creating his/her own time stamp with a
1186: bogus date on systems that allow users to give away files if the time
1187: stamp directory is located in a world-writable directory.
1188: .Pp
1189: Since time stamp files live in the file system, they can outlive a
1190: user's login session.
1191: As a result, a user may be able to login, run a command with
1192: .Nm sudo
1193: after authenticating, logout, login again, and run
1194: .Nm sudo
1195: without authenticating so long as the time stamp file's modification
1196: time is within
1197: .Li @timeout@
1198: minutes (or whatever the timeout is set to in
1199: .Em sudoers ) .
1200: When the
1201: .Em tty_tickets
1202: .Em sudoers
1203: option is enabled, the time stamp has per-tty granularity but still
1204: may outlive the user's session.
1205: .Pp
1206: Please note that
1207: .Nm sudo
1208: will normally only log the command it explicitly runs.
1209: If a user runs a command such as
1210: .Li sudo su
1211: or
1212: .Li sudo sh ,
1213: subsequent commands run from that shell are not subject to
1.5 ! schwarze 1214: .Nm sudo Ns 's
1.1 millert 1215: security policy.
1216: The same is true for commands that offer shell escapes (including
1217: most editors).
1218: If I/O logging is enabled, subsequent commands will have their input and/or
1219: output logged, but there will not be traditional logs for those commands.
1220: Because of this, care must be taken when giving users access to commands via
1221: .Nm sudo
1222: to verify that the command does not inadvertently give the user an
1223: effective root shell.
1224: For more information, please see the
1225: .Em PREVENTING SHELL ESCAPES
1226: section in
1227: .Xr sudoers @mansectform@ .
1228: .Pp
1229: To prevent the disclosure of potentially sensitive information,
1230: .Nm sudo
1231: disables core dumps by default while it is executing (they are
1232: re-enabled for the command that is run).
1233: .Pp
1234: For information on the security implications of
1235: .Em sudoers
1236: entries, please see the
1237: .Em SECURITY NOTES
1238: section in
1239: .Xr sudoers @mansectform@ .
1240: .Sh ENVIRONMENT
1241: .Nm sudo
1242: utilizes the following environment variables:
1243: .Bl -tag -width 15n
1244: .It Ev EDITOR
1245: Default editor to use in
1246: .Fl e
1247: (sudoedit) mode if neither
1248: .Ev SUDO_EDITOR
1249: nor
1250: .Ev VISUAL
1251: is set.
1252: .It Ev MAIL
1253: In
1254: .Fl i
1255: mode or when
1256: .Em env_reset
1257: is enabled in
1258: .Em sudoers ,
1259: set to the mail spool of the target user.
1260: .It Ev HOME
1261: Set to the home directory of the target user if
1262: .Fl H
1263: it specified,
1264: .Em always_set_home
1265: is set in
1266: .Em sudoers ,
1267: or when the
1268: .Fl s
1269: option is specified and
1270: .Em set_home
1271: is set in
1272: .Em sudoers .
1273: .It Ev PATH
1274: Set to a sane value if the
1275: .Em secure_path
1276: option is set in the
1277: .Em sudoers
1278: file.
1279: .It Ev SHELL
1280: Used to determine shell to run with
1281: .Fl s
1282: option.
1283: .It Ev SUDO_ASKPASS
1284: Specifies the path to a helper program used to read the password
1285: if no terminal is available or if the
1286: .Fl A
1287: option is specified.
1288: .It Ev SUDO_COMMAND
1289: Set to the command run by sudo.
1290: .It Ev SUDO_EDITOR
1291: Default editor to use in
1292: .Fl e
1293: (sudoedit) mode.
1294: .It Ev SUDO_GID
1295: Set to the group ID of the user who invoked sudo.
1296: .It Ev SUDO_PROMPT
1297: Used as the default password prompt.
1298: .It Ev SUDO_PS1
1299: If set,
1300: .Ev PS1
1301: will be set to its value for the program being run.
1302: .It Ev SUDO_UID
1303: Set to the user ID of the user who invoked sudo.
1304: .It Ev SUDO_USER
1305: Set to the login name of the user who invoked sudo.
1306: .It Ev USER
1307: Set to the target user (root unless the
1308: .Fl u
1309: option is specified).
1310: .It Ev VISUAL
1311: Default editor to use in
1312: .Fl e
1313: (sudoedit) mode if
1314: .Ev SUDO_EDITOR
1315: is not set.
1316: .El
1317: .Sh FILES
1318: .Bl -tag -width 24n
1319: .It Pa @sysconfdir@/sudoers
1320: List of who can run what
1321: .It Pa @timedir@
1322: Directory containing time stamps
1323: .It Pa /etc/environment
1324: Initial environment for
1325: .Fl i
1326: mode on AIX and Linux systems
1327: .El
1328: .Sh EXAMPLES
1329: Note: the following examples assume suitable
1.5 ! schwarze 1330: .Xr sudoers @mansectform@
1.1 millert 1331: entries.
1332: .Pp
1333: To get a file listing of an unreadable directory:
1334: .Bd -literal -offset indent
1335: $ sudo ls /usr/local/protected
1336: .Ed
1337: .Pp
1338: To list the home directory of user yaz on a machine where the file
1339: system holding ~yaz is not exported as root:
1340: .Bd -literal -offset indent
1341: $ sudo -u yaz ls ~yaz
1342: .Ed
1343: .Pp
1344: To edit the
1345: .Pa index.html
1346: file as user www:
1347: .Bd -literal -offset indent
1348: $ sudo -u www vi ~www/htdocs/index.html
1349: .Ed
1350: .Pp
1351: To view system logs only accessible to root and users in the adm
1352: group:
1353: .Bd -literal -offset indent
1354: $ sudo -g adm view /var/log/syslog
1355: .Ed
1356: .Pp
1357: To run an editor as jim with a different primary group:
1358: .Bd -literal -offset indent
1359: $ sudo -u jim -g audio vi ~jim/sound.txt
1360: .Ed
1361: .Pp
1362: To shut down a machine:
1363: .Bd -literal -offset indent
1364: $ sudo shutdown -r +15 "quick reboot"
1365: .Ed
1366: .Pp
1367: To make a usage listing of the directories in the /home partition.
1368: Note that this runs the commands in a sub-shell to make the
1369: .Li cd
1370: and file redirection work.
1371: .Bd -literal -offset indent
1372: $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
1373: .Ed
1374: .Sh SEE ALSO
1375: .Xr grep 1 ,
1376: .Xr su 1 ,
1377: .Xr stat 2 ,
1378: .Xr login_cap 3 ,
1379: .Xr passwd @mansectform@ ,
1380: .Xr sudoers @mansectform@ ,
1381: .Xr sudoreplay @mansectsu@ ,
1382: .Xr visudo @mansectsu@
1383: .Sh HISTORY
1384: See the HISTORY file in the
1385: .Nm sudo
1386: distribution (http://www.sudo.ws/sudo/history.html) for a brief
1387: history of sudo.
1388: .Sh AUTHORS
1389: Many people have worked on
1390: .Nm sudo
1391: over the years; this version consists of code written primarily by:
1392: .Bd -ragged -offset indent
1393: Todd C. Miller
1394: .Ed
1395: .Pp
1396: See the CONTRIBUTORS file in the
1397: .Nm sudo
1398: distribution (http://www.sudo.ws/sudo/contributors.html) for an
1399: exhaustive list of people who have contributed to
1400: .Nm sudo .
1401: .Sh CAVEATS
1402: There is no easy way to prevent a user from gaining a root shell
1403: if that user is allowed to run arbitrary commands via
1404: .Nm sudo .
1405: Also, many programs (such as editors) allow the user to run commands
1406: via shell escapes, thus avoiding
1.5 ! schwarze 1407: .Nm sudo Ns 's
1.1 millert 1408: checks.
1409: However, on most systems it is possible to prevent shell escapes with
1.5 ! schwarze 1410: .Nm sudo Ns 's
1.1 millert 1411: .Em noexec
1412: functionality.
1413: See the
1414: .Xr sudoers @mansectform@
1415: manual for details.
1416: .Pp
1417: It is not meaningful to run the
1418: .Li cd
1419: command directly via sudo, e.g.,
1420: .Bd -literal -offset indent
1421: $ sudo cd /usr/local/protected
1422: .Ed
1423: .Pp
1424: since when the command exits the parent process (your shell) will
1425: still be the same.
1426: Please see the
1427: .Sx EXAMPLES
1428: section for more information.
1429: .Pp
1430: Running shell scripts via
1431: .Nm sudo
1432: can expose the same kernel bugs that make setuid shell scripts
1433: unsafe on some operating systems (if your OS has a /dev/fd/ directory,
1434: setuid shell scripts are generally safe).
1435: .Sh BUGS
1436: If you feel you have found a bug in
1437: .Nm sudo ,
1438: please submit a bug report at http://www.sudo.ws/sudo/bugs/
1439: .Sh SUPPORT
1440: Limited free support is available via the sudo-users mailing list,
1441: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1442: search the archives.
1443: .Sh DISCLAIMER
1444: .Nm sudo
1445: is provided
1446: .Dq AS IS
1447: and any express or implied warranties, including, but not limited
1448: to, the implied warranties of merchantability and fitness for a
1449: particular purpose are disclaimed.
1450: See the LICENSE file distributed with
1451: .Nm sudo
1452: or http://www.sudo.ws/sudo/license.html for complete details.
![[BACK]](/icons/back.gif){kind=icon}
Return to sudo.mdoc.in CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / sudo