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