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