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