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.Dd March 26, 2020 29.Dt SU 1 30.Os 31.Sh NAME 32.Nm su 33.Nd substitute user identity 34.Sh SYNOPSIS 35.Nm 36.Op Fl 37.Op Fl c Ar class 38.Op Fl flms 39.Op Ar login Op Ar args 40.Sh DESCRIPTION 41The 42.Nm 43utility requests appropriate user credentials via PAM 44and switches to that user ID 45(the default user is the superuser). 46A shell is then executed. 47.Pp 48PAM is used to set the policy 49.Xr su 1 50will use. 51In particular, by default only users in the 52.Dq Li wheel 53group can switch to UID 0 54.Pq Dq Li root . 55This group requirement may be changed by modifying the 56.Dq Li pam_group 57section of 58.Pa /etc/pam.d/su . 59See 60.Xr pam_group 8 61for details on how to modify this setting. 62.Pp 63By default, the environment is unmodified with the exception of 64.Ev USER , 65.Ev HOME , 66and 67.Ev SHELL . 68.Ev HOME 69and 70.Ev SHELL 71are set to the target login's default values. 72.Ev USER 73is set to the target login, unless the target login has a user ID of 0, 74in which case it is unmodified. 75The invoked shell is the one belonging to the target login. 76This is the traditional behavior of 77.Nm . 78Resource limits and session priority applicable to the original user's 79login class (see 80.Xr login.conf 5 ) 81are also normally retained unless the target login has a user ID of 0. 82.Pp 83The options are as follows: 84.Bl -tag -width Ds 85.It Fl c Ar class 86Use the settings of the specified login class. 87The login class must be defined in 88.Xr login.conf 5 . 89Only allowed for the super-user. 90.It Fl f 91If the invoked shell is 92.Xr csh 1 , 93this option prevents it from reading the 94.Dq Pa .cshrc 95file. 96.It Fl l 97Simulate a full login. 98The environment is discarded except for 99.Ev HOME , 100.Ev SHELL , 101.Ev PATH , 102.Ev TERM , 103and 104.Ev USER . 105.Ev HOME 106and 107.Ev SHELL 108are modified as above. 109.Ev USER 110is set to the target login. 111.Ev PATH 112is set to 113.Dq Pa /bin:/usr/bin . 114.Ev TERM 115is imported from your current environment. 116Environment variables may be set or overridden from the login class 117capabilities database according to the class of the target login. 118The invoked shell is the target login's, and 119.Nm 120will change directory to the target login's home directory. 121Resource limits and session priority are modified to that for the 122target account's login class. 123.It Fl 124(no letter) The same as 125.Fl l . 126.It Fl m 127Leave the environment unmodified. 128The invoked shell is your login shell, and no directory changes are made. 129As a security precaution, if the target user's shell is a non-standard 130shell (as defined by 131.Xr getusershell 3 ) 132and the caller's real uid is 133non-zero, 134.Nm 135will fail. 136.It Fl s 137Set the MAC label to the user's default label as part of the user 138credential setup. 139Setting the MAC label may fail if the MAC label of the invoking process 140is not sufficient to transition to the user's default MAC label. 141If the label cannot be set, 142.Nm 143will fail. 144.El 145.Pp 146The 147.Fl l 148(or 149.Fl ) 150and 151.Fl m 152options are mutually exclusive; the last one specified 153overrides any previous ones. 154.Pp 155If the optional 156.Ar args 157are provided on the command line, they are passed to the login shell of 158the target login. 159Note that all command line arguments before the target login name are 160processed by 161.Nm 162itself, everything after the target login name gets passed to the login 163shell. 164.Pp 165By default (unless the prompt is reset by a startup file) the super-user 166prompt is set to 167.Dq Sy \&# 168to remind one of its awesome power. 169.Sh ENVIRONMENT 170Environment variables used by 171.Nm : 172.Bl -tag -width HOME 173.It Ev HOME 174Default home directory of real user ID unless modified as 175specified above. 176.It Ev PATH 177Default search path of real user ID unless modified as specified above. 178.It Ev TERM 179Provides terminal type which may be retained for the substituted 180user ID. 181.It Ev USER 182The user ID is always the effective ID (the target user ID) after an 183.Nm 184unless the user ID is 0 (root). 185.El 186.Sh FILES 187.Bl -tag -width "/etc/pam.d/su" -compact 188.It Pa /etc/pam.d/su 189PAM configuration for 190.Nm . 191.El 192.Sh EXAMPLES 193.Bl -tag -width 5n -compact 194.It Li "su -m operator -c poweroff" 195Starts a shell as user 196.Li operator , 197and runs the command 198.Li poweroff . 199You will be asked for operator's password unless your real UID is 0. 200Note that the 201.Fl m 202option is required since user 203.Dq operator 204does not have a valid shell by default. 205In this example, 206.Fl c 207is passed to the shell of the user 208.Dq operator , 209and is not interpreted as an argument to 210.Nm . 211.It Li "su -m operator -c 'shutdown -p now'" 212Same as above, but the target command consists of more than a 213single word and hence is quoted for use with the 214.Fl c 215option being passed to the shell. 216(Most shells expect the argument to 217.Fl c 218to be a single word). 219.It Li "su -m -c staff operator -c 'shutdown -p now'" 220Same as above, but the target command is run with the resource limits of 221the login class 222.Dq staff . 223Note: in this example, the first 224.Fl c 225option applies to 226.Nm 227while the second is an argument to the shell being invoked. 228.It Li "su -l foo" 229Simulate a login for user foo. 230.It Li "su - foo" 231Same as above. 232.It Li "su -" 233Simulate a login for root. 234.El 235.Sh SEE ALSO 236.Xr csh 1 , 237.Xr sh 1 , 238.Xr group 5 , 239.Xr login.conf 5 , 240.Xr passwd 5 , 241.Xr environ 7 , 242.Xr pam_group 8 243.Sh HISTORY 244A 245.Nm 246command appeared in 247.At v1 . 248