Annotation of src/usr.bin/sudo/sudo.pod, Revision 1.9
1.6 millert 1: Copyright (c) 1994-1996, 1998-2005, 2007
2: Todd C. Miller <Todd.Miller@courtesan.com>
1.1 millert 3:
4: Permission to use, copy, modify, and distribute this software for any
5: purpose with or without fee is hereby granted, provided that the above
6: copyright notice and this permission notice appear in all copies.
7:
8: THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9: WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10: MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11: ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13: ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14: OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15: ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
16:
17: Sponsored in part by the Defense Advanced Research Projects
18: Agency (DARPA) and Air Force Research Laboratory, Air Force
19: Materiel Command, USAF, under agreement number F39502-99-1-0512.
20:
1.9 ! millert 21: $Sudo: sudo.pod,v 1.70.2.24 2008/02/19 18:22:11 millert Exp $
1.1 millert 22: =pod
23:
24: =head1 NAME
25:
26: sudo, sudoedit - execute a command as another user
27:
28: =head1 SYNOPSIS
29:
30: B<sudo> B<-h> | B<-K> | B<-k> | B<-L> | B<-l> | B<-V> | B<-v>
31:
1.9 ! millert 32: B<sudo> [B<-bEHPS>]
! 33: S<[B<-a> I<auth_type>]>
! 34: S<[B<-c> I<class>|I<->]>
! 35: S<[B<-p> I<prompt>]>
! 36: S<[B<-u> I<username>|I<#uid>]>
1.1 millert 37: S<[B<VAR>=I<value>]> S<{B<-i> | B<-s> | I<command>}>
38:
1.9 ! millert 39: B<sudoedit> [B<-S>]
! 40: S<[B<-a> I<auth_type>]>
! 41: S<[B<-c> I<class>|I<->]>
1.1 millert 42: S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
43: file ...
44:
45: =head1 DESCRIPTION
46:
47: B<sudo> allows a permitted user to execute a I<command> as the
48: superuser or another user, as specified in the I<sudoers> file.
49: The real and effective uid and gid are set to match those of the
50: target user as specified in the passwd file and the group vector
51: is initialized based on the group file (unless the B<-P> option was
52: specified). If the invoking user is root or if the target user is
53: the same as the invoking user, no password is required. Otherwise,
54: B<sudo> requires that users authenticate themselves with a password
55: by default (NOTE: in the default configuration this is the user's
56: password, not the root password). Once a user has been authenticated,
57: a timestamp is updated and the user may then use sudo without a
58: password for a short period of time (C<@timeout@> minutes unless
59: overridden in I<sudoers>).
60:
61: When invoked as B<sudoedit>, the B<-e> option (described below),
62: is implied.
63:
64: B<sudo> determines who is an authorized user by consulting the file
65: F<@sysconfdir@/sudoers>. By giving B<sudo> the B<-v> flag, a user
1.6 millert 66: can update the time stamp without running a I<command>. The password
1.1 millert 67: prompt itself will also time out if the user's password is not
68: entered within C<@password_timeout@> minutes (unless overridden via
69: I<sudoers>).
70:
71: If a user who is not listed in the I<sudoers> file tries to run a
72: command via B<sudo>, mail is sent to the proper authorities, as
73: defined at configure time or in the I<sudoers> file (defaults to
74: C<@mailto@>). Note that the mail will not be sent if an unauthorized
75: user tries to run sudo with the B<-l> or B<-v> flags. This allows
76: users to determine for themselves whether or not they are allowed
77: to use B<sudo>.
78:
79: If B<sudo> is run by root and the C<SUDO_USER> environment variable
80: is set, B<sudo> will use this value to determine who the actual
81: user is. This can be used by a user to log commands through sudo
82: even when a root shell has been invoked. It also allows the B<-e>
83: flag to remain useful even when being run via a sudo-run script or
84: program. Note however, that the sudoers lookup is still done for
85: root, not the user specified by C<SUDO_USER>.
86:
87: B<sudo> can log both successful and unsuccessful attempts (as well
88: as errors) to syslog(3), a log file, or both. By default B<sudo>
89: will log via syslog(3) but this is changeable at configure time
90: or via the I<sudoers> file.
91:
92: =head1 OPTIONS
93:
94: B<sudo> accepts the following command line options:
95:
96: =over 4
97:
98: =item -a
99:
100: The B<-a> (I<authentication type>) option causes B<sudo> to use the
101: specified authentication type when validating the user, as allowed
1.6 millert 102: by F</etc/login.conf>. The system administrator may specify a list
1.1 millert 103: of sudo-specific authentication methods by adding an "auth-sudo"
1.6 millert 104: entry in F</etc/login.conf>. This option is only available on systems
1.1 millert 105: that support BSD authentication.
106:
107: =item -b
108:
109: The B<-b> (I<background>) option tells B<sudo> to run the given
110: command in the background. Note that if you use the B<-b>
111: option you cannot use shell job control to manipulate the process.
112:
113: =item -c
114:
115: The B<-c> (I<class>) option causes B<sudo> to run the specified command
116: with resources limited by the specified login class. The I<class>
117: argument can be either a class name as defined in C</etc/login.conf>,
118: or a single '-' character. Specifying a I<class> of C<-> indicates
119: that the command should be run restricted by the default login
120: capabilities for the user the command is run as. If the I<class>
121: argument specifies an existing user class, the command must be run
122: as root, or the B<sudo> command must be run from a shell that is already
123: root. This option is only available on systems with BSD login classes.
124:
125: =item -E
126:
1.6 millert 127: The B<-E> (I<preserve> I<environment>) option will override the
1.1 millert 128: I<env_reset> option in L<sudoers(5)>). It is only
129: available when either the matching command has the C<SETENV> tag
130: or the I<setenv> option is set in L<sudoers(5)>.
131:
132: =item -e
133:
134: The B<-e> (I<edit>) option indicates that, instead of running
135: a command, the user wishes to edit one or more files. In lieu
136: of a command, the string "sudoedit" is used when consulting
137: the I<sudoers> file. If the user is authorized by I<sudoers>
138: the following steps are taken:
139:
1.6 millert 140: =over 4
1.1 millert 141:
142: =item 1.
143:
144: Temporary copies are made of the files to be edited with the owner
145: set to the invoking user.
146:
147: =item 2.
148:
149: The editor specified by the C<VISUAL> or C<EDITOR> environment
150: variables is run to edit the temporary files. If neither C<VISUAL>
151: nor C<EDITOR> are set, the program listed in the I<editor> I<sudoers>
152: variable is used.
153:
154: =item 3.
155:
156: If they have been modified, the temporary files are copied back to
157: their original location and the temporary versions are removed.
158:
159: =back
160:
161: If the specified file does not exist, it will be created. Note
162: that unlike most commands run by B<sudo>, the editor is run with
163: the invoking user's environment unmodified. If, for some reason,
164: B<sudo> is unable to update a file with its edited version, the
165: user will receive a warning and the edited copy will remain in a
166: temporary file.
167:
168: =item -H
169:
170: The B<-H> (I<HOME>) option sets the C<HOME> environment variable
171: to the homedir of the target user (root by default) as specified
172: in passwd(5). By default, B<sudo> does not modify C<HOME>
173: (see I<set_home> and I<always_set_home> in L<sudoers(5)>).
174:
175: =item -h
176:
177: The B<-h> (I<help>) option causes B<sudo> to print a usage message and exit.
178:
179: =item -i
180:
181: The B<-i> (I<simulate initial login>) option runs the shell specified
182: in the L<passwd(5)> entry of the user that the command is
183: being run as. The command name argument given to the shell begins
184: with a `C<->' to tell the shell to run as a login shell. B<sudo>
185: attempts to change to that user's home directory before running the
186: shell. It also initializes the environment, leaving I<TERM>
187: unchanged, setting I<HOME>, I<SHELL>, I<USER>, I<LOGNAME>, and
188: I<PATH>, and unsetting all other environment variables. Note that
189: because the shell to use is determined before the I<sudoers> file
190: is parsed, a I<runas_default> setting in I<sudoers> will specify
191: the user to run the shell as but will not affect which shell is
192: actually run.
193:
194: =item -K
195:
196: The B<-K> (sure I<kill>) option is like B<-k> except that it removes
197: the user's timestamp entirely. Like B<-k>, this option does not
198: require a password.
199:
200: =item -k
201:
202: The B<-k> (I<kill>) option to B<sudo> invalidates the user's timestamp
203: by setting the time on it to the Epoch. The next time B<sudo> is
204: run a password will be required. This option does not require a password
205: and was added to allow a user to revoke B<sudo> permissions from a .logout
206: file.
207:
208: =item -L
209:
210: The B<-L> (I<list> defaults) option will list out the parameters
211: that may be set in a I<Defaults> line along with a short description
212: for each. This option is useful in conjunction with L<grep(1)>.
213:
214: =item -l
215:
216: The B<-l> (I<list>) option will list out the allowed (and
217: forbidden) commands for the invoking user on the current host.
218:
219: =item -P
220:
1.6 millert 221: The B<-P> (I<preserve> I<group vector>) option causes B<sudo> to
1.1 millert 222: preserve the invoking user's group vector unaltered. By default,
223: B<sudo> will initialize the group vector to the list of groups the
224: target user is in. The real and effective group IDs, however, are
225: still set to match the target user.
226:
227: =item -p
228:
229: The B<-p> (I<prompt>) option allows you to override the default
230: password prompt and use a custom one. The following percent (`C<%>')
231: escapes are supported:
232:
1.6 millert 233: =over 4
1.1 millert 234:
235: =item C<%H>
236:
237: expanded to the local hostname including the domain name
238: (on if the machine's hostname is fully qualified or the I<fqdn>
239: I<sudoers> option is set)
240:
241: =item C<%h>
242:
243: expanded to the local hostname without the domain name
1.8 millert 244:
245: =item C<%p>
246:
247: expanded to the user whose password is being asked for (respects the
248: I<rootpw>, I<targetpw> and I<runaspw> flags in I<sudoers>)
1.1 millert 249:
250: =item C<%U>
251:
252: expanded to the login name of the user the command will
253: be run as (defaults to root)
254:
255: =item C<%u>
256:
257: expanded to the invoking user's login name
258:
259: =item C<%%>
260:
261: two consecutive C<%> characters are collapsed into a single C<%> character
262:
263: =back
264:
265: =item -S
266:
267: The B<-S> (I<stdin>) option causes B<sudo> to read the password from
268: the standard input instead of the terminal device.
269:
270: =item -s
271:
272: The B<-s> (I<shell>) option runs the shell specified by the I<SHELL>
273: environment variable if it is set or the shell as specified
274: in L<passwd(5)>.
275:
276: =item -u
277:
1.6 millert 278: The B<-u> (I<user>) option causes B<sudo> to run the specified
279: command as a user other than I<root>. To specify a I<uid> instead
280: of a I<username>, use I<#uid>. When running commands as a I<uid>,
281: many shells require that the '#' be escaped with a backslash ('\').
282: Note that if the I<targetpw> Defaults option is set (see L<sudoers(5)>)
283: it is not possible to run commands with a uid not listed in the
284: password database.
1.1 millert 285:
286: =item -V
287:
288: The B<-V> (I<version>) option causes B<sudo> to print the version
289: number and exit. If the invoking user is already root the B<-V>
290: option will print out a list of the defaults B<sudo> was compiled
291: with as well as the machine's local network addresses.
292:
293: =item -v
294:
295: If given the B<-v> (I<validate>) option, B<sudo> will update the
296: user's timestamp, prompting for the user's password if necessary.
297: This extends the B<sudo> timeout for another C<@timeout@> minutes
298: (or whatever the timeout is set to in I<sudoers>) but does not run
299: a command.
300:
301: =item --
302:
303: The B<--> flag indicates that B<sudo> should stop processing command
304: line arguments. It is most useful in conjunction with the B<-s> flag.
305:
306: =back
307:
308: Environment variables to be set for the command may also be passed
309: on the command line in the form of B<VAR>=I<value>, e.g.
310: B<LD_LIBRARY_PATH>=I</usr/local/pkg/lib>. Variables passed on the
311: command line are subject to the same restrictions as normal environment
312: variables with one important exception. If the I<setenv> option
1.7 millert 313: is set in I<sudoers>, the command to be run has the C<SETENV> tag
314: set or the command matched is C<ALL>, the user may set variables
315: that would overwise be forbidden. See L<sudoers(5)> for more information.
1.1 millert 316:
317: =head1 RETURN VALUES
318:
319: Upon successful execution of a program, the return value from B<sudo>
320: will simply be the return value of the program that was executed.
321:
322: Otherwise, B<sudo> quits with an exit value of 1 if there is a
323: configuration/permission problem or if B<sudo> cannot execute the
324: given command. In the latter case the error string is printed to
325: stderr. If B<sudo> cannot L<stat(2)> one or more entries in the user's
326: C<PATH> an error is printed on stderr. (If the directory does not
327: exist or if it is not really a directory, the entry is ignored and
328: no error is printed.) This should not happen under normal
329: circumstances. The most common reason for L<stat(2)> to return
330: "permission denied" is if you are running an automounter and one
331: of the directories in your C<PATH> is on a machine that is currently
332: unreachable.
333:
334: =head1 SECURITY NOTES
335:
336: B<sudo> tries to be safe when executing external commands.
337:
338: There are two distinct ways to deal with environment variables.
339: By default, the I<env_reset> I<sudoers> option is enabled.
340: This causes commands to be executed with a minimal environment
341: containing C<TERM>, C<PATH>, C<HOME>, C<SHELL>, C<LOGNAME>, C<USER>
342: and C<USERNAME> in addition to variables from the invoking process
343: permitted by the I<env_check> and I<env_keep> I<sudoers> options.
344: There is effectively a whitelist for environment variables.
345:
346: If, however, the I<env_reset> option is disabled in I<sudoers>, any
347: variables not explicitly denied by the I<env_check> and I<env_delete>
348: options are inherited from the invoking process. In this case,
349: I<env_check> and I<env_delete> behave like a blacklist. Since it
350: is not possible to blacklist all potentially dangerous environment
351: variables, use of the default I<env_reset> behavior is encouraged.
352:
353: In all cases, environment variables with a value beginning with
354: C<()> are removed as they could be interpreted as B<bash> functions.
355: The list of environment variables that B<sudo> allows or denies is
356: contained in the output of C<sudo -V> when run as root.
357:
358: Note that the dynamic linker on most operating systems will remove
359: variables that can control dynamic linking from the environment of
360: setuid executables, including B<sudo>. Depending on the operating
361: system this may include C<_RLD*>, C<DYLD_*>, C<LD_*>, C<LDR_*>,
362: C<LIBPATH>, C<SHLIB_PATH>, and others. These type of variables are
363: removed from the environment before B<sudo> even begins execution
364: and, as such, it is not possible for B<sudo> to preserve them.
365:
366: To prevent command spoofing, B<sudo> checks "." and "" (both denoting
367: current directory) last when searching for a command in the user's
368: PATH (if one or both are in the PATH). Note, however, that the
369: actual C<PATH> environment variable is I<not> modified and is passed
370: unchanged to the program that B<sudo> executes.
371:
372: B<sudo> will check the ownership of its timestamp directory
373: (F<@timedir@> by default) and ignore the directory's contents if
374: it is not owned by root or if it is writable by a user other than
375: root. On systems that allow non-root users to give away files via
376: L<chown(2)>, if the timestamp directory is located in a directory
377: writable by anyone (e.g., F</tmp>), it is possible for a user to
378: create the timestamp directory before B<sudo> is run. However,
379: because B<sudo> checks the ownership and mode of the directory and
380: its contents, the only damage that can be done is to "hide" files
381: by putting them in the timestamp dir. This is unlikely to happen
382: since once the timestamp dir is owned by root and inaccessible by
383: any other user, the user placing files there would be unable to get
384: them back out. To get around this issue you can use a directory
385: that is not world-writable for the timestamps (F</var/adm/sudo> for
386: instance) or create F<@timedir@> with the appropriate owner (root)
387: and permissions (0700) in the system startup files.
388:
389: B<sudo> will not honor timestamps set far in the future.
390: Timestamps with a date greater than current_time + 2 * C<TIMEOUT>
391: will be ignored and sudo will log and complain. This is done to
392: keep a user from creating his/her own timestamp with a bogus
393: date on systems that allow users to give away files.
394:
395: Please note that B<sudo> will normally only log the command it
396: explicitly runs. If a user runs a command such as C<sudo su> or
397: C<sudo sh>, subsequent commands run from that shell will I<not> be
398: logged, nor will B<sudo>'s access control affect them. The same
399: is true for commands that offer shell escapes (including most
400: editors). Because of this, care must be taken when giving users
401: access to commands via B<sudo> to verify that the command does not
402: inadvertently give the user an effective root shell. For more
403: information, please see the C<PREVENTING SHELL ESCAPES> section in
404: L<sudoers(5)>.
405:
406: =head1 ENVIRONMENT
407:
408: B<sudo> utilizes the following environment variables:
409:
1.6 millert 410: =over 16
411:
412: =item C<EDITOR>
413:
414: Default editor to use in B<-e> (sudoedit) mode if C<VISUAL> is not set
415:
416: =item C<HOME>
417:
418: In B<-s> or B<-H> mode (or if sudo was configured with the
419: --enable-shell-sets-home option), set to homedir of the target user
420:
421: =item C<PATH>
422:
423: Set to a sane value if the I<secure_path> sudoers option is set.
424:
425: =item C<SHELL>
1.1 millert 426:
1.6 millert 427: Used to determine shell to run with C<-s> option
1.1 millert 428:
1.6 millert 429: =item C<SUDO_PROMPT>
1.1 millert 430:
1.6 millert 431: Used as the default password prompt
1.1 millert 432:
1.6 millert 433: =item C<SUDO_COMMAND>
1.1 millert 434:
1.6 millert 435: Set to the command run by sudo
1.1 millert 436:
1.6 millert 437: =item C<SUDO_USER>
1.1 millert 438:
1.6 millert 439: Set to the login of the user who invoked sudo
1.1 millert 440:
1.6 millert 441: =item C<SUDO_UID>
1.1 millert 442:
1.6 millert 443: Set to the uid of the user who invoked sudo
1.1 millert 444:
1.6 millert 445: =item C<SUDO_GID>
1.1 millert 446:
1.6 millert 447: Set to the gid of the user who invoked sudo
448:
449: =item C<SUDO_PS1>
450:
451: If set, C<PS1> will be set to its value
452:
453: =item C<USER>
454:
455: Set to the target user (root unless the B<-u> option is specified)
456:
457: =item C<VISUAL>
458:
459: Default editor to use in B<-e> (sudoedit) mode
460:
461: =back
1.1 millert 462:
463: =head1 FILES
464:
1.9 ! millert 465: =over 24
! 466:
! 467: =item F<@sysconfdir@/sudoers>
! 468:
! 469: List of who can run what
1.5 millert 470:
1.9 ! millert 471: =item F<@timedir@>
1.4 millert 472:
1.9 ! millert 473: Directory containing timestamps
1.5 millert 474:
475: =back
1.1 millert 476:
477: =head1 EXAMPLES
478:
479: Note: the following examples assume suitable L<sudoers(5)> entries.
480:
481: To get a file listing of an unreadable directory:
482:
483: $ sudo ls /usr/local/protected
484:
485: To list the home directory of user yazza on a machine where the
486: file system holding ~yazza is not exported as root:
487:
488: $ sudo -u yazza ls ~yazza
489:
490: To edit the F<index.html> file as user www:
491:
492: $ sudo -u www vi ~www/htdocs/index.html
493:
494: To shutdown a machine:
495:
496: $ sudo shutdown -r +15 "quick reboot"
497:
498: To make a usage listing of the directories in the /home
499: partition. Note that this runs the commands in a sub-shell
500: to make the C<cd> and file redirection work.
501:
502: $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
503:
504: =head1 SEE ALSO
505:
1.9 ! millert 506: L<grep(1)>, L<su(1)>, L<stat(2)>,
! 507: L<login_cap(3)>,
! 508: L<passwd(5)>, L<sudoers(5)>, L<visudo(8)>
1.1 millert 509:
510: =head1 AUTHORS
511:
512: Many people have worked on B<sudo> over the years; this
513: version consists of code written primarily by:
514:
515: Todd C. Miller
516: Chris Jepeway
517:
518: See the HISTORY file in the B<sudo> distribution or visit
519: http://www.sudo.ws/sudo/history.html for a short history
520: of B<sudo>.
521:
522: =head1 CAVEATS
523:
524: There is no easy way to prevent a user from gaining a root shell
525: if that user is allowed to run arbitrary commands via B<sudo>.
526: Also, many programs (such as editors) allow the user to run commands
527: via shell escapes, thus avoiding B<sudo>'s checks. However, on
528: most systems it is possible to prevent shell escapes with B<sudo>'s
529: I<noexec> functionality. See the L<sudoers(5)> manual
530: for details.
531:
532: It is not meaningful to run the C<cd> command directly via sudo, e.g.,
533:
534: $ sudo cd /usr/local/protected
535:
536: since when the command exits the parent process (your shell) will
537: still be the same. Please see the EXAMPLES section for more information.
538:
539: If users have sudo C<ALL> there is nothing to prevent them from
540: creating their own program that gives them a root shell regardless
541: of any '!' elements in the user specification.
542:
543: Running shell scripts via B<sudo> can expose the same kernel bugs that
544: make setuid shell scripts unsafe on some operating systems (if your OS
545: has a /dev/fd/ directory, setuid shell scripts are generally safe).
546:
547: =head1 BUGS
548:
549: If you feel you have found a bug in B<sudo>, please submit a bug report
550: at http://www.sudo.ws/sudo/bugs/
551:
552: =head1 SUPPORT
553:
554: Limited free support is available via the sudo-users mailing list,
555: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
556: search the archives.
557:
558: =head1 DISCLAIMER
559:
560: B<sudo> is provided ``AS IS'' and any express or implied warranties,
561: including, but not limited to, the implied warranties of merchantability
562: and fitness for a particular purpose are disclaimed. See the LICENSE
563: file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
564: for complete details.
![[BACK]](/icons/back.gif){kind=icon}
Return to sudo.pod CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / sudo