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