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