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