Annotation of src/usr.bin/su/su.1, Revision 1.17
1.17 ! deraadt 1: .\" $OpenBSD: su.1,v 1.16 2002/10/16 01:06:32 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.16 millert 44: .Op Fl fKLlm
1.12 millert 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.16 millert 125: .It Fl L
126: Loop until a correct username and password combination is entered,
127: similar to
128: .Xr login 1 .
129: Note that in this mode target
130: .Ar login
131: must be specified explicitly, either on the command line or interactively.
132: Additionally,
133: .Nm
134: will prompt for the password even when invoked by root.
1.12 millert 135: .It Fl K
136: Do not attempt to use Kerberos to authenticate the user.
1.1 deraadt 137: .It Fl l
138: Simulate a full login.
139: The environment is discarded except for
140: .Ev HOME ,
141: .Ev SHELL ,
142: .Ev PATH ,
143: .Ev TERM ,
1.5 millert 144: .Ev LOGNAME ,
1.1 deraadt 145: and
146: .Ev USER .
147: .Ev HOME
148: and
149: .Ev SHELL
150: are modified as above.
1.5 millert 151: .Ev LOGNAME
152: and
1.1 deraadt 153: .Ev USER
1.5 millert 154: are set to the target login.
1.1 deraadt 155: .Ev PATH
1.12 millert 156: is set to the value specified by the
157: .Dq path
158: entry in
159: .Xr login.conf 5 .
1.1 deraadt 160: .Ev TERM
161: is imported from your current environment.
162: The invoked shell is the target login's, and
1.8 aaron 163: .Nm
1.1 deraadt 164: will change directory to the target login's home directory.
165: .It Fl m
166: Leave the environment unmodified.
167: The invoked shell is your login shell, and no directory changes are made.
168: As a security precaution, if the target user's shell is a non-standard
169: shell (as defined by
170: .Xr getusershell 3 )
1.7 aaron 171: and the caller's real UID is
1.1 deraadt 172: non-zero,
1.8 aaron 173: .Nm
1.1 deraadt 174: will fail.
175: .El
176: .Pp
177: The
178: .Fl l
179: and
180: .Fl m
181: options are mutually exclusive; the last one specified
182: overrides any previous ones.
1.8 aaron 183: .Pp
184: If the optional
1.4 millert 185: .Ar "shell arguments"
1.8 aaron 186: are provided on the command line, they are passed to the login shell of
1.9 aaron 187: the target login.
188: This allows it to pass arbitrary commands via the
1.8 aaron 189: .Fl c
1.9 aaron 190: option as understood by most shells.
191: Note that
1.8 aaron 192: .Fl c
1.4 millert 193: usually expects a single argument only; you have to quote it when
1.8 aaron 194: passing multiple words.
1.1 deraadt 195: .Pp
1.2 deraadt 196: If group 0 (normally
1.1 deraadt 197: .Dq wheel )
1.2 deraadt 198: has users listed then only those users can
1.8 aaron 199: .Nm
1.2 deraadt 200: to
201: .Dq root .
1.6 provos 202: It is not sufficient to change a user's
203: .Pa /etc/passwd
204: entry to add them to the
205: .Dq wheel
206: group; they must explicitly be listed in
207: .Pa /etc/group .
208: If no one is in the
209: .Dq wheel
210: group, it is ignored, and anyone who knows the root password is permitted to
1.8 aaron 211: .Nm
1.1 deraadt 212: to
213: .Dq root .
214: .Pp
1.9 aaron 215: By default (unless the prompt is reset by a startup file) the superuser
1.1 deraadt 216: prompt is set to
217: .Dq Sy \&#
218: to remind one of its awesome power.
1.8 aaron 219: .Sh EXAMPLES
220: .Bl -tag -width 5n -compact
1.17 ! deraadt 221: .It Li "$ su bin -c makewhatis"
1.8 aaron 222: Runs the command
223: .Li makewhatis
224: as user
225: .Li bin .
226: You will be asked for bin's password unless your real UID is 0.
1.4 millert 227: .Pp
1.17 ! deraadt 228: .It Li "$ su bin -c 'makewhatis /usr/local/man'"
1.8 aaron 229: Same as above, but the target command consists of more than a
230: single word.
1.4 millert 231: .Pp
1.17 ! deraadt 232: .It Li "$ su -l foo"
1.8 aaron 233: Pretend a login for user
234: .Li foo .
1.15 millert 235: .Pp
1.17 ! deraadt 236: .It Li "$ su -a skey -l foo"
1.15 millert 237: Same as above, but use S/Key for authentication.
1.8 aaron 238: .El
1.1 deraadt 239: .Sh ENVIRONMENT
1.9 aaron 240: .Bl -tag -width LOGNAME
1.1 deraadt 241: .It Ev HOME
242: Default home directory of real user ID unless modified as
243: specified above.
1.12 millert 244: .It Ev LOGNAME
245: The user ID is always the effective ID (the target user ID) after an
246: .Nm
247: unless the user ID is 0 (root).
1.1 deraadt 248: .It Ev PATH
249: Default search path of real user ID unless modified as specified above.
250: .It Ev TERM
251: Provides terminal type which may be retained for the substituted
252: user ID.
1.5 millert 253: .It Ev USER
254: Same as
255: .Ev LOGNAME .
1.1 deraadt 256: .El
1.9 aaron 257: .Sh SEE ALSO
258: .Xr csh 1 ,
259: .Xr kerberos 1 ,
260: .Xr kinit 1 ,
261: .Xr login 1 ,
262: .Xr sh 1 ,
263: .Xr skey 1 ,
1.10 millert 264: .Xr setusercontext 3 ,
1.9 aaron 265: .Xr group 5 ,
1.10 millert 266: .Xr login.conf 5 ,
1.9 aaron 267: .Xr passwd 5 ,
1.13 heko 268: .Xr environ 7 ,
269: .Xr sudo 8
1.1 deraadt 270: .Sh HISTORY
271: A
272: .Nm
273: command appeared in
274: .At v7 .
1.12 millert 275: .Sh BUGS
276: There is no direct way to force a particular shell to be used.
277: .Pp
278: The login name is not optional for root if there are shell arguments.
![[BACK]](/icons/back.gif){kind=icon}
Return to su.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / su