1.\" Copyright (c) 1988, 1990, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)su.1 8.2 (Berkeley) 4/18/94 29.\" 30.Dd March 26, 2020 31.Dt SU 1 32.Os 33.Sh NAME 34.Nm su 35.Nd substitute user identity 36.Sh SYNOPSIS 37.Nm 38.Op Fl 39.Op Fl c Ar class 40.Op Fl flms 41.Op Ar login Op Ar args 42.Sh DESCRIPTION 43The 44.Nm 45utility requests appropriate user credentials via PAM 46and switches to that user ID 47(the default user is the superuser). 48A shell is then executed. 49.Pp 50PAM is used to set the policy 51.Xr su 1 52will use. 53In particular, by default only users in the 54.Dq Li wheel 55group can switch to UID 0 56.Pq Dq Li root . 57This group requirement may be changed by modifying the 58.Dq Li pam_group 59section of 60.Pa /etc/pam.d/su . 61See 62.Xr pam_group 8 63for details on how to modify this setting. 64.Pp 65By default, the environment is unmodified with the exception of 66.Ev USER , 67.Ev HOME , 68and 69.Ev SHELL . 70.Ev HOME 71and 72.Ev SHELL 73are set to the target login's default values. 74.Ev USER 75is set to the target login, unless the target login has a user ID of 0, 76in which case it is unmodified. 77The invoked shell is the one belonging to the target login. 78This is the traditional behavior of 79.Nm . 80Resource limits and session priority applicable to the original user's 81login class (see 82.Xr login.conf 5 ) 83are also normally retained unless the target login has a user ID of 0. 84.Pp 85The options are as follows: 86.Bl -tag -width Ds 87.It Fl c Ar class 88Use the settings of the specified login class. 89The login class must be defined in 90.Xr login.conf 5 . 91Only allowed for the super-user. 92.It Fl f 93If the invoked shell is 94.Xr csh 1 , 95this option prevents it from reading the 96.Dq Pa .cshrc 97file. 98.It Fl l 99Simulate a full login. 100The environment is discarded except for 101.Ev HOME , 102.Ev SHELL , 103.Ev PATH , 104.Ev TERM , 105and 106.Ev USER . 107.Ev HOME 108and 109.Ev SHELL 110are modified as above. 111.Ev USER 112is set to the target login. 113.Ev PATH 114is set to 115.Dq Pa /bin:/usr/bin . 116.Ev TERM 117is imported from your current environment. 118Environment variables may be set or overridden from the login class 119capabilities database according to the class of the target login. 120The invoked shell is the target login's, and 121.Nm 122will change directory to the target login's home directory. 123Resource limits and session priority are modified to that for the 124target account's login class. 125.It Fl 126(no letter) The same as 127.Fl l . 128.It Fl m 129Leave the environment unmodified. 130The invoked shell is your login shell, and no directory changes are made. 131As a security precaution, if the target user's shell is a non-standard 132shell (as defined by 133.Xr getusershell 3 ) 134and the caller's real uid is 135non-zero, 136.Nm 137will fail. 138.It Fl s 139Set the MAC label to the user's default label as part of the user 140credential setup. 141Setting the MAC label may fail if the MAC label of the invoking process 142is not sufficient to transition to the user's default MAC label. 143If the label cannot be set, 144.Nm 145will fail. 146.El 147.Pp 148The 149.Fl l 150(or 151.Fl ) 152and 153.Fl m 154options are mutually exclusive; the last one specified 155overrides any previous ones. 156.Pp 157If the optional 158.Ar args 159are provided on the command line, they are passed to the login shell of 160the target login. 161Note that all command line arguments before the target login name are 162processed by 163.Nm 164itself, everything after the target login name gets passed to the login 165shell. 166.Pp 167By default (unless the prompt is reset by a startup file) the super-user 168prompt is set to 169.Dq Sy \&# 170to remind one of its awesome power. 171.Sh ENVIRONMENT 172Environment variables used by 173.Nm : 174.Bl -tag -width HOME 175.It Ev HOME 176Default home directory of real user ID unless modified as 177specified above. 178.It Ev PATH 179Default search path of real user ID unless modified as specified above. 180.It Ev TERM 181Provides terminal type which may be retained for the substituted 182user ID. 183.It Ev USER 184The user ID is always the effective ID (the target user ID) after an 185.Nm 186unless the user ID is 0 (root). 187.El 188.Sh FILES 189.Bl -tag -width "/etc/pam.d/su" -compact 190.It Pa /etc/pam.d/su 191PAM configuration for 192.Nm . 193.El 194.Sh EXAMPLES 195.Bl -tag -width 5n -compact 196.It Li "su -m operator -c poweroff" 197Starts a shell as user 198.Li operator , 199and runs the command 200.Li poweroff . 201You will be asked for operator's password unless your real UID is 0. 202Note that the 203.Fl m 204option is required since user 205.Dq operator 206does not have a valid shell by default. 207In this example, 208.Fl c 209is passed to the shell of the user 210.Dq operator , 211and is not interpreted as an argument to 212.Nm . 213.It Li "su -m operator -c 'shutdown -p now'" 214Same as above, but the target command consists of more than a 215single word and hence is quoted for use with the 216.Fl c 217option being passed to the shell. 218(Most shells expect the argument to 219.Fl c 220to be a single word). 221.It Li "su -m -c staff operator -c 'shutdown -p now'" 222Same as above, but the target command is run with the resource limits of 223the login class 224.Dq staff . 225Note: in this example, the first 226.Fl c 227option applies to 228.Nm 229while the second is an argument to the shell being invoked. 230.It Li "su -l foo" 231Simulate a login for user foo. 232.It Li "su - foo" 233Same as above. 234.It Li "su -" 235Simulate a login for root. 236.El 237.Sh SEE ALSO 238.Xr csh 1 , 239.Xr sh 1 , 240.Xr group 5 , 241.Xr login.conf 5 , 242.Xr passwd 5 , 243.Xr environ 7 , 244.Xr pam_group 8 245.Sh HISTORY 246A 247.Nm 248command appeared in 249.At v1 . 250