Annotation of src/usr.bin/sudo/sudo.8, Revision 1.18
1.13 millert 1: .\" Copyright (c) 1994-1996,1998-2003 Todd C. Miller <Todd.Miller@courtesan.com>
2: .\"
1.14 millert 3: .\" Permission to use, copy, modify, and distribute this software for any
4: .\" purpose with or without fee is hereby granted, provided that the above
5: .\" copyright notice and this permission notice appear in all copies.
1.13 millert 6: .\"
1.14 millert 7: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.13 millert 15: .\"
1.14 millert 16: .\" Sponsored in part by the Defense Advanced Research Projects
17: .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
18: .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
1.13 millert 19: .\"
1.14 millert 20: .\" $Sudo: sudo.man.in,v 1.31 2004/09/08 18:35:53 millert Exp $
21: .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
1.11 millert 22: .\"
1.7 millert 23: .\" Standard preamble:
1.13 millert 24: .\" ========================================================================
1.7 millert 25: .de Sh \" Subsection heading
1.1 millert 26: .br
27: .if t .Sp
28: .ne 5
29: .PP
30: \fB\\$1\fR
31: .PP
32: ..
1.7 millert 33: .de Sp \" Vertical space (when we can't use .PP)
1.1 millert 34: .if t .sp .5v
35: .if n .sp
36: ..
1.7 millert 37: .de Vb \" Begin verbatim text
1.1 millert 38: .ft CW
39: .nf
40: .ne \\$1
41: ..
1.7 millert 42: .de Ve \" End verbatim text
1.1 millert 43: .ft R
44: .fi
45: ..
1.7 millert 46: .\" Set up some character translations and predefined strings. \*(-- will
47: .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
48: .\" double quote, and \*(R" will give a right double quote. | will give a
1.13 millert 49: .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
50: .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
51: .\" expand to `' in nroff, nothing in troff, for use with C<>.
1.1 millert 52: .tr \(*W-|\(bv\*(Tr
1.7 millert 53: .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
1.1 millert 54: .ie n \{\
1.7 millert 55: . ds -- \(*W-
56: . ds PI pi
57: . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
58: . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
59: . ds L" ""
60: . ds R" ""
61: . ds C`
62: . ds C'
1.1 millert 63: 'br\}
64: .el\{\
1.7 millert 65: . ds -- \|\(em\|
66: . ds PI \(*p
67: . ds L" ``
68: . ds R" ''
1.1 millert 69: 'br\}
1.7 millert 70: .\"
1.13 millert 71: .\" If the F register is turned on, we'll generate index entries on stderr for
72: .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
73: .\" entries marked with X<> in POD. Of course, you'll have to process the
74: .\" output yourself in some meaningful fashion.
1.7 millert 75: .if \nF \{\
76: . de IX
77: . tm Index:\\$1\t\\n%\t"\\$2"
1.1 millert 78: ..
1.7 millert 79: . nr % 0
80: . rr F
1.1 millert 81: .\}
1.7 millert 82: .\"
1.13 millert 83: .\" For nroff, turn off justification. Always turn off hyphenation; it makes
84: .\" way too many mistakes in technical documents.
1.7 millert 85: .hy 0
1.1 millert 86: .if n .na
1.7 millert 87: .\"
88: .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
89: .\" Fear. Run. Save yourself. No user-serviceable parts.
90: . \" fudge factors for nroff and troff
1.1 millert 91: .if n \{\
1.7 millert 92: . ds #H 0
93: . ds #V .8m
94: . ds #F .3m
95: . ds #[ \f1
96: . ds #] \fP
1.1 millert 97: .\}
98: .if t \{\
1.7 millert 99: . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
100: . ds #V .6m
101: . ds #F 0
102: . ds #[ \&
103: . ds #] \&
1.1 millert 104: .\}
1.7 millert 105: . \" simple accents for nroff and troff
1.1 millert 106: .if n \{\
1.7 millert 107: . ds ' \&
108: . ds ` \&
109: . ds ^ \&
110: . ds , \&
111: . ds ~ ~
112: . ds /
1.1 millert 113: .\}
114: .if t \{\
1.7 millert 115: . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
116: . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
117: . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
118: . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
119: . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
120: . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
1.1 millert 121: .\}
1.7 millert 122: . \" troff and (daisy-wheel) nroff accents
1.1 millert 123: .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
124: .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
125: .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
126: .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
127: .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
128: .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
129: .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
130: .ds ae a\h'-(\w'a'u*4/10)'e
131: .ds Ae A\h'-(\w'A'u*4/10)'E
1.7 millert 132: . \" corrections for vroff
1.1 millert 133: .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
134: .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
1.7 millert 135: . \" for low resolution devices (crt and lpr)
1.1 millert 136: .if \n(.H>23 .if \n(.V>19 \
137: \{\
1.7 millert 138: . ds : e
139: . ds 8 ss
140: . ds o a
141: . ds d- d\h'-1'\(ga
142: . ds D- D\h'-1'\(hy
143: . ds th \o'bp'
144: . ds Th \o'LP'
145: . ds ae ae
146: . ds Ae AE
1.1 millert 147: .\}
148: .rm #[ #] #H #V #F C
1.13 millert 149: .\" ========================================================================
1.7 millert 150: .\"
1.13 millert 151: .IX Title "SUDO 8"
1.18 ! millert 152: .TH SUDO 8 "February 5, 2005" "1.6.8p7" "MAINTENANCE COMMANDS"
1.1 millert 153: .SH "NAME"
1.14 millert 154: sudo, sudoedit \- execute a command as another user
1.1 millert 155: .SH "SYNOPSIS"
1.7 millert 156: .IX Header "SYNOPSIS"
1.14 millert 157: \&\fBsudo\fR \fB\-K\fR | \fB\-L\fR | \fB\-V\fR | \fB\-h\fR | \fB\-k\fR | \fB\-l\fR | \fB\-v\fR
158: .PP
159: \&\fBsudo\fR [\fB\-HPSb\fR] [\fB\-a\fR\ \fIauth_type\fR] [\fB\-c\fR\ \fIclass\fR|\fI\-\fR]
160: [\fB\-p\fR\ \fIprompt\fR] [\fB\-u\fR\ \fIusername\fR|\fI#uid\fR]
161: {\fB\-e\fR\ file\ [...]\ |\ \fB\-i\fR\ |\ \fB\-s\fR\ |\ \fIcommand\fR}
162: .PP
163: \&\fBsudoedit\fR [\fB\-S\fR] [\fB\-a\fR\ \fIauth_type\fR]
164: [\fB\-p\fR\ \fIprompt\fR] [\fB\-u\fR\ \fIusername\fR|\fI#uid\fR]
165: file [...]
1.1 millert 166: .SH "DESCRIPTION"
1.7 millert 167: .IX Header "DESCRIPTION"
168: \&\fBsudo\fR allows a permitted user to execute a \fIcommand\fR as the
169: superuser or another user, as specified in the \fIsudoers\fR file.
170: The real and effective uid and gid are set to match those of the
1.14 millert 171: target user as specified in the passwd file and the group vector
172: is initialized based on the group file (unless the \fB\-P\fR option was
173: specified). If the invoking user is root or if the target user is
174: the same as the invoking user, no password is required. Otherwise,
1.7 millert 175: \&\fBsudo\fR requires that users authenticate themselves with a password
1.14 millert 176: by default (\s-1NOTE:\s0 in the default configuration this is the user's
177: password, not the root password). Once a user has been authenticated,
178: a timestamp is updated and the user may then use sudo without a
179: password for a short period of time (\f(CW\*(C`5\*(C'\fR minutes unless
180: overridden in \fIsudoers\fR).
181: .PP
182: When invoked as \fBsudoedit\fR, the \fB\-e\fR option (described below),
183: is implied.
1.7 millert 184: .PP
185: \&\fBsudo\fR determines who is an authorized user by consulting the file
186: \&\fI/etc/sudoers\fR. By giving \fBsudo\fR the \fB\-v\fR flag a user
187: can update the time stamp without running a \fIcommand.\fR The password
188: prompt itself will also time out if the user's password is not
189: entered within \f(CW\*(C`5\*(C'\fR minutes (unless overridden via
190: \&\fIsudoers\fR).
191: .PP
192: If a user who is not listed in the \fIsudoers\fR file tries to run a
193: command via \fBsudo\fR, mail is sent to the proper authorities, as
1.14 millert 194: defined at configure time or in the \fIsudoers\fR file (defaults to
195: \&\f(CW\*(C`root\*(C'\fR). Note that the mail will not be sent if an unauthorized
196: user tries to run sudo with the \fB\-l\fR or \fB\-v\fR flags. This allows
197: users to determine for themselves whether or not they are allowed
198: to use \fBsudo\fR.
199: .PP
200: If \fBsudo\fR is run by root and the \f(CW\*(C`SUDO_USER\*(C'\fR environment variable
201: is set, \fBsudo\fR will use this value to determine who the actual
202: user is. This can be used by a user to log commands through sudo
203: even when a root shell has been invoked. It also allows the \fB\-e\fR
204: flag to remain useful even when being run via a sudo-run script or
205: program. Note however, that the sudoers lookup is still done for
206: root, not the user specified by \f(CW\*(C`SUDO_USER\*(C'\fR.
1.1 millert 207: .PP
1.7 millert 208: \&\fBsudo\fR can log both successful and unsuccessful attempts (as well
1.1 millert 209: as errors) to \fIsyslog\fR\|(3), a log file, or both. By default \fBsudo\fR
1.7 millert 210: will log via \fIsyslog\fR\|(3) but this is changeable at configure time
211: or via the \fIsudoers\fR file.
1.1 millert 212: .SH "OPTIONS"
1.7 millert 213: .IX Header "OPTIONS"
214: \&\fBsudo\fR accepts the following command line options:
1.14 millert 215: .IP "\-H" 4
216: .IX Item "-H"
217: The \fB\-H\fR (\fI\s-1HOME\s0\fR) option sets the \f(CW\*(C`HOME\*(C'\fR environment variable
218: to the homedir of the target user (root by default) as specified
219: in passwd(5). By default, \fBsudo\fR does not modify \f(CW\*(C`HOME\*(C'\fR
220: (see \fIset_home\fR and \fIalways_set_home\fR in sudoers(5)).
221: .IP "\-K" 4
222: .IX Item "-K"
223: The \fB\-K\fR (sure \fIkill\fR) option is like \fB\-k\fR except that it removes
224: the user's timestamp entirely. Like \fB\-k\fR, this option does not
225: require a password.
1.13 millert 226: .IP "\-L" 4
1.7 millert 227: .IX Item "-L"
228: The \fB\-L\fR (\fIlist\fR defaults) option will list out the parameters
1.1 millert 229: that may be set in a \fIDefaults\fR line along with a short description
230: for each. This option is useful in conjunction with \fIgrep\fR\|(1).
1.14 millert 231: .IP "\-P" 4
232: .IX Item "-P"
233: The \fB\-P\fR (\fIpreserve group vector\fR) option causes \fBsudo\fR to
234: preserve the invoking user's group vector unaltered. By default,
235: \&\fBsudo\fR will initialize the group vector to the list of groups the
236: target user is in. The real and effective group IDs, however, are
237: still set to match the target user.
238: .IP "\-S" 4
239: .IX Item "-S"
240: The \fB\-S\fR (\fIstdin\fR) option causes \fBsudo\fR to read the password from
241: the standard input instead of the terminal device.
242: .IP "\-V" 4
243: .IX Item "-V"
244: The \fB\-V\fR (\fIversion\fR) option causes \fBsudo\fR to print the version
245: number and exit. If the invoking user is already root the \fB\-V\fR
246: option will print out a list of the defaults \fBsudo\fR was compiled
247: with as well as the machine's local network addresses.
248: .IP "\-a" 4
249: .IX Item "-a"
250: The \fB\-a\fR (\fIauthentication type\fR) option causes \fBsudo\fR to use the
251: specified authentication type when validating the user, as allowed
252: by /etc/login.conf. The system administrator may specify a list
253: of sudo-specific authentication methods by adding an \*(L"auth\-sudo\*(R"
254: entry in /etc/login.conf. This option is only available on systems
255: that support \s-1BSD\s0 authentication where \fBsudo\fR has been configured
256: with the \-\-with\-bsdauth option.
257: .IP "\-b" 4
258: .IX Item "-b"
259: The \fB\-b\fR (\fIbackground\fR) option tells \fBsudo\fR to run the given
260: command in the background. Note that if you use the \fB\-b\fR
261: option you cannot use shell job control to manipulate the process.
262: .IP "\-c" 4
263: .IX Item "-c"
264: The \fB\-c\fR (\fIclass\fR) option causes \fBsudo\fR to run the specified command
265: with resources limited by the specified login class. The \fIclass\fR
266: argument can be either a class name as defined in /etc/login.conf,
267: or a single '\-' character. Specifying a \fIclass\fR of \f(CW\*(C`\-\*(C'\fR indicates
268: that the command should be run restricted by the default login
269: capabilities for the user the command is run as. If the \fIclass\fR
270: argument specifies an existing user class, the command must be run
271: as root, or the \fBsudo\fR command must be run from a shell that is already
272: root. This option is only available on systems with \s-1BSD\s0 login classes
273: where \fBsudo\fR has been configured with the \-\-with\-logincap option.
274: .IP "\-e" 4
275: .IX Item "-e"
276: The \fB\-e\fR (\fIedit\fR) option indicates that, instead of running
277: a command, the user wishes to edit one or more files. In lieu
278: of a command, the string \*(L"sudoedit\*(R" is used when consulting
279: the \fIsudoers\fR file. If the user is authorized by \fIsudoers\fR
280: the following steps are taken:
281: .RS 4
282: .IP "1." 8
283: Temporary copies are made of the files to be edited with the owner
284: set to the invoking user.
285: .IP "2." 8
286: The editor specified by the \f(CW\*(C`VISUAL\*(C'\fR or \f(CW\*(C`EDITOR\*(C'\fR environment
287: variables is run to edit the temporary files. If neither \f(CW\*(C`VISUAL\*(C'\fR
288: nor \f(CW\*(C`EDITOR\*(C'\fR are set, the program listed in the \fIeditor\fR \fIsudoers\fR
289: variable is used.
290: .IP "3." 8
291: If they have been modified, the temporary files are copied back to
292: their original location and the temporary versions are removed.
293: .RE
294: .RS 4
295: .Sp
296: If the specified file does not exist, it will be created. Note
297: that unlike most commands run by \fBsudo\fR, the editor is run with
298: the invoking user's environment unmodified. If, for some reason,
299: \&\fBsudo\fR is unable to update a file with its edited version, the
300: user will receive a warning and the edited copy will remain in a
301: temporary file.
302: .RE
1.13 millert 303: .IP "\-h" 4
1.7 millert 304: .IX Item "-h"
305: The \fB\-h\fR (\fIhelp\fR) option causes \fBsudo\fR to print a usage message and exit.
1.14 millert 306: .IP "\-i" 4
307: .IX Item "-i"
308: The \fB\-i\fR (\fIsimulate initial login\fR) option runs the shell specified
309: in the passwd(5) entry of the user that the command is
310: being run as. The command name argument given to the shell begins
311: with a \f(CW\*(C`\-\*(C'\fR to tell the shell to run as a login shell. \fBsudo\fR
312: attempts to change to that user's home directory before running the
313: shell. It also initializes the environment, leaving \fI\s-1TERM\s0\fR
314: unchanged, setting \fI\s-1HOME\s0\fR, \fI\s-1SHELL\s0\fR, \fI\s-1USER\s0\fR, \fI\s-1LOGNAME\s0\fR, and
315: \&\fI\s-1PATH\s0\fR, and unsetting all other environment variables. Note that
316: because the shell to use is determined before the \fIsudoers\fR file
317: is parsed, a \fIrunas_default\fR setting in \fIsudoers\fR will specify
318: the user to run the shell as but will not affect which shell is
319: actually run.
1.13 millert 320: .IP "\-k" 4
1.7 millert 321: .IX Item "-k"
322: The \fB\-k\fR (\fIkill\fR) option to \fBsudo\fR invalidates the user's timestamp
1.1 millert 323: by setting the time on it to the epoch. The next time \fBsudo\fR is
324: run a password will be required. This option does not require a password
325: and was added to allow a user to revoke \fBsudo\fR permissions from a .logout
326: file.
1.14 millert 327: .IP "\-l" 4
328: .IX Item "-l"
329: The \fB\-l\fR (\fIlist\fR) option will list out the allowed (and
330: forbidden) commands for the user on the current host.
1.13 millert 331: .IP "\-p" 4
1.7 millert 332: .IX Item "-p"
333: The \fB\-p\fR (\fIprompt\fR) option allows you to override the default
1.13 millert 334: password prompt and use a custom one. The following percent (`\f(CW\*(C`%\*(C'\fR')
335: escapes are supported:
336: .RS 4
337: .ie n .IP "%u" 8
338: .el .IP "\f(CW%u\fR" 8
339: .IX Item "%u"
340: expanded to the invoking user's login name
341: .ie n .IP "%U" 8
342: .el .IP "\f(CW%U\fR" 8
343: .IX Item "%U"
344: expanded to the login name of the user the command will
345: be run as (defaults to root)
346: .ie n .IP "%h" 8
347: .el .IP "\f(CW%h\fR" 8
348: .IX Item "%h"
349: expanded to the local hostname without the domain name
350: .ie n .IP "%H" 8
351: .el .IP "\f(CW%H\fR" 8
352: .IX Item "%H"
353: expanded to the local hostname including the domain name
354: (on if the machine's hostname is fully qualified or the \fIfqdn\fR
355: sudoers option is set)
356: .ie n .IP "\*(C`%%\*(C'" 8
357: .el .IP "\f(CW\*(C`%%\*(C'\fR" 8
358: .IX Item "%%"
1.14 millert 359: two consecutive \f(CW\*(C`%\*(C'\fR characters are collapsed into a single \f(CW\*(C`%\*(C'\fR character
1.13 millert 360: .RE
361: .RS 4
362: .RE
1.14 millert 363: .IP "\-s" 4
364: .IX Item "-s"
365: The \fB\-s\fR (\fIshell\fR) option runs the shell specified by the \fI\s-1SHELL\s0\fR
366: environment variable if it is set or the shell as specified
367: in passwd(5).
1.13 millert 368: .IP "\-u" 4
1.7 millert 369: .IX Item "-u"
370: The \fB\-u\fR (\fIuser\fR) option causes \fBsudo\fR to run the specified command
1.1 millert 371: as a user other than \fIroot\fR. To specify a \fIuid\fR instead of a
1.14 millert 372: \&\fIusername\fR, use \fI#uid\fR. Note that if the \fItargetpw\fR Defaults
373: option is set (see sudoers(5)) it is not possible
374: to run commands with a uid not listed in the password database.
375: .IP "\-v" 4
376: .IX Item "-v"
377: If given the \fB\-v\fR (\fIvalidate\fR) option, \fBsudo\fR will update the
378: user's timestamp, prompting for the user's password if necessary.
379: This extends the \fBsudo\fR timeout for another \f(CW\*(C`5\*(C'\fR minutes
380: (or whatever the timeout is set to in \fIsudoers\fR) but does not run
381: a command.
1.13 millert 382: .IP "\-\-" 4
383: The \fB\-\-\fR flag indicates that \fBsudo\fR should stop processing command
1.7 millert 384: line arguments. It is most useful in conjunction with the \fB\-s\fR flag.
1.1 millert 385: .SH "RETURN VALUES"
1.7 millert 386: .IX Header "RETURN VALUES"
387: Upon successful execution of a program, the return value from \fBsudo\fR
388: will simply be the return value of the program that was executed.
389: .PP
390: Otherwise, \fBsudo\fR quits with an exit value of 1 if there is a
1.1 millert 391: configuration/permission problem or if \fBsudo\fR cannot execute the
392: given command. In the latter case the error string is printed to
393: stderr. If \fBsudo\fR cannot \fIstat\fR\|(2) one or more entries in the user's
1.7 millert 394: \&\f(CW\*(C`PATH\*(C'\fR an error is printed on stderr. (If the directory does not
1.1 millert 395: exist or if it is not really a directory, the entry is ignored and
396: no error is printed.) This should not happen under normal
397: circumstances. The most common reason for \fIstat\fR\|(2) to return
1.7 millert 398: \&\*(L"permission denied\*(R" is if you are running an automounter and one
399: of the directories in your \f(CW\*(C`PATH\*(C'\fR is on a machine that is currently
1.1 millert 400: unreachable.
401: .SH "SECURITY NOTES"
1.7 millert 402: .IX Header "SECURITY NOTES"
403: \&\fBsudo\fR tries to be safe when executing external commands. Variables
1.1 millert 404: that control how dynamic loading and binding is done can be used
405: to subvert the program that \fBsudo\fR runs. To combat this the
1.13 millert 406: \&\f(CW\*(C`LD_*\*(C'\fR, \f(CW\*(C`_RLD_*\*(C'\fR, \f(CW\*(C`SHLIB_PATH\*(C'\fR (\s-1HP\-UX\s0 only), and \f(CW\*(C`LIBPATH\*(C'\fR (\s-1AIX\s0
1.1 millert 407: only) environment variables are removed from the environment passed
1.7 millert 408: on to all commands executed. \fBsudo\fR will also remove the \f(CW\*(C`IFS\*(C'\fR,
1.15 millert 409: \&\f(CW\*(C`CDPATH\*(C'\fR, \f(CW\*(C`ENV\*(C'\fR, \f(CW\*(C`BASH_ENV\*(C'\fR, \f(CW\*(C`KRB_CONF\*(C'\fR, \f(CW\*(C`KRBCONFDIR\*(C'\fR, \f(CW\*(C`KRBTKFILE\*(C'\fR,
1.7 millert 410: \&\f(CW\*(C`KRB5_CONFIG\*(C'\fR, \f(CW\*(C`LOCALDOMAIN\*(C'\fR, \f(CW\*(C`RES_OPTIONS\*(C'\fR, \f(CW\*(C`HOSTALIASES\*(C'\fR,
411: \&\f(CW\*(C`NLSPATH\*(C'\fR, \f(CW\*(C`PATH_LOCALE\*(C'\fR, \f(CW\*(C`TERMINFO\*(C'\fR, \f(CW\*(C`TERMINFO_DIRS\*(C'\fR and
412: \&\f(CW\*(C`TERMPATH\*(C'\fR variables as they too can pose a threat. If the
413: \&\f(CW\*(C`TERMCAP\*(C'\fR variable is set and is a pathname, it too is ignored.
414: Additionally, if the \f(CW\*(C`LC_*\*(C'\fR or \f(CW\*(C`LANGUAGE\*(C'\fR variables contain the
1.15 millert 415: \&\f(CW\*(C`/\*(C'\fR or \f(CW\*(C`%\*(C'\fR characters, they are ignored. Environment variables
416: with a value beginning with \f(CW\*(C`()\*(C'\fR are also removed as they could
417: be interpreted as \fBbash\fR functions. If \fBsudo\fR has been
1.7 millert 418: compiled with SecurID support, the \f(CW\*(C`VAR_ACE\*(C'\fR, \f(CW\*(C`USR_ACE\*(C'\fR and
419: \&\f(CW\*(C`DLC_ACE\*(C'\fR variables are cleared as well. The list of environment
420: variables that \fBsudo\fR clears is contained in the output of
421: \&\f(CW\*(C`sudo \-V\*(C'\fR when run as root.
1.1 millert 422: .PP
1.7 millert 423: To prevent command spoofing, \fBsudo\fR checks \*(L".\*(R" and "" (both denoting
1.1 millert 424: current directory) last when searching for a command in the user's
1.7 millert 425: \&\s-1PATH\s0 (if one or both are in the \s-1PATH\s0). Note, however, that the
426: actual \f(CW\*(C`PATH\*(C'\fR environment variable is \fInot\fR modified and is passed
1.1 millert 427: unchanged to the program that \fBsudo\fR executes.
428: .PP
1.7 millert 429: For security reasons, if your \s-1OS\s0 supports shared libraries and does
1.1 millert 430: not disable user-defined library search paths for setuid programs
431: (most do), you should either use a linker option that disables this
432: behavior or link \fBsudo\fR statically.
433: .PP
1.7 millert 434: \&\fBsudo\fR will check the ownership of its timestamp directory
1.3 millert 435: (\fI/var/run/sudo\fR by default) and ignore the directory's contents if
436: it is not owned by root and only writable by root. On systems that
437: allow non-root users to give away files via \fIchown\fR\|(2), if the timestamp
1.6 pjanzen 438: directory is located in a directory writable by anyone (e.g.: \fI/tmp\fR),
1.3 millert 439: it is possible for a user to create the timestamp directory before
1.7 millert 440: \&\fBsudo\fR is run. However, because \fBsudo\fR checks the ownership and
1.3 millert 441: mode of the directory and its contents, the only damage that can
442: be done is to \*(L"hide\*(R" files by putting them in the timestamp dir.
443: This is unlikely to happen since once the timestamp dir is owned
444: by root and inaccessible by any other user the user placing files
445: there would be unable to get them back out. To get around this
446: issue you can use a directory that is not world-writable for the
447: timestamps (\fI/var/adm/sudo\fR for instance) or create \fI/var/run/sudo\fR
448: with the appropriate owner (root) and permissions (0700) in the
449: system startup files.
1.1 millert 450: .PP
1.7 millert 451: \&\fBsudo\fR will not honor timestamps set far in the future.
452: Timestamps with a date greater than current_time + 2 * \f(CW\*(C`TIMEOUT\*(C'\fR
1.1 millert 453: will be ignored and sudo will log and complain. This is done to
454: keep a user from creating his/her own timestamp with a bogus
1.7 millert 455: date on systems that allow users to give away files.
456: .PP
457: Please note that \fBsudo\fR will only log the command it explicitly
458: runs. If a user runs a command such as \f(CW\*(C`sudo su\*(C'\fR or \f(CW\*(C`sudo sh\*(C'\fR,
459: subsequent commands run from that shell will \fInot\fR be logged, nor
460: will \fBsudo\fR's access control affect them. The same is true for
461: commands that offer shell escapes (including most editors). Because
462: of this, care must be taken when giving users access to commands
1.12 david 463: via \fBsudo\fR to verify that the command does not inadvertently give
1.7 millert 464: the user an effective root shell.
1.14 millert 465: .SH "ENVIRONMENT"
466: .IX Header "ENVIRONMENT"
467: \&\fBsudo\fR utilizes the following environment variables:
468: .PP
469: .Vb 2
470: \& EDITOR Default editor to use in -e (sudoedit) mode if
471: \& VISUAL is not set
472: .Ve
473: .PP
474: .Vb 3
475: \& HOME In -s or -H mode (or if sudo was configured with
476: \& the --enable-shell-sets-home option), set to
477: \& homedir of the target user
478: .Ve
479: .PP
480: .Vb 2
481: \& PATH Set to a sane value if sudo was configured with
482: \& the --with-secure-path option
483: .Ve
484: .PP
485: .Vb 1
486: \& SHELL Used to determine shell to run with -s option
487: .Ve
488: .PP
489: .Vb 1
490: \& SUDO_PROMPT Used as the default password prompt
491: .Ve
492: .PP
493: .Vb 1
494: \& SUDO_COMMAND Set to the command run by sudo
495: .Ve
496: .PP
497: .Vb 1
498: \& SUDO_USER Set to the login of the user who invoked sudo
499: .Ve
500: .PP
501: .Vb 1
502: \& SUDO_UID Set to the uid of the user who invoked sudo
503: .Ve
504: .PP
505: .Vb 1
506: \& SUDO_GID Set to the gid of the user who invoked sudo
507: .Ve
508: .PP
509: .Vb 1
510: \& SUDO_PS1 If set, PS1 will be set to its value
511: .Ve
512: .PP
513: .Vb 2
514: \& USER Set to the target user (root unless the -u option
515: \& is specified)
516: .Ve
517: .PP
518: .Vb 1
519: \& VISUAL Default editor to use in -e (sudoedit) mode
520: .Ve
521: .SH "FILES"
522: .IX Header "FILES"
523: .Vb 2
524: \& /etc/sudoers List of who can run what
525: \& /var/run/sudo Directory containing timestamps
526: .Ve
1.1 millert 527: .SH "EXAMPLES"
1.7 millert 528: .IX Header "EXAMPLES"
1.14 millert 529: Note: the following examples assume suitable sudoers(5) entries.
1.1 millert 530: .PP
531: To get a file listing of an unreadable directory:
532: .PP
533: .Vb 1
1.14 millert 534: \& $ sudo ls /usr/local/protected
1.1 millert 535: .Ve
1.13 millert 536: .PP
1.1 millert 537: To list the home directory of user yazza on a machine where the
1.14 millert 538: file system holding ~yazza is not exported as root:
1.1 millert 539: .PP
540: .Vb 1
1.14 millert 541: \& $ sudo -u yazza ls ~yazza
1.1 millert 542: .Ve
1.13 millert 543: .PP
1.1 millert 544: To edit the \fIindex.html\fR file as user www:
545: .PP
546: .Vb 1
1.14 millert 547: \& $ sudo -u www vi ~www/htdocs/index.html
1.1 millert 548: .Ve
1.13 millert 549: .PP
1.1 millert 550: To shutdown a machine:
551: .PP
552: .Vb 1
1.14 millert 553: \& $ sudo shutdown -r +15 "quick reboot"
1.1 millert 554: .Ve
1.13 millert 555: .PP
1.1 millert 556: To make a usage listing of the directories in the /home
557: partition. Note that this runs the commands in a sub-shell
1.7 millert 558: to make the \f(CW\*(C`cd\*(C'\fR and file redirection work.
1.1 millert 559: .PP
560: .Vb 1
1.14 millert 561: \& $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
1.1 millert 562: .Ve
1.14 millert 563: .SH "SEE ALSO"
564: .IX Header "SEE ALSO"
565: \&\fIgrep\fR\|(1), \fIsu\fR\|(1), \fIstat\fR\|(2), \fIlogin_cap\fR\|(3), sudoers(5),
566: passwd(5), visudo(8)
1.1 millert 567: .SH "AUTHORS"
1.7 millert 568: .IX Header "AUTHORS"
569: Many people have worked on \fBsudo\fR over the years; this
1.1 millert 570: version consists of code written primarily by:
571: .PP
572: .Vb 2
573: \& Todd Miller
574: \& Chris Jepeway
575: .Ve
1.13 millert 576: .PP
1.7 millert 577: See the \s-1HISTORY\s0 file in the \fBsudo\fR distribution or visit
1.8 millert 578: http://www.sudo.ws/sudo/history.html for a short history
1.1 millert 579: of \fBsudo\fR.
1.14 millert 580: .SH "CAVEATS"
581: .IX Header "CAVEATS"
582: There is no easy way to prevent a user from gaining a root shell
583: if that user is allowed to run arbitrary commands via \fBsudo\fR.
584: Also, many programs (such as editors) allow the user to run commands
585: via shell escapes, thus avoiding \fBsudo\fR's checks. However, on
586: most systems it is possible to prevent shell escapes with \fBsudo\fR's
587: \&\fInoexec\fR functionality. See the sudoers(5) manual
588: for details.
589: .PP
590: It is not meaningful to run the \f(CW\*(C`cd\*(C'\fR command directly via sudo, e.g.
591: .PP
592: .Vb 1
593: \& $ sudo cd /usr/local/protected
594: .Ve
595: .PP
596: since when whe command exits the parent process (your shell) will
597: still be the same. Please see the \s-1EXAMPLES\s0 section for more information.
598: .PP
599: If users have sudo \f(CW\*(C`ALL\*(C'\fR there is nothing to prevent them from
600: creating their own program that gives them a root shell regardless
601: of any '!' elements in the user specification.
602: .PP
603: Running shell scripts via \fBsudo\fR can expose the same kernel bugs that
604: make setuid shell scripts unsafe on some operating systems (if your \s-1OS\s0
605: has a /dev/fd/ directory, setuid shell scripts are generally safe).
1.1 millert 606: .SH "BUGS"
1.7 millert 607: .IX Header "BUGS"
1.14 millert 608: If you feel you have found a bug in \fBsudo\fR, please submit a bug report
1.8 millert 609: at http://www.sudo.ws/sudo/bugs/
1.14 millert 610: .SH "SUPPORT"
611: .IX Header "SUPPORT"
612: Commercial support is available for \fBsudo\fR, see
613: http://www.sudo.ws/sudo/support.html for details.
614: .PP
615: Limited free support is available via the sudo-users mailing list,
616: see http://www.sudo.ws/mailman/listinfo/sudo\-users to subscribe or
617: search the archives.
1.1 millert 618: .SH "DISCLAIMER"
1.7 millert 619: .IX Header "DISCLAIMER"
620: \&\fBSudo\fR is provided ``\s-1AS\s0 \s-1IS\s0'' and any express or implied warranties,
1.1 millert 621: including, but not limited to, the implied warranties of merchantability
1.14 millert 622: and fitness for a particular purpose are disclaimed. See the \s-1LICENSE\s0
623: file distributed with \fBsudo\fR or http://www.sudo.ws/sudo/license.html
624: for complete details.