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