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