0337a4db6ddb8e209472079185066bbfb9bf3b45
[debian/sudo] / doc / sudo.mdoc.in
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.