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