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