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