Annotation of src/usr.bin/su/su.1, Revision 1.10
1.10 ! millert 1: .\" $OpenBSD: su.1,v 1.9 2000/03/11 21:40:03 aaron 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
44: .Op Fl Kflm
1.10 ! millert 45: .Op Fl c Ar login-class
1.1 deraadt 46: .Op Ar login Op Ar "shell arguments"
47: .Sh DESCRIPTION
1.8 aaron 48: .Nm
1.1 deraadt 49: requests the Kerberos password for
50: .Ar login
51: (or for
52: .Dq Ar login Ns .root ,
53: if no login is provided), and switches to
1.7 aaron 54: that user and group ID after obtaining a Kerberos ticket granting access.
1.1 deraadt 55: A shell is then executed, and any additional
56: .Ar "shell arguments"
57: after the login name
58: are passed to the shell.
1.8 aaron 59: .Nm
1.1 deraadt 60: will resort to the local password file to find the password for
61: .Ar login
1.4 millert 62: if there is a Kerberos error or if Kerberos is not installed.
1.1 deraadt 63: If
1.8 aaron 64: .Nm
1.1 deraadt 65: is executed by root, no password is requested and a shell
66: with the appropriate user ID is executed; no additional Kerberos tickets
67: are obtained.
68: .Pp
69: Alternately, if the user enters the password "s/key", they will be
70: authenticated using the S/Key one-time password system as described in
71: .Xr skey 1 .
72: S/Key is a Trademark of Bellcore.
73: .Pp
74: By default, the environment is unmodified with the exception of
1.5 millert 75: .Ev LOGNAME ,
1.1 deraadt 76: .Ev USER ,
77: .Ev HOME ,
78: and
79: .Ev SHELL .
80: .Ev HOME
81: and
82: .Ev SHELL
83: are set to the target login's default values.
1.5 millert 84: .Ev LOGNAME
85: and
1.1 deraadt 86: .Ev USER
1.5 millert 87: are set to the target login, unless the target login has a user ID of 0,
1.1 deraadt 88: in which case it is unmodified.
89: The invoked shell is the target login's.
90: This is the traditional behavior of
91: .Nm su .
92: .Pp
93: The options are as follows:
94: .Bl -tag -width Ds
95: .It Fl K
96: Do not attempt to use Kerberos to authenticate the user.
1.10 ! millert 97: .It Fl c
! 98: Specify a login class.
! 99: You may only override the default class if you're already root.
1.1 deraadt 100: .It Fl f
101: If the invoked shell is
102: .Xr csh 1 ,
103: this option prevents it from reading the
104: .Dq Pa .cshrc
105: file.
106: .It Fl l
107: Simulate a full login.
108: The environment is discarded except for
109: .Ev HOME ,
110: .Ev SHELL ,
111: .Ev PATH ,
112: .Ev TERM ,
1.5 millert 113: .Ev LOGNAME ,
1.1 deraadt 114: and
115: .Ev USER .
116: .Ev HOME
117: and
118: .Ev SHELL
119: are modified as above.
1.5 millert 120: .Ev LOGNAME
121: and
1.1 deraadt 122: .Ev USER
1.5 millert 123: are set to the target login.
1.1 deraadt 124: .Ev PATH
125: is set to
1.4 millert 126: .Dq Pa /usr/bin:/bin .
1.1 deraadt 127: .Ev TERM
128: is imported from your current environment.
129: The invoked shell is the target login's, and
1.8 aaron 130: .Nm
1.1 deraadt 131: will change directory to the target login's home directory.
132: .It Fl m
133: Leave the environment unmodified.
134: The invoked shell is your login shell, and no directory changes are made.
135: As a security precaution, if the target user's shell is a non-standard
136: shell (as defined by
137: .Xr getusershell 3 )
1.7 aaron 138: and the caller's real UID is
1.1 deraadt 139: non-zero,
1.8 aaron 140: .Nm
1.1 deraadt 141: will fail.
142: .El
143: .Pp
144: The
145: .Fl l
146: and
147: .Fl m
148: options are mutually exclusive; the last one specified
149: overrides any previous ones.
1.8 aaron 150: .Pp
151: If the optional
1.4 millert 152: .Ar "shell arguments"
1.8 aaron 153: are provided on the command line, they are passed to the login shell of
1.9 aaron 154: the target login.
155: This allows it to pass arbitrary commands via the
1.8 aaron 156: .Fl c
1.9 aaron 157: option as understood by most shells.
158: Note that
1.8 aaron 159: .Fl c
1.4 millert 160: usually expects a single argument only; you have to quote it when
1.8 aaron 161: passing multiple words.
1.1 deraadt 162: .Pp
1.2 deraadt 163: If group 0 (normally
1.1 deraadt 164: .Dq wheel )
1.2 deraadt 165: has users listed then only those users can
1.8 aaron 166: .Nm
1.2 deraadt 167: to
168: .Dq root .
1.6 provos 169: It is not sufficient to change a user's
170: .Pa /etc/passwd
171: entry to add them to the
172: .Dq wheel
173: group; they must explicitly be listed in
174: .Pa /etc/group .
175: If no one is in the
176: .Dq wheel
177: group, it is ignored, and anyone who knows the root password is permitted to
1.8 aaron 178: .Nm
1.1 deraadt 179: to
180: .Dq root .
181: .Pp
1.9 aaron 182: By default (unless the prompt is reset by a startup file) the superuser
1.1 deraadt 183: prompt is set to
184: .Dq Sy \&#
185: to remind one of its awesome power.
1.8 aaron 186: .Sh EXAMPLES
187: .Bl -tag -width 5n -compact
188: .It Li "su bin -c makewhatis"
189: Runs the command
190: .Li makewhatis
191: as user
192: .Li bin .
193: You will be asked for bin's password unless your real UID is 0.
1.4 millert 194: .Pp
195: .It Li "su bin -c 'makewhatis /usr/local/man'"
1.8 aaron 196: Same as above, but the target command consists of more than a
197: single word.
1.4 millert 198: .Pp
1.8 aaron 199: .It Li "su -l foo"
200: Pretend a login for user
201: .Li foo .
202: .El
1.1 deraadt 203: .Sh ENVIRONMENT
1.9 aaron 204: The following environment variables affect the execution of
1.1 deraadt 205: .Nm su :
1.9 aaron 206: .Bl -tag -width LOGNAME
1.1 deraadt 207: .It Ev HOME
208: Default home directory of real user ID unless modified as
209: specified above.
210: .It Ev PATH
211: Default search path of real user ID unless modified as specified above.
212: .It Ev TERM
213: Provides terminal type which may be retained for the substituted
214: user ID.
1.5 millert 215: .It Ev LOGNAME
1.1 deraadt 216: The user ID is always the effective ID (the target user ID) after an
1.8 aaron 217: .Nm
1.1 deraadt 218: unless the user ID is 0 (root).
1.5 millert 219: .It Ev USER
220: Same as
221: .Ev LOGNAME .
1.1 deraadt 222: .El
1.9 aaron 223: .Sh SEE ALSO
224: .Xr csh 1 ,
225: .Xr kerberos 1 ,
226: .Xr kinit 1 ,
227: .Xr login 1 ,
228: .Xr sh 1 ,
229: .Xr skey 1 ,
1.10 ! millert 230: .Xr setusercontext 3 ,
1.9 aaron 231: .Xr group 5 ,
1.10 ! millert 232: .Xr login.conf 5 ,
1.9 aaron 233: .Xr passwd 5 ,
234: .Xr environ 7
1.1 deraadt 235: .Sh HISTORY
236: A
237: .Nm
238: command appeared in
239: .At v7 .
240: The version described
241: here is an adaptation of the
242: .Tn MIT
243: Athena Kerberos command.