Annotation of src/usr.bin/su/su.1, Revision 1.28
1.28 ! millert 1: .\" $OpenBSD: su.1,v 1.27 2010/12/10 19:29:52 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.
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.28 ! millert 32: .Dd $Mdocdate: December 10 2010 $
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.26 sobrado 40: .Bk -words
1.16 millert 41: .Op Fl fKLlm
1.12 millert 42: .Op Fl a Ar auth-type
1.10 millert 43: .Op Fl c Ar login-class
1.25 millert 44: .Op Fl s Ar login-shell
1.1 deraadt 45: .Op Ar login Op Ar "shell arguments"
1.26 sobrado 46: .Ek
1.1 deraadt 47: .Sh DESCRIPTION
1.27 millert 48: The
1.8 aaron 49: .Nm
1.27 millert 50: utility allows a user to run a shell with the user and group ID of another user
51: without having to log out and in as that other user.
52: .Pp
53: If Kerberos is in use, the password for
1.1 deraadt 54: .Ar login
55: (or for
1.28 ! millert 56: .Dq Ar login Ns /root ,
1.27 millert 57: if no login is provided) is requested, and
58: .Nm
59: switches to
1.7 aaron 60: that user and group ID after obtaining a Kerberos ticket granting access.
1.1 deraadt 61: A shell is then executed, and any additional
62: .Ar "shell arguments"
63: after the login name
64: are passed to the shell.
1.27 millert 65: If Kerberos is not configured or if there is a Kerberos error,
1.8 aaron 66: .Nm
1.27 millert 67: falls back to local password authentication to validate the password for
68: .Ar login .
1.1 deraadt 69: If
1.8 aaron 70: .Nm
1.1 deraadt 71: is executed by root, no password is requested and a shell
72: with the appropriate user ID is executed; no additional Kerberos tickets
73: are obtained.
74: .Pp
75: By default, the environment is unmodified with the exception of
1.5 millert 76: .Ev LOGNAME ,
1.1 deraadt 77: .Ev HOME ,
1.12 millert 78: .Ev SHELL ,
1.1 deraadt 79: and
1.12 millert 80: .Ev USER .
1.1 deraadt 81: .Ev HOME
82: and
83: .Ev SHELL
84: are set to the target login's default values.
1.5 millert 85: .Ev LOGNAME
86: and
1.1 deraadt 87: .Ev USER
1.12 millert 88: are set to the target login, unless the target login has a user ID of 0
89: and the
90: .Fl l
91: flag was not specified,
1.1 deraadt 92: in which case it is unmodified.
93: The invoked shell is the target login's.
94: This is the traditional behavior of
95: .Nm su .
96: .Pp
1.12 millert 97: If not using
98: .Fl m
99: and the target login has a user ID of 0 then the
100: .Ev PATH
101: variable and umask value
1.19 jmc 102: (see
1.12 millert 103: .Xr umask 2 )
104: are always set according to the
105: .Pa /etc/login.conf
106: file (see
107: .Xr login.conf 5 ) .
108: .Pp
1.1 deraadt 109: The options are as follows:
110: .Bl -tag -width Ds
1.14 millert 111: .It Fl
112: Same as the
113: .Fl l
114: option (deprecated).
1.21 jmc 115: .It Fl a Ar auth-type
1.12 millert 116: Specify an authentication type such as
117: .Dq skey ,
118: .Dq securid ,
119: or
1.20 jmc 120: .Dq krb5 .
1.21 jmc 121: .It Fl c Ar login-class
1.10 millert 122: Specify a login class.
123: You may only override the default class if you're already root.
1.1 deraadt 124: .It Fl f
125: If the invoked shell is
126: .Xr csh 1 ,
127: this option prevents it from reading the
128: .Dq Pa .cshrc
129: file.
1.21 jmc 130: .It Fl K
131: Do not attempt to use Kerberos to authenticate the user.
1.27 millert 132: This is shorthand for
133: .Dq Nm Fl a Ar passwd ,
134: provided for backwards compatibility.
1.16 millert 135: .It Fl L
136: Loop until a correct username and password combination is entered,
137: similar to
138: .Xr login 1 .
139: Note that in this mode target
140: .Ar login
141: must be specified explicitly, either on the command line or interactively.
142: Additionally,
143: .Nm
144: will prompt for the password even when invoked by root.
1.1 deraadt 145: .It Fl l
146: Simulate a full login.
147: The environment is discarded except for
148: .Ev HOME ,
149: .Ev SHELL ,
150: .Ev PATH ,
151: .Ev TERM ,
1.5 millert 152: .Ev LOGNAME ,
1.1 deraadt 153: and
154: .Ev USER .
155: .Ev HOME
156: and
157: .Ev SHELL
158: are modified as above.
1.5 millert 159: .Ev LOGNAME
160: and
1.1 deraadt 161: .Ev USER
1.5 millert 162: are set to the target login.
1.1 deraadt 163: .Ev PATH
1.12 millert 164: is set to the value specified by the
165: .Dq path
166: entry in
167: .Xr login.conf 5 .
1.1 deraadt 168: .Ev TERM
169: is imported from your current environment.
170: The invoked shell is the target login's, and
1.8 aaron 171: .Nm
1.1 deraadt 172: will change directory to the target login's home directory.
173: .It Fl m
174: Leave the environment unmodified.
175: The invoked shell is your login shell, and no directory changes are made.
176: As a security precaution, if the target user's shell is a non-standard
177: shell (as defined by
178: .Xr getusershell 3 )
1.7 aaron 179: and the caller's real UID is
1.1 deraadt 180: non-zero,
1.8 aaron 181: .Nm
1.1 deraadt 182: will fail.
1.25 millert 183: .It Fl s Ar login-shell
184: Specify the path to an alternate login shell.
185: You may only override the shell if you're already root.
186: This option will override the shell even if the
187: .Fl m
188: option is specified.
1.1 deraadt 189: .El
190: .Pp
191: The
192: .Fl l
193: and
194: .Fl m
195: options are mutually exclusive; the last one specified
196: overrides any previous ones.
1.8 aaron 197: .Pp
198: If the optional
1.4 millert 199: .Ar "shell arguments"
1.8 aaron 200: are provided on the command line, they are passed to the login shell of
1.9 aaron 201: the target login.
202: This allows it to pass arbitrary commands via the
1.8 aaron 203: .Fl c
1.9 aaron 204: option as understood by most shells.
205: Note that
1.8 aaron 206: .Fl c
1.4 millert 207: usually expects a single argument only; you have to quote it when
1.8 aaron 208: passing multiple words.
1.1 deraadt 209: .Pp
1.2 deraadt 210: If group 0 (normally
1.1 deraadt 211: .Dq wheel )
1.2 deraadt 212: has users listed then only those users can
1.8 aaron 213: .Nm
1.2 deraadt 214: to
215: .Dq root .
1.6 provos 216: It is not sufficient to change a user's
217: .Pa /etc/passwd
218: entry to add them to the
219: .Dq wheel
220: group; they must explicitly be listed in
221: .Pa /etc/group .
222: If no one is in the
223: .Dq wheel
224: group, it is ignored, and anyone who knows the root password is permitted to
1.8 aaron 225: .Nm
1.1 deraadt 226: to
227: .Dq root .
228: .Pp
1.9 aaron 229: By default (unless the prompt is reset by a startup file) the superuser
1.1 deraadt 230: prompt is set to
231: .Dq Sy \&#
232: to remind one of its awesome power.
1.19 jmc 233: .Sh ENVIRONMENT
234: .Bl -tag -width LOGNAME
235: .It Ev HOME
236: Default home directory of real user ID unless modified as
237: specified above.
238: .It Ev LOGNAME
239: The user ID is always the effective ID (the target user ID) after an
240: .Nm
241: unless the user ID is 0 (root).
242: .It Ev PATH
243: Default search path of real user ID unless modified as specified above.
244: .It Ev TERM
245: Provides terminal type which may be retained for the substituted
246: user ID.
247: .It Ev USER
248: Same as
249: .Ev LOGNAME .
250: .El
1.8 aaron 251: .Sh EXAMPLES
1.23 jmc 252: Run the command
253: .Dq makewhatis
1.8 aaron 254: as user
1.23 jmc 255: .Dq bin .
1.8 aaron 256: You will be asked for bin's password unless your real UID is 0.
1.4 millert 257: .Pp
1.23 jmc 258: .Dl $ su bin -c makewhatis
259: .Pp
1.8 aaron 260: Same as above, but the target command consists of more than a
1.23 jmc 261: single word:
262: .Pp
263: .Dl $ su bin -c 'makewhatis /usr/local/man'
1.22 jmc 264: .Pp
265: Same as above, but the target command is run with the resource
266: limits of the login class
267: .Dq staff .
268: Note that the first
269: .Fl c
270: option applies to
271: .Nm
272: while the second is an argument to the shell.
1.4 millert 273: .Pp
1.23 jmc 274: .Dl $ su -c staff bin -c 'makewhatis /usr/local/man'
275: .Pp
1.8 aaron 276: Pretend a login for user
1.23 jmc 277: .Dq foo :
1.15 millert 278: .Pp
1.23 jmc 279: .Dl $ su -l foo
280: .Pp
281: Same as above, but use S/Key for authentication:
282: .Pp
283: .Dl $ su -a skey -l foo
1.9 aaron 284: .Sh SEE ALSO
285: .Xr csh 1 ,
286: .Xr kinit 1 ,
287: .Xr login 1 ,
288: .Xr sh 1 ,
289: .Xr skey 1 ,
1.10 millert 290: .Xr setusercontext 3 ,
1.9 aaron 291: .Xr group 5 ,
1.10 millert 292: .Xr login.conf 5 ,
1.9 aaron 293: .Xr passwd 5 ,
1.13 heko 294: .Xr environ 7 ,
295: .Xr sudo 8
1.1 deraadt 296: .Sh HISTORY
297: A
298: .Nm
299: command appeared in
300: .At v7 .
1.12 millert 301: .Sh BUGS
302: 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