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