Annotation of src/usr.bin/su/su.1, Revision 1.38
1.38 ! kn 1: .\" $OpenBSD: su.1,v 1.37 2020/07/08 16:05:27 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.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.38 ! kn 45: .Op Ar login Op Ar shell-argument ...
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
1.38 ! kn 171: If shell arguments are provided on the command line,
! 172: they are passed to the login shell of the target login.
1.9 aaron 173: This allows it to pass arbitrary commands via the
1.8 aaron 174: .Fl c
1.9 aaron 175: option as understood by most shells.
176: Note that
1.8 aaron 177: .Fl c
1.4 millert 178: usually expects a single argument only; you have to quote it when
1.8 aaron 179: passing multiple words.
1.1 deraadt 180: .Pp
1.2 deraadt 181: If group 0 (normally
1.1 deraadt 182: .Dq wheel )
1.2 deraadt 183: has users listed then only those users can
1.8 aaron 184: .Nm
1.2 deraadt 185: to
186: .Dq root .
1.6 provos 187: It is not sufficient to change a user's
188: .Pa /etc/passwd
189: entry to add them to the
190: .Dq wheel
191: group; they must explicitly be listed in
192: .Pa /etc/group .
193: If no one is in the
194: .Dq wheel
195: group, it is ignored, and anyone who knows the root password is permitted to
1.8 aaron 196: .Nm
1.1 deraadt 197: to
198: .Dq root .
1.19 jmc 199: .Sh ENVIRONMENT
1.34 schwarze 200: The following list provides the values of environment variables
201: in the new shell that is started by
202: .Nm .
1.19 jmc 203: .Bl -tag -width LOGNAME
204: .It Ev HOME
1.34 schwarze 205: The home directory of the target login, except that it remains unchanged with
206: .Fl m .
1.19 jmc 207: .It Ev LOGNAME
1.34 schwarze 208: The target login by default, but unchanged if the target login has
209: a UID of 0 or if
210: .Fl m
211: is given.
1.19 jmc 212: .It Ev PATH
1.34 schwarze 213: The search path.
214: It remains unchanged by default, but is set according to the target login
215: if the target login has a UID of 0 or if
216: .Fl l
217: is given.
218: .It Ev PWD
219: The current working directory.
220: It remains unchanged by default,
221: but is set to the home directory of the target login with
222: .Fl l .
223: .It Ev SHELL
224: The new shell that is started.
225: It is the shell of the target login by default,
226: but the shell of the invoking user with
227: .Fl m .
1.19 jmc 228: .It Ev TERM
1.34 schwarze 229: The terminal type.
230: It is always retained from the invoking process.
1.19 jmc 231: .It Ev USER
232: Same as
233: .Ev LOGNAME .
234: .El
1.8 aaron 235: .Sh EXAMPLES
1.23 jmc 236: Run the command
237: .Dq makewhatis
1.8 aaron 238: as user
1.23 jmc 239: .Dq bin .
1.8 aaron 240: You will be asked for bin's password unless your real UID is 0.
1.4 millert 241: .Pp
1.23 jmc 242: .Dl $ su bin -c makewhatis
243: .Pp
1.8 aaron 244: Same as above, but the target command consists of more than a
1.23 jmc 245: single word:
246: .Pp
247: .Dl $ su bin -c 'makewhatis /usr/local/man'
1.22 jmc 248: .Pp
249: Same as above, but the target command is run with the resource
250: limits of the login class
251: .Dq staff .
252: Note that the first
253: .Fl c
254: option applies to
255: .Nm
256: while the second is an argument to the shell.
1.4 millert 257: .Pp
1.23 jmc 258: .Dl $ su -c staff bin -c 'makewhatis /usr/local/man'
259: .Pp
1.8 aaron 260: Pretend a login for user
1.23 jmc 261: .Dq foo :
1.15 millert 262: .Pp
1.23 jmc 263: .Dl $ su -l foo
264: .Pp
265: Same as above, but use S/Key for authentication:
266: .Pp
267: .Dl $ su -a skey -l foo
1.9 aaron 268: .Sh SEE ALSO
1.31 jmc 269: .Xr doas 1 ,
1.9 aaron 270: .Xr login 1 ,
1.10 millert 271: .Xr setusercontext 3 ,
1.9 aaron 272: .Xr group 5 ,
1.10 millert 273: .Xr login.conf 5 ,
1.9 aaron 274: .Xr passwd 5 ,
1.31 jmc 275: .Xr environ 7
1.1 deraadt 276: .Sh HISTORY
277: A
278: .Nm
1.33 schwarze 279: command first appeared in
280: .At v1 .
1.12 millert 281: .Sh BUGS
282: 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