Annotation of embedaddon/sudo/doc/sudo.mdoc.in, revision 1.1.1.1
1.1 misho 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: .\"
22: .Dd July 10, 2012
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
142: .Sx PLUGINS
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
205: .Pa @sysconfdir@/sudo.conf
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
690: envionment for the command.
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 ,
728: sets up the execution environment as described above, and calls the
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
734: command's exit status to the security policy's close method and exits.
735: If an I/O logging plugin is configured, a new pseudo-terminal
736: .Pq Dq pty
737: is created and a second
738: .Nm sudo
739: process is used to relay job control signals between the user's
740: existing pty and the new pty the command is being run in.
741: This extra process makes it possible to, for example, suspend
742: and resume the command.
743: Without it, the command would be in what POSIX terms an
744: .Dq orphaned process group
745: and it would not receive any job control signals.
746: .Ss Signal handling
747: Because the command is run as a child of the
748: .Nm sudo
749: process,
750: .Nm sudo
751: will relay signals it receives to the command.
752: Unless the command is being run in a new pty, the
753: .Dv SIGHUP ,
754: .Dv SIGINT
755: and
756: .Dv SIGQUIT
757: signals are not relayed unless they are sent by a user process,
758: not the kernel.
759: Otherwise, the command would receive
760: .Dv SIGINT
761: twice every time the user entered control-C.
762: Some signals, such as
763: .Dv SIGSTOP
764: and
765: .Dv SIGKILL ,
766: cannot be caught and thus will not be relayed to the command.
767: As a general rule,
768: .Dv SIGTSTP
769: should be used instead of
770: .Dv SIGSTOP
771: when you wish to suspend a command being run by
772: .Nm sudo .
773: .Pp
774: As a special case,
775: .Nm sudo
776: will not relay signals that were sent by the command it is running.
777: This prevents the command from accidentally killing itself.
778: On some systems, the
779: .Xr reboot @mansectsu@
780: command sends
781: .Dv SIGTERM
782: to all non-system processes other than itself before rebooting
783: the systyem.
784: This prevents
785: .Nm sudo
786: from relaying the
787: .Dv SIGTERM
788: signal it received back to
789: .Xr reboot @mansectsu@ ,
790: which might then exit before the system was actually rebooted,
791: leaving it in a half-dead state similar to single user mode.
792: Note, however, that this check only applies to the command run by
793: .Nm sudo
794: and not any other processes that the command may create.
795: As a result, running a script that calls
796: .Xr reboot @mansectsu@
797: or
798: .Xr shutdown @mansectsu@
799: via
800: .Nm sudo
801: may cause the system to end up in this undefined state unless the
802: .Xr reboot @mansectsu@
803: or
804: .Xr shutdown @mansectsu@
805: are run using the
806: .Fn exec
807: family of functions instead of
808: .Fn system
809: (which interposes a shell between the command and the calling process).
810: .Sh PLUGINS
811: Plugins are dynamically loaded based on the contents of the
812: .Pa @sysconfdir@/sudo.conf
813: file.
814: If no
815: .Pa @sysconfdir@/sudo.conf
816: file is present, or it contains no
817: .Li Plugin
818: lines,
819: .Nm sudo
820: will use the traditional
821: .Em sudoers
822: security policy and I/O logging, which corresponds to the following
823: .Pa @sysconfdir@/sudo.conf
824: file.
825: .Bd -literal
826: #
827: # Default @sysconfdir@/sudo.conf file
828: #
829: # Format:
830: # Plugin plugin_name plugin_path plugin_options ...
831: # Path askpass /path/to/askpass
832: # Path noexec /path/to/sudo_noexec.so
833: # Debug sudo /var/log/sudo_debug all@warn
834: # Set disable_coredump true
835: #
836: # The plugin_path is relative to @prefix@/libexec unless
837: # fully qualified.
838: # The plugin_name corresponds to a global symbol in the plugin
839: # that contains the plugin interface structure.
840: # The plugin_options are optional.
841: #
842: Plugin policy_plugin sudoers.so
843: Plugin io_plugin sudoers.so
844: .Ed
845: .Pp
846: A
847: .Li Plugin
848: line consists of the
849: .Li Plugin
850: keyword, followed by the
851: .Em symbol_name
852: and the
853: .Em path
854: to the shared object containing the plugin.
855: The
856: .Em symbol_name
857: is the name of the
858: .Li struct policy_plugin
859: or
860: .Li struct io_plugin
861: in the plugin shared object.
862: The
863: .Em path
864: may be fully qualified or relative.
865: If not fully qualified it is relative to the
866: .Pa @prefix@/libexec
867: directory.
868: Any additional parameters after the
869: .Em path
870: are passed as arguments to the plugin's
871: .Em open
872: function.
873: Lines that don't begin with
874: .Li Plugin ,
875: .Li Path ,
876: .Li Debug ,
877: or
878: .Li Set
879: are silently ignored.
880: .Pp
881: For more information, see the
882: .Xr sudo_plugin @mansectsu@
883: manual.
884: .Sh PATHS
885: A
886: .Li Path
887: line consists of the
888: .Li Path
889: keyword, followed by the name of the path to set and its value.
890: E.g.
891: .Bd -literal -offset indent
892: Path noexec @noexec_file@
893: Path askpass /usr/X11R6/bin/ssh-askpass
894: .Ed
895: .Pp
896: The following plugin-agnostic paths may be set in the
897: .Pa @sysconfdir@/sudo.conf
898: file:
899: .Bl -tag -width 8n
900: .It askpass
901: The fully qualified path to a helper program used to read the user's
902: password when no terminal is available.
903: This may be the case when
904: .Nm sudo
905: is executed from a graphical (as opposed to text-based) application.
906: The program specified by
907: .Em askpass
908: should display the argument passed to it as the prompt and write
909: the user's password to the standard output.
910: The value of
911: .Em askpass
912: may be overridden by the
913: .Ev SUDO_ASKPASS
914: environment variable.
915: .It noexec
916: The fully-qualified path to a shared library containing dummy
917: versions of the
918: .Fn execv ,
919: .Fn execve
920: and
921: .Fn fexecve
922: library functions that just return an error.
923: This is used to implement the
924: .Em noexec
925: functionality on systems that support
926: .Ev LD_PRELOAD
927: or its equivalent.
928: Defaults to
929: .Pa @noexec_file@ .
930: .El
931: .Sh DEBUG FLAGS
932: .Nm sudo
933: versions 1.8.4 and higher support a flexible debugging framework
934: that can help track down what
935: .Nm sudo
936: is doing internally if there is a problem.
937: .Pp
938: A
939: .Li Debug
940: line consists of the
941: .Li Debug
942: keyword, followed by the name of the program to debug
943: .Pq Nm sudo , Nm visudo , Nm sudoreplay ,
944: the debug file name and a comma-separated list of debug flags.
945: The debug flag syntax used by
946: .Nm sudo
947: and the
948: .Em sudoers
949: plugin is
950: .Em subsystem Ns No @ Ns Em priority
951: but the plugin is free to use a different format so long as it does
952: not include a comma
953: .Pq Ql \&, .
954: .Pp
955: For instance:
956: .Bd -literal -offset indent
957: Debug sudo /var/log/sudo_debug all@warn,plugin@info
958: .Ed
959: .Pp
960: would log all debugging statements at the
961: .Em warn
962: level and higher in addition to those at the
963: .Em info
964: level for the plugin subsystem.
965: .Pp
966: Currently, only one
967: .Li Debug
968: entry per program is supported.
969: The
970: .Nm sudo
971: .Li Debug
972: entry is shared by the
973: .Nm sudo
974: front end,
975: .Nm sudoedit
976: and the plugins.
977: A future release may add support for per-plugin
978: .Li Debug
979: lines and/or support for multiple debugging files for a single
980: program.
981: .Pp
982: The priorities used by the
983: .Nm sudo
984: front end, in order of decreasing severity, are:
985: .Em crit , err , warn , notice , diag , info , trace
986: and
987: .Em debug .
988: Each priority, when specified, also includes all priorities higher
989: than it.
990: For example, a priority of
991: .Em notice
992: would include debug messages logged at
993: .Em notice
994: and higher.
995: .Pp
996: The following subsystems are used by the
997: .Nm sudo
998: front-end:
999: .Bl -tag -width Fl
1000: .It Em all
1001: matches every subsystem
1002: .It Em args
1003: command line argument processing
1004: .It Em conv
1005: user conversation
1006: .It Em edit
1007: sudoedit
1008: .It Em exec
1009: command execution
1010: .It Em main
1011: .Nm sudo
1012: main function
1013: .It Em netif
1014: network interface handling
1015: .It Em pcomm
1016: communication with the plugin
1017: .It Em plugin
1018: plugin configuration
1019: .It Em pty
1020: pseudo-tty related code
1021: .It Em selinux
1022: SELinux-specific handling
1023: .It Em util
1024: utility functions
1025: .It Em utmp
1026: utmp handling
1027: .El
1028: .Sh EXIT VALUE
1029: Upon successful execution of a program, the exit status from
1030: .Em sudo
1031: will simply be the exit status of the program that was executed.
1032: .Pp
1033: Otherwise,
1034: .Nm sudo
1035: exits with a value of 1 if there is a configuration/permission
1036: problem or if
1037: .Nm sudo
1038: cannot execute the given command.
1039: In the latter case the error string is printed to the standard error.
1040: If
1041: .Nm sudo
1042: cannot
1043: .Xr stat 2
1044: one or more entries in the user's
1045: .Ev PATH ,
1046: an error is printed on stderr.
1047: (If the directory does not exist or if it is not really a directory,
1048: the entry is ignored and no error is printed.)
1049: This should not happen under normal circumstances.
1050: The most common reason for
1051: .Xr stat 2
1052: to return
1053: .Dq permission denied
1054: is if you are running an automounter and one of the directories in
1055: your
1056: .Ev PATH
1057: is on a machine that is currently unreachable.
1058: .Sh SECURITY NOTES
1059: .Nm sudo
1060: tries to be safe when executing external commands.
1061: .Pp
1062: To prevent command spoofing,
1063: .Nm sudo
1064: checks "." and "" (both denoting current directory) last when
1065: searching for a command in the user's
1066: .Ev PATH
1067: (if one or both are in the
1068: .Ev PATH ) .
1069: Note, however, that the actual
1070: .Ev PATH
1071: environment variable is
1072: .Em not
1073: modified and is passed unchanged to the program that
1074: .Nm sudo
1075: executes.
1076: .Pp
1077: Please note that
1078: .Nm sudo
1079: will normally only log the command it explicitly runs.
1080: If a user runs a command such as
1081: .Li sudo su
1082: or
1083: .Li sudo sh ,
1084: subsequent commands run from that shell are not subject to
1085: .Nm sudo Ns No 's
1086: security policy.
1087: The same is true for commands that offer shell escapes (including
1088: most editors).
1089: If I/O logging is enabled, subsequent commands will have their input and/or
1090: output logged, but there will not be traditional logs for those commands.
1091: Because of this, care must be taken when giving users access to commands via
1092: .Nm sudo
1093: to verify that the command does not inadvertently give the user an
1094: effective root shell.
1095: For more information, please see the
1096: .Em PREVENTING SHELL ESCAPES
1097: section in
1098: .Xr sudoers @mansectform@ .
1099: .Pp
1100: To prevent the disclosure of potentially sensitive information,
1101: .Nm sudo
1102: disables core dumps by default while it is executing (they are
1103: re-enabled for the command that is run).
1104: To aid in debugging
1105: .Nm sudo
1106: crashes, you may wish to re-enable core dumps by setting
1107: .Dq disable_coredump
1108: to false in the
1109: .Pa @sysconfdir@/sudo.conf
1110: file as follows:
1111: .Bd -literal -offset indent
1112: Set disable_coredump false
1113: .Ed
1114: .Pp
1115: Note that by default, most operating systems disable core dumps
1116: from setuid programs, which includes
1117: .Nm sudo .
1118: To actually get a
1119: .Nm sudo
1120: core file you may need to enable core dumps for setuid processes.
1121: On BSD and Linux systems this is accomplished via the sysctl command,
1122: on Solaris the coreadm command can be used.
1123: .Sh ENVIRONMENT
1124: .Nm sudo
1125: utilizes the following environment variables.
1126: The security policy has control over the actual content of the command's
1127: environment.
1128: .Bl -tag -width 15n
1129: .It Ev EDITOR
1130: Default editor to use in
1131: .Fl e
1132: (sudoedit) mode if neither
1133: .Ev SUDO_EDITOR
1134: nor
1135: .Ev VISUAL
1136: is set.
1137: .It Ev MAIL
1138: In
1139: .Fl i
1140: mode or when
1141: .Em env_reset
1142: is enabled in
1143: .Em sudoers ,
1144: set to the mail spool of the target user.
1145: .It Ev HOME
1146: Set to the home directory of the target user if
1147: .Fl i
1148: or
1149: .Fl H
1150: are specified,
1151: .Em env_reset
1152: or
1153: .Em always_set_home
1154: are set in
1155: .Em sudoers ,
1156: or when the
1157: .Fl s
1158: option is specified and
1159: .Em set_home
1160: is set in
1161: .Em sudoers .
1162: .It Ev PATH
1163: May be overridden by the security policy.
1164: .It Ev SHELL
1165: Used to determine shell to run with
1166: .Fl s
1167: option.
1168: .It Ev SUDO_ASKPASS
1169: Specifies the path to a helper program used to read the password
1170: if no terminal is available or if the
1171: .Fl A
1172: option is specified.
1173: .It Ev SUDO_COMMAND
1174: Set to the command run by sudo.
1175: .It Ev SUDO_EDITOR
1176: Default editor to use in
1177: .Fl e
1178: (sudoedit) mode.
1179: .It Ev SUDO_GID
1180: Set to the group ID of the user who invoked sudo.
1181: .It Ev SUDO_PROMPT
1182: Used as the default password prompt.
1183: .It Ev SUDO_PS1
1184: If set,
1185: .Ev PS1
1186: will be set to its value for the program being run.
1187: .It Ev SUDO_UID
1188: Set to the user ID of the user who invoked sudo.
1189: .It Ev SUDO_USER
1190: Set to the login name of the user who invoked sudo.
1191: .It Ev USER
1192: Set to the target user (root unless the
1193: .Fl u
1194: option is specified).
1195: .It Ev VISUAL
1196: Default editor to use in
1197: .Fl e
1198: (sudoedit) mode if
1199: .Ev SUDO_EDITOR
1200: is not set.
1201: .El
1202: .Sh FILES
1203: .Bl -tag -width 24n
1204: .It Pa @sysconfdir@/sudo.conf
1205: .Nm sudo
1206: front end configuration
1207: .El
1208: .Sh EXAMPLES
1209: Note: the following examples assume a properly configured security
1210: policy.
1211: .Pp
1212: To get a file listing of an unreadable directory:
1213: .Bd -literal -offset indent
1214: $ sudo ls /usr/local/protected
1215: .Ed
1216: .Pp
1217: To list the home directory of user yaz on a machine where the file
1218: system holding ~yaz is not exported as root:
1219: .Bd -literal -offset indent
1220: $ sudo -u yaz ls ~yaz
1221: .Ed
1222: .Pp
1223: To edit the
1224: .Pa index.html
1225: file as user www:
1226: .Bd -literal -offset indent
1227: $ sudo -u www vi ~www/htdocs/index.html
1228: .Ed
1229: .Pp
1230: To view system logs only accessible to root and users in the adm
1231: group:
1232: .Bd -literal -offset indent
1233: $ sudo -g adm view /var/log/syslog
1234: .Ed
1235: .Pp
1236: To run an editor as jim with a different primary group:
1237: .Bd -literal -offset indent
1238: $ sudo -u jim -g audio vi ~jim/sound.txt
1239: .Ed
1240: .Pp
1241: To shut down a machine:
1242: .Bd -literal -offset indent
1243: $ sudo shutdown -r +15 "quick reboot"
1244: .Ed
1245: .Pp
1246: To make a usage listing of the directories in the /home partition.
1247: Note that this runs the commands in a sub-shell to make the
1248: .Li cd
1249: and file redirection work.
1250: .Bd -literal -offset indent
1251: $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
1252: .Ed
1253: .Sh SEE ALSO
1254: .Xr grep 1 ,
1255: .Xr su 1 ,
1256: .Xr stat 2 ,
1257: .Xr login_cap 3 ,
1258: .Xr passwd @mansectform@ ,
1259: .Xr sudoers @mansectform@ ,
1260: .Xr sudo_plugin @mansectsu@ ,
1261: .Xr sudoreplay @mansectsu@ ,
1262: .Xr visudo @mansectsu@
1263: .Sh HISTORY
1264: See the HISTORY file in the
1265: .Nm sudo
1266: distribution (http://www.sudo.ws/sudo/history.html) for a brief
1267: history of sudo.
1268: .Sh AUTHORS
1269: Many people have worked on
1270: .Nm sudo
1271: over the years; this version consists of code written primarily by:
1272: .Bd -ragged -offset indent
1273: Todd C. Miller
1274: .Ed
1275: .Pp
1276: See the CONTRIBUTORS file in the
1277: .Nm sudo
1278: distribution (http://www.sudo.ws/sudo/contributors.html) for an
1279: exhaustive list of people who have contributed to
1280: .Nm sudo .
1281: .Sh CAVEATS
1282: There is no easy way to prevent a user from gaining a root shell
1283: if that user is allowed to run arbitrary commands via
1284: .Nm sudo .
1285: Also, many programs (such as editors) allow the user to run commands
1286: via shell escapes, thus avoiding
1287: .Nm sudo Ns No 's
1288: checks.
1289: However, on most systems it is possible to prevent shell escapes with the
1290: .Xr sudoers @mansectform@
1291: plugin's
1292: .Em noexec
1293: functionality.
1294: .Pp
1295: It is not meaningful to run the
1296: .Li cd
1297: command directly via sudo, e.g.,
1298: .Bd -literal -offset indent
1299: $ sudo cd /usr/local/protected
1300: .Ed
1301: .Pp
1302: since when the command exits the parent process (your shell) will
1303: still be the same.
1304: Please see the
1305: .Sx EXAMPLES
1306: section for more information.
1307: .Pp
1308: Running shell scripts via
1309: .Nm sudo
1310: can expose the same kernel bugs that make setuid shell scripts
1311: unsafe on some operating systems (if your OS has a /dev/fd/ directory,
1312: setuid shell scripts are generally safe).
1313: .Sh BUGS
1314: If you feel you have found a bug in
1315: .Nm sudo ,
1316: please submit a bug report at http://www.sudo.ws/sudo/bugs/
1317: .Sh SUPPORT
1318: Limited free support is available via the sudo-users mailing list,
1319: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1320: search the archives.
1321: .Sh DISCLAIMER
1322: .Nm sudo
1323: is provided
1324: .Dq AS IS
1325: and any express or implied warranties, including, but not limited
1326: to, the implied warranties of merchantability and fitness for a
1327: particular purpose are disclaimed.
1328: See the LICENSE file distributed with
1329: .Nm sudo
1330: 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