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