Annotation of src/usr.bin/su/su.1, Revision 1.15
1.15 ! millert 1: .\" $OpenBSD: su.1,v 1.14 2002/02/17 23:59:20 millert Exp $
1.9 aaron 2: .\"
1.1 deraadt 3: .\" Copyright (c) 1988, 1990 The Regents of the University of California.
4: .\" All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
14: .\" 3. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
34: .\" from: @(#)su.1 6.12 (Berkeley) 7/29/91
35: .\"
36: .Dd July 29, 1991
37: .Dt SU 1
38: .Os
39: .Sh NAME
40: .Nm su
41: .Nd substitute user identity
42: .Sh SYNOPSIS
43: .Nm su
1.12 millert 44: .Op Fl fKlm
45: .Op Fl a Ar auth-type
1.10 millert 46: .Op Fl c Ar login-class
1.1 deraadt 47: .Op Ar login Op Ar "shell arguments"
48: .Sh DESCRIPTION
1.8 aaron 49: .Nm
1.1 deraadt 50: requests the Kerberos password for
51: .Ar login
52: (or for
53: .Dq Ar login Ns .root ,
54: if no login is provided), and switches to
1.7 aaron 55: that user and group ID after obtaining a Kerberos ticket granting access.
1.1 deraadt 56: A shell is then executed, and any additional
57: .Ar "shell arguments"
58: after the login name
59: are passed to the shell.
1.8 aaron 60: .Nm
1.1 deraadt 61: will resort to the local password file to find the password for
62: .Ar login
1.4 millert 63: if there is a Kerberos error or if Kerberos is not installed.
1.1 deraadt 64: If
1.8 aaron 65: .Nm
1.1 deraadt 66: is executed by root, no password is requested and a shell
67: with the appropriate user ID is executed; no additional Kerberos tickets
68: are obtained.
69: .Pp
70: By default, the environment is unmodified with the exception of
1.5 millert 71: .Ev LOGNAME ,
1.1 deraadt 72: .Ev HOME ,
1.12 millert 73: .Ev SHELL ,
1.1 deraadt 74: and
1.12 millert 75: .Ev USER .
1.1 deraadt 76: .Ev HOME
77: and
78: .Ev SHELL
79: are set to the target login's default values.
1.5 millert 80: .Ev LOGNAME
81: and
1.1 deraadt 82: .Ev USER
1.12 millert 83: are set to the target login, unless the target login has a user ID of 0
84: and the
85: .Fl l
86: flag was not specified,
1.1 deraadt 87: in which case it is unmodified.
88: The invoked shell is the target login's.
89: This is the traditional behavior of
90: .Nm su .
91: .Pp
1.12 millert 92: If not using
93: .Fl m
94: and the target login has a user ID of 0 then the
95: .Ev PATH
96: variable and umask value
97: (see
98: .Xr umask 2 )
99: are always set according to the
100: .Pa /etc/login.conf
101: file (see
102: .Xr login.conf 5 ) .
103: .Pp
1.1 deraadt 104: The options are as follows:
105: .Bl -tag -width Ds
1.14 millert 106: .It Fl
107: Same as the
108: .Fl l
109: option (deprecated).
1.12 millert 110: .It Fl a
111: Specify an authentication type such as
112: .Dq skey ,
113: .Dq securid ,
114: or
1.15 ! millert 115: .Dq krb4 .
1.10 millert 116: .It Fl c
117: Specify a login class.
118: You may only override the default class if you're already root.
1.1 deraadt 119: .It Fl f
120: If the invoked shell is
121: .Xr csh 1 ,
122: this option prevents it from reading the
123: .Dq Pa .cshrc
124: file.
1.12 millert 125: .It Fl K
126: Do not attempt to use Kerberos to authenticate the user.
1.1 deraadt 127: .It Fl l
128: Simulate a full login.
129: The environment is discarded except for
130: .Ev HOME ,
131: .Ev SHELL ,
132: .Ev PATH ,
133: .Ev TERM ,
1.5 millert 134: .Ev LOGNAME ,
1.1 deraadt 135: and
136: .Ev USER .
137: .Ev HOME
138: and
139: .Ev SHELL
140: are modified as above.
1.5 millert 141: .Ev LOGNAME
142: and
1.1 deraadt 143: .Ev USER
1.5 millert 144: are set to the target login.
1.1 deraadt 145: .Ev PATH
1.12 millert 146: is set to the value specified by the
147: .Dq path
148: entry in
149: .Xr login.conf 5 .
1.1 deraadt 150: .Ev TERM
151: is imported from your current environment.
152: The invoked shell is the target login's, and
1.8 aaron 153: .Nm
1.1 deraadt 154: will change directory to the target login's home directory.
155: .It Fl m
156: Leave the environment unmodified.
157: The invoked shell is your login shell, and no directory changes are made.
158: As a security precaution, if the target user's shell is a non-standard
159: shell (as defined by
160: .Xr getusershell 3 )
1.7 aaron 161: and the caller's real UID is
1.1 deraadt 162: non-zero,
1.8 aaron 163: .Nm
1.1 deraadt 164: will fail.
165: .El
166: .Pp
167: The
168: .Fl l
169: and
170: .Fl m
171: options are mutually exclusive; the last one specified
172: overrides any previous ones.
1.8 aaron 173: .Pp
174: If the optional
1.4 millert 175: .Ar "shell arguments"
1.8 aaron 176: are provided on the command line, they are passed to the login shell of
1.9 aaron 177: the target login.
178: This allows it to pass arbitrary commands via the
1.8 aaron 179: .Fl c
1.9 aaron 180: option as understood by most shells.
181: Note that
1.8 aaron 182: .Fl c
1.4 millert 183: usually expects a single argument only; you have to quote it when
1.8 aaron 184: passing multiple words.
1.1 deraadt 185: .Pp
1.2 deraadt 186: If group 0 (normally
1.1 deraadt 187: .Dq wheel )
1.2 deraadt 188: has users listed then only those users can
1.8 aaron 189: .Nm
1.2 deraadt 190: to
191: .Dq root .
1.6 provos 192: It is not sufficient to change a user's
193: .Pa /etc/passwd
194: entry to add them to the
195: .Dq wheel
196: group; they must explicitly be listed in
197: .Pa /etc/group .
198: If no one is in the
199: .Dq wheel
200: group, it is ignored, and anyone who knows the root password is permitted to
1.8 aaron 201: .Nm
1.1 deraadt 202: to
203: .Dq root .
204: .Pp
1.9 aaron 205: By default (unless the prompt is reset by a startup file) the superuser
1.1 deraadt 206: prompt is set to
207: .Dq Sy \&#
208: to remind one of its awesome power.
1.8 aaron 209: .Sh EXAMPLES
210: .Bl -tag -width 5n -compact
211: .It Li "su bin -c makewhatis"
212: Runs the command
213: .Li makewhatis
214: as user
215: .Li bin .
216: You will be asked for bin's password unless your real UID is 0.
1.4 millert 217: .Pp
218: .It Li "su bin -c 'makewhatis /usr/local/man'"
1.8 aaron 219: Same as above, but the target command consists of more than a
220: single word.
1.4 millert 221: .Pp
1.8 aaron 222: .It Li "su -l foo"
223: Pretend a login for user
224: .Li foo .
1.15 ! millert 225: .Pp
! 226: .It Li "su -a skey -l foo"
! 227: Same as above, but use S/Key for authentication.
1.8 aaron 228: .El
1.1 deraadt 229: .Sh ENVIRONMENT
1.9 aaron 230: .Bl -tag -width LOGNAME
1.1 deraadt 231: .It Ev HOME
232: Default home directory of real user ID unless modified as
233: specified above.
1.12 millert 234: .It Ev LOGNAME
235: The user ID is always the effective ID (the target user ID) after an
236: .Nm
237: unless the user ID is 0 (root).
1.1 deraadt 238: .It Ev PATH
239: Default search path of real user ID unless modified as specified above.
240: .It Ev TERM
241: Provides terminal type which may be retained for the substituted
242: user ID.
1.5 millert 243: .It Ev USER
244: Same as
245: .Ev LOGNAME .
1.1 deraadt 246: .El
1.9 aaron 247: .Sh SEE ALSO
248: .Xr csh 1 ,
249: .Xr kerberos 1 ,
250: .Xr kinit 1 ,
251: .Xr login 1 ,
252: .Xr sh 1 ,
253: .Xr skey 1 ,
1.10 millert 254: .Xr setusercontext 3 ,
1.9 aaron 255: .Xr group 5 ,
1.10 millert 256: .Xr login.conf 5 ,
1.9 aaron 257: .Xr passwd 5 ,
1.13 heko 258: .Xr environ 7 ,
259: .Xr sudo 8
1.1 deraadt 260: .Sh HISTORY
261: A
262: .Nm
263: command appeared in
264: .At v7 .
1.12 millert 265: .Sh BUGS
266: There is no direct way to force a particular shell to be used.
267: .Pp
268: The login name is not optional for root if there are shell arguments.