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