Annotation of src/usr.bin/sudo/sudo.8, Revision 1.2
1.1 millert 1: .rn '' }`
1.2 ! millert 2: ''' $RCSfile: sudo.man,v $$Revision: 1.43 $$Date: 2000/01/17 17:28:41 $
1.1 millert 3: '''
4: ''' $Log: sudo.man,v $
1.2 ! millert 5: ''' Revision 1.43 2000/01/17 17:28:41 millert
! 6: ''' Crank version to 1.6.2
1.1 millert 7: '''
8: '''
9: .de Sh
10: .br
11: .if t .Sp
12: .ne 5
13: .PP
14: \fB\\$1\fR
15: .PP
16: ..
17: .de Sp
18: .if t .sp .5v
19: .if n .sp
20: ..
21: .de Ip
22: .br
23: .ie \\n(.$>=3 .ne \\$3
24: .el .ne 3
25: .IP "\\$1" \\$2
26: ..
27: .de Vb
28: .ft CW
29: .nf
30: .ne \\$1
31: ..
32: .de Ve
33: .ft R
34:
35: .fi
36: ..
37: '''
38: '''
39: ''' Set up \*(-- to give an unbreakable dash;
40: ''' string Tr holds user defined translation string.
41: ''' Bell System Logo is used as a dummy character.
42: '''
43: .tr \(*W-|\(bv\*(Tr
44: .ie n \{\
45: .ds -- \(*W-
46: .ds PI pi
47: .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
48: .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
49: .ds L" ""
50: .ds R" ""
51: ''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
52: ''' \*(L" and \*(R", except that they are used on ".xx" lines,
53: ''' such as .IP and .SH, which do another additional levels of
54: ''' double-quote interpretation
55: .ds M" """
56: .ds S" """
57: .ds N" """""
58: .ds T" """""
59: .ds L' '
60: .ds R' '
61: .ds M' '
62: .ds S' '
63: .ds N' '
64: .ds T' '
65: 'br\}
66: .el\{\
67: .ds -- \(em\|
68: .tr \*(Tr
69: .ds L" ``
70: .ds R" ''
71: .ds M" ``
72: .ds S" ''
73: .ds N" ``
74: .ds T" ''
75: .ds L' `
76: .ds R' '
77: .ds M' `
78: .ds S' '
79: .ds N' `
80: .ds T' '
81: .ds PI \(*p
82: 'br\}
83: .\" If the F register is turned on, we'll generate
84: .\" index entries out stderr for the following things:
85: .\" TH Title
86: .\" SH Header
87: .\" Sh Subsection
88: .\" Ip Item
89: .\" X<> Xref (embedded
90: .\" Of course, you have to process the output yourself
91: .\" in some meaninful fashion.
92: .if \nF \{
93: .de IX
94: .tm Index:\\$1\t\\n%\t"\\$2"
95: ..
96: .nr % 0
97: .rr F
98: .\}
1.2 ! millert 99: .TH sudo 8 "1.6.2" "4/Dec/1999" "MAINTENANCE COMMANDS"
1.1 millert 100: .UC
101: .if n .hy 0
102: .if n .na
103: .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
104: .de CQ \" put $1 in typewriter font
105: .ft CW
106: 'if n "\c
107: 'if t \\&\\$1\c
108: 'if n \\&\\$1\c
109: 'if n \&"
110: \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
111: '.ft R
112: ..
113: .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
114: . \" AM - accent mark definitions
115: .bd B 3
116: . \" fudge factors for nroff and troff
117: .if n \{\
118: . ds #H 0
119: . ds #V .8m
120: . ds #F .3m
121: . ds #[ \f1
122: . ds #] \fP
123: .\}
124: .if t \{\
125: . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
126: . ds #V .6m
127: . ds #F 0
128: . ds #[ \&
129: . ds #] \&
130: .\}
131: . \" simple accents for nroff and troff
132: .if n \{\
133: . ds ' \&
134: . ds ` \&
135: . ds ^ \&
136: . ds , \&
137: . ds ~ ~
138: . ds ? ?
139: . ds ! !
140: . ds /
141: . ds q
142: .\}
143: .if t \{\
144: . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
145: . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
146: . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
147: . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
148: . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
149: . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
150: . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
151: . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
152: . ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
153: .\}
154: . \" troff and (daisy-wheel) nroff accents
155: .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
156: .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
157: .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
158: .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
159: .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
160: .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
161: .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
162: .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
163: .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
164: .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
165: .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
166: .ds ae a\h'-(\w'a'u*4/10)'e
167: .ds Ae A\h'-(\w'A'u*4/10)'E
168: .ds oe o\h'-(\w'o'u*4/10)'e
169: .ds Oe O\h'-(\w'O'u*4/10)'E
170: . \" corrections for vroff
171: .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
172: .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
173: . \" for low resolution devices (crt and lpr)
174: .if \n(.H>23 .if \n(.V>19 \
175: \{\
176: . ds : e
177: . ds 8 ss
178: . ds v \h'-1'\o'\(aa\(ga'
179: . ds _ \h'-1'^
180: . ds . \h'-1'.
181: . ds 3 3
182: . ds o a
183: . ds d- d\h'-1'\(ga
184: . ds D- D\h'-1'\(hy
185: . ds th \o'bp'
186: . ds Th \o'LP'
187: . ds ae ae
188: . ds Ae AE
189: . ds oe oe
190: . ds Oe OE
191: .\}
192: .rm #[ #] #H #V #F C
193: .SH "NAME"
194: sudo \- execute a command as another user
195: .SH "SYNOPSIS"
196: \fBsudo\fR \fB\-V\fR | \fB\-h\fR | \fB\-l\fR | \fB\-L\fR | \fB\-v\fR | \fB\-k\fR | \fB\-K\fR | \fB\-s\fR | \fB\-H\fR |
197: [ \fB\-b\fR ] | [ \fB\-p\fR prompt ] [ \fB\-u\fR username/#uid] \fIcommand\fR
198: .SH "DESCRIPTION"
199: \fBsudo\fR allows a permitted user to execute a \fIcommand\fR as the
200: superuser or another user, as specified in the sudoers file. The
201: real and effective uid and gid are set to match those of the target
202: user as specified in the passwd file (the group vector is also
1.2 ! millert 203: initialized when the target user is not root). By default, \fBsudo\fR
! 204: requires that users authenticate themselves with a password
! 205: (NOTE: this is the user's password, not the root password). Once
! 206: a user has been authenticated, a timestamp is updated and the
! 207: user may then use sudo without a password for a short period of time
! 208: (five minutes by default).
1.1 millert 209: .PP
210: \fBsudo\fR determines who is an authorized user by consulting the
211: file \fI/etc/sudoers\fR. By giving \fBsudo\fR the \f(CW-v\fR flag a user
212: can update the time stamp without running a \fIcommand.\fR
213: The password prompt itself will also time out if the user's password is
214: not entered with N minutes (again, this is defined at configure
215: time and defaults to 5 minutes).
216: .PP
217: If a user that is not listed in the \fIsudoers\fR file tries to run
218: a command via \fBsudo\fR, mail is sent to the proper authorities,
219: as defined at configure time (defaults to root). Note that the
220: mail will not be sent if an unauthorized user tries to run sudo
221: with the \f(CW-l\fR or \f(CW-v\fR flags. This allows users to determine
222: for themselves whether or not they are allowed to use \fBsudo\fR.
223: .PP
224: \fBsudo\fR can log both successful an unsuccessful attempts (as well
225: as errors) to \fIsyslog\fR\|(3), a log file, or both. By default \fBsudo\fR
226: will log via \fIsyslog\fR\|(3) but this is changeable at configure time.
227: .SH "OPTIONS"
228: \fBsudo\fR accepts the following command line options:
229: .Ip "-V" 4
230: The \f(CW-V\fR (\fIversion\fR) option causes \fBsudo\fR to print the
231: version number and exit.
232: .Ip "-l" 4
233: The \f(CW-l\fR (\fIlist\fR) option will list out the allowed (and
234: forbidden) commands for the user on the current host.
235: .Ip "-L" 4
236: The \f(CW-L\fR (\fIlist\fR defaults) option will list out the parameters
237: that may be set in a \fIDefaults\fR line along with a short description
238: for each. This option is useful in conjunction with \fIgrep\fR\|(1).
239: .Ip "-h" 4
240: The \f(CW-h\fR (\fIhelp\fR) option causes \fBsudo\fR to print a usage message and exit.
241: .Ip "-v" 4
242: If given the \f(CW-v\fR (\fIvalidate\fR) option, \fBsudo\fR will update the
243: user's timestamp, prompting for the user's password if necessary.
244: This extends the \fBsudo\fR timeout to for another N minutes
245: (where N is defined at installation time and defaults to 5
246: minutes) but does not run a command.
247: .Ip "-k" 4
248: The \f(CW-k\fR (\fIkill\fR) option to \fBsudo\fR invalidates the user's timestamp
249: by setting the time on it to the epoch. The next time \fBsudo\fR is
250: run a password will be required. This option does not require a password
251: and was added to allow a user to revoke \fBsudo\fR permissions from a .logout
252: file.
253: .Ip "-K" 4
254: The \f(CW-K\fR (sure \fIkill\fR) option to \fBsudo\fR removes the user's timestamp
255: entirely. This option does not require a password.
256: .Ip "-b" 4
257: The \f(CW-b\fR (\fIbackground\fR) option tells \fBsudo\fR to run the given
258: command in the background. Note that if you use the \f(CW-b\fR
259: option you cannot use shell job control to manipulate the command.
260: .Ip "-p" 4
261: The \f(CW-p\fR (\fIprompt\fR) option allows you to override the default
262: password prompt and use a custom one. If the password prompt
263: contains the \f(CW%u\fR escape, \f(CW%u\fR will be replaced with the user's
264: login name. Similarly, \f(CW%h\fR will be replaced with the local
265: hostname.
266: .Ip "-u" 4
267: The \f(CW-u\fR (\fIuser\fR) option causes sudo to run the specified command
268: as a user other than \fIroot\fR. To specify a \fIuid\fR instead of a
269: \fIusername\fR, use \*(L"#uid\*(R".
270: .Ip "-s" 4
271: The \f(CW-s\fR (\fIshell\fR) option runs the shell specified by the \fI\s-1SHELL\s0\fR
272: environment variable if it is set or the shell as specified
273: in \fIpasswd\fR\|(5).
274: .Ip "-H" 4
275: The \f(CW-H\fR (\fI\s-1HOME\s0\fR) option sets the \fI\s-1HOME\s0\fR environment variable
276: to the homedir of the target user (root by default) as specified
277: in \fIpasswd\fR\|(5). By default, \fBsudo\fR does not modify \fI\s-1HOME\s0\fR.
278: .Ip "--" 4
279: The \f(CW--\fR flag indicates that \fBsudo\fR should stop processing command
280: line arguments. It is most useful in conjunction with the \f(CW-s\fR flag.
281: .SH "RETURN VALUES"
282: \fBsudo\fR quits with an exit value of 1 if there is a
283: configuration/permission problem or if \fBsudo\fR cannot execute the
284: given command. In the latter case the error string is printed to
285: stderr. If \fBsudo\fR cannot \fIstat\fR\|(2) one or more entries in the user's
286: \f(CWPATH\fR an error is printed on stderr. (If the directory does not
287: exist or if it is not really a directory, the entry is ignored and
288: no error is printed.) This should not happen under normal
289: circumstances. The most common reason for \fIstat\fR\|(2) to return
290: \*(L"permission denied\*(R" is if you are running an automounter and one
291: of the directories in your \f(CWPATH\fR is on a machine that is currently
292: unreachable.
293: .SH "SECURITY NOTES"
294: \fBsudo\fR tries to be safe when executing external commands. Variables
295: that control how dynamic loading and binding is done can be used
296: to subvert the program that \fBsudo\fR runs. To combat this the
297: \f(CWLD_*\fR, \f(CW_RLD_*\fR, \f(CWSHLIB_PATH\fR (HP\-UX only), and \f(CWLIBPATH\fR (AIX
298: only) environment variables are removed from the environment passed
299: on to all commands executed. \fBsudo\fR will also remove the \f(CWIFS\fR,
300: \f(CWENV\fR, \f(CWBASH_ENV\fR, \f(CWKRB_CONF\fR, \f(CWKRB5_CONFIG\fR, \f(CWLOCALDOMAIN\fR,
301: \f(CWRES_OPTIONS\fR and \f(CWHOSTALIASES\fR variables as they too can pose a
302: threat.
303: .PP
304: To prevent command spoofing, \fBsudo\fR checks "." and "" (both denoting
305: current directory) last when searching for a command in the user's
306: PATH (if one or both are in the PATH). Note, however, that the
307: actual \f(CWPATH\fR environment variable is \fInot\fR modified and is passed
308: unchanged to the program that \fBsudo\fR executes.
309: .PP
310: For security reasons, if your OS supports shared libraries and does
311: not disable user-defined library search paths for setuid programs
312: (most do), you should either use a linker option that disables this
313: behavior or link \fBsudo\fR statically.
314: .PP
315: \fBsudo\fR will check the ownership of its timestamp directory
316: (\fI/var/run/sudo\fR or \fI/tmp/.odus\fR by default) and ignore the
317: directory's contents if it is not owned by root and only writable
318: by root. On systems that allow non-root users to give away files
319: via \fIchown\fR\|(2), if the timestamp directory is located in a directory
320: writable by anyone (ie: \fI/tmp\fR), it is possible for a user to
321: create the timestamp directory before \fBsudo\fR is run. However,
322: because \fBsudo\fR checks the ownership and mode of the directory and
323: its contents, the only damage that can be done is to \*(L"hide\*(R" files
324: by putting them in the timestamp dir. This is unlikely to happen
325: since once the timestamp dir is owned by root and inaccessible by
326: any other user the user placing files there would be unable to get
327: them back out. To get around this issue you can use a directory
328: that is not world-writable for the timestamps (\fI/var/adm/sudo\fR for
329: instance) or create /tmp/.odus with the appropriate owner (root)
330: and permissions (0700) in the system startup files.
331: .PP
332: \fBsudo\fR will not honor timestamps set far in the future.
333: Timestamps with a date greater than current_time + 2 * \f(CWTIMEOUT\fR
334: will be ignored and sudo will log and complain. This is done to
335: keep a user from creating his/her own timestamp with a bogus
336: date on system that allow users to give away files.
337: .SH "EXAMPLES"
338: Note: the following examples assume suitable \fIsudoers\fR\|(5) entries.
339: .PP
340: To get a file listing of an unreadable directory:
341: .PP
342: .Vb 1
343: \& % sudo ls /usr/local/protected
344: .Ve
345: To list the home directory of user yazza on a machine where the
346: filesystem holding ~yazza is not exported as root:
347: .PP
348: .Vb 1
349: \& % sudo -u yazza ls ~yazza
350: .Ve
351: To edit the \fIindex.html\fR file as user www:
352: .PP
353: .Vb 1
354: \& % sudo -u www vi ~www/htdocs/index.html
355: .Ve
356: To shutdown a machine:
357: .PP
358: .Vb 1
359: \& % sudo shutdown -r +15 "quick reboot"
360: .Ve
361: To make a usage listing of the directories in the /home
362: partition. Note that this runs the commands in a sub-shell
363: to make the \f(CWcd\fR and file redirection work.
364: .PP
365: .Vb 1
366: \& % sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
367: .Ve
368: .SH "ENVIRONMENT"
369: \fBsudo\fR utilizes the following environment variables:
370: .PP
371: .Vb 13
372: \& PATH Set to a sane value if SECURE_PATH is set
373: \& SHELL Used to determine shell to run with -s option
374: \& USER Set to the target user (root unless the -u option
375: \& is specified)
376: \& HOME In -s or -H mode (or if sudo was configured with
377: \& the --enable-shell-sets-home option), set to
378: \& homedir of the target user.
379: \& SUDO_PROMPT Used as the default password prompt
380: \& SUDO_COMMAND Set to the command run by sudo
381: \& SUDO_USER Set to the login of the user who invoked sudo
382: \& SUDO_UID Set to the uid of the user who invoked sudo
383: \& SUDO_GID Set to the gid of the user who invoked sudo
384: \& SUDO_PS1 If set, PS1 will be set to its value
385: .Ve
386: .SH "FILES"
387: .PP
388: .Vb 2
389: \& /etc/sudoers List of who can run what
390: \& /var/run/sudo Directory containing timestamps
391: .Ve
392: \fBsudo\fR utilizes the following environment variables:
393: .PP
394: .Vb 13
395: \& PATH Set to a sane value if SECURE_PATH is set
396: \& SHELL Used to determine shell to run with -s option
397: \& USER Set to the target user (root unless the -u option
398: \& is specified)
399: \& HOME In -s or -H mode (or if sudo was configured with
400: \& the --enable-shell-sets-home option), set to
401: \& homedir of the target user.
402: \& SUDO_PROMPT Used as the default password prompt
403: \& SUDO_COMMAND Set to the command run by sudo
404: \& SUDO_USER Set to the login of the user who invoked sudo
405: \& SUDO_UID Set to the uid of the user who invoked sudo
406: \& SUDO_GID Set to the gid of the user who invoked sudo
407: \& SUDO_PS1 If set, PS1 will be set to its value
408: .Ve
409: .SH "FILES"
410: .PP
411: .Vb 3
412: \& /etc/sudoers List of who can run what
413: \& /var/run/sudo Directory containing timestamps
414: \& /tmp/.odus Same as above if no /var/run exists
415: .Ve
416: .SH "AUTHORS"
417: Many people have worked on \fBsudo\fR over the years, this
418: version consists of code written primarily by:
419: .PP
420: .Vb 2
421: \& Todd Miller
422: \& Chris Jepeway
423: .Ve
424: See the HISTORY file in the \fBsudo\fR distribution for a short history
425: of \fBsudo\fR.
426: .SH "BUGS"
427: If you feel you have found a bug in sudo, please submit a bug report
1.2 ! millert 428: at http://www.courtesan.com/sudo/bugs/
1.1 millert 429: .SH "DISCLAIMER"
430: \fBSudo\fR is provided ``AS IS'\*(R' and any express or implied warranties,
431: including, but not limited to, the implied warranties of merchantability
432: and fitness for a particular purpose are disclaimed.
433: See the LICENSE file distributed with \fBsudo\fR for complete details.
434: .SH "CAVEATS"
435: There is no easy way to prevent a user from gaining a root shell if
436: that user has access to commands allowing shell escapes.
437: .PP
438: If users have sudo \f(CWALL\fR there is nothing to prevent them from creating
439: their own program that gives them a root shell regardless of any \*(L'!\*(R'
440: elements in the user specification.
441: .PP
442: Running shell scripts via \fBsudo\fR can expose the same kernel bugs
443: that make setuid shell scripts unsafe on some operating systems
444: (if your OS supports the /dev/fd/ directory, setuid shell scripts
445: are generally safe).
446: .SH "SEE ALSO"
447: \fIsudoers\fR\|(5), \fIvisudo\fR\|(8), \fIsu\fR\|(1).
448:
449: .rn }` ''
450: .IX Title "sudo 8"
451: .IX Name "sudo - execute a command as another user"
452:
453: .IX Header "NAME"
454:
455: .IX Header "SYNOPSIS"
456:
457: .IX Header "DESCRIPTION"
458:
459: .IX Header "OPTIONS"
460:
461: .IX Item "-V"
462:
463: .IX Item "-l"
464:
465: .IX Item "-L"
466:
467: .IX Item "-h"
468:
469: .IX Item "-v"
470:
471: .IX Item "-k"
472:
473: .IX Item "-K"
474:
475: .IX Item "-b"
476:
477: .IX Item "-p"
478:
479: .IX Item "-u"
480:
481: .IX Item "-s"
482:
483: .IX Item "-H"
484:
485: .IX Item "--"
486:
487: .IX Header "RETURN VALUES"
488:
489: .IX Header "SECURITY NOTES"
490:
491: .IX Header "EXAMPLES"
492:
493: .IX Header "ENVIRONMENT"
494:
495: .IX Header "FILES"
496:
497: .IX Header "FILES"
498:
499: .IX Header "AUTHORS"
500:
501: .IX Header "BUGS"
502:
503: .IX Header "DISCLAIMER"
504:
505: .IX Header "CAVEATS"
506:
507: .IX Header "SEE ALSO"
508: