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.\" from: @(#)su.1 8.2 (Berkeley) 4/18/94 29.\" $NetBSD: su.1,v 1.54 2019/09/01 19:12:16 wiz Exp $ 30.\" 31.Dd September 1, 2019 32.Dt SU 1 33.Os 34.Sh NAME 35.Nm su 36.Nd substitute user identity 37.Sh SYNOPSIS 38.Nm 39.Op Fl dfKlm 40.Op Fl c Ar login-class 41.Oo 42.Ar login Ns Op : Ns Ar group 43.Op Ar "shell arguments" 44.Oc 45.Nm 46.Op Fl dfKlm 47.Op Fl c Ar login-class 48.Oo : Ns Ar group 49.Op Ar "shell arguments" 50.Oc 51.Sh DESCRIPTION 52.Nm 53allows one user to become another user 54.Ar login 55without logging out and in as 56the new user. 57If a 58.Ar group 59is specified and 60.Ar login 61is a member of 62.Ar group , 63then the group is changed to 64.Ar group 65rather than to 66.Ar login Ns 's 67primary group. 68If 69.Ar login 70is omitted and 71.Ar group 72is provided (form two above), then 73.Ar login 74is assumed to be the current username. 75.Pp 76When executed by a user, the 77.Ar login 78user's password is requested. 79When using Kerberos, the password for 80.Ar login 81(or for 82.Dq Ar login Ns .root , 83if no login is provided) is requested, and 84.Nm 85switches to that user and group ID after obtaining a Kerberos ticket 86granting ticket. 87A shell is then executed, and any additional 88.Ar "shell arguments" 89after the login name are passed to the shell. 90.Nm 91will resort to the local password file to find the password for 92.Ar login 93if there is a Kerberos error. 94If 95.Nm 96is executed by root, no password is requested and a shell 97with the appropriate user ID is executed; no additional Kerberos tickets 98are obtained. 99.Pp 100Alternatively, if the user enters the password "s/key", authentication 101will use the S/Key one-time password system as described in 102.Xr skey 1 . 103S/Key is a Trademark of Bellcore. 104.Pp 105By default, the environment is unmodified with the exception of 106.Ev LOGNAME , 107.Ev USER , 108.Ev HOME , 109.Ev SHELL , 110and 111.Ev SU_FROM . 112.Ev HOME 113and 114.Ev SHELL 115are set to the target login's default values. 116.Ev LOGNAME 117and 118.Ev USER 119are set to the target login, unless the target login has a user ID of 0, 120in which case they are unmodified. 121.Ev SU_FROM 122is set to the caller's login. 123The invoked shell is the target login's. 124With the exception of 125.Ev SU_FROM 126this is the traditional behavior of 127.Nm . 128.Pp 129The options are as follows: 130.Bl -tag -width Ds 131.It Fl c 132Specify a login class. 133You may only override the default class if you're already root. 134See 135.Xr login.conf 5 136for details. 137.It Fl d 138Same as 139.Fl l , 140but does not change the current directory. 141.It Fl f 142If the invoked shell is 143.Xr csh 1 , 144this option prevents it from reading the 145.Dq Pa .cshrc 146file. 147If the invoked shell is 148.Xr sh 1 , 149or 150.Xr ksh 1 , 151this option unsets 152.Ev ENV , 153thus preventing the shell from executing the startup file pointed to by 154this variable. 155.It Fl K 156Do not attempt to use Kerberos to authenticate the user. 157.It Fl l 158Simulate a full login. 159The environment is discarded except for 160.Ev HOME , 161.Ev SHELL , 162.Ev PATH , 163.Ev TERM , 164.Ev LOGNAME , 165.Ev USER , 166and 167.Ev SU_FROM . 168.Ev HOME , 169.Ev SHELL , 170and 171.Ev SU_FROM 172are modified as above. 173.Ev LOGNAME 174and 175.Ev USER 176are set to the target login. 177.Ev PATH 178is set to the path specified in the 179.Pa /etc/login.conf 180file (or to the default of 181.Dq Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin 182). 183.Ev TERM 184is imported from your current environment. 185The invoked shell is the target login's, and 186.Nm 187will change directory to the target login's home directory. 188The 189.Xr utmp 5 , 190.Xr wtmp 5 , 191and 192.Xr lastlog 5 193databases are not updated. 194.It Fl 195Same as 196.Fl l . 197.It Fl m 198Leave the environment unmodified. 199The invoked shell is your login shell, and no directory changes are made. 200As a security precaution, if the target user's shell is a non-standard 201shell (as defined by 202.Xr getusershell 3 ) 203and the caller's real uid is 204non-zero, 205.Nm 206will fail. 207.El 208.Pp 209The 210.Fl l 211and 212.Fl m 213options are mutually exclusive; the last one specified 214overrides any previous ones. 215.Pp 216Only users in group 217.Dq wheel 218(normally gid 0), 219as listed in 220.Pa /etc/group , 221can 222.Nm 223to 224.Dq root , 225unless group wheel does not exist or has no members. 226(If you do not want anybody to be able to 227.Nm 228to 229.Dq root , 230make 231.Dq root 232the only member of group 233.Dq wheel , 234which is the default.) 235.Pp 236For sites with very large user populations, group 237.Dq wheel 238can contain the names of other groups that will be considered authorized 239to 240.Nm 241to 242.Dq root . 243.Pp 244By default (unless the prompt is reset by a startup file) the super-user 245prompt is set to 246.Dq Sy \&# 247to remind one of its awesome power. 248.Sh CUSTOMIZATION 249.Bl -tag -width "" 250.It Changing required group 251For the 252.Xr pam 8 253version of 254.Nm 255the name of the required group can be changed by setting 256.Ar gname 257in 258.Xr pam.conf 5 : 259.Bd -literal 260auth requisite pam_group.so no_warn group=gname root_only fail_safe 261.Ed 262.Pp 263For the non 264.Xr pam 8 265version of 266.Nm 267the same can be achieved by compiling with 268.Dv SU_GROUP 269set to the desired group name. 270.It Supplying own password 271.Nm 272can be configured so that users in a particular group can supply their 273own password to become 274.Dq root . 275For the 276.Xr pam 8 277version of 278.Nm 279this can be done by adding a line to 280.Xr pam.conf 5 281such as: 282.Bd -literal 283auth sufficient pam_group.so no_warn group=gname root_only authenticate 284.Ed 285.Pp 286where 287.Ar gname 288is the name of the desired group. 289For the non 290.Xr pam 8 291version of 292.Nm 293the same can be achieved by compiling with 294.Dv SU_ROOTAUTH 295set to the desired group name. 296.It Indirect groups 297This option is not available with the 298.Xr pam 8 299version of 300.Nm . 301For the non 302.Xr pam 8 303version of 304.Nm , 305if 306.Dv SU_INDIRECT_GROUP 307is defined, the 308.Ar SU_GROUP 309and 310.Ar SU_ROOTAUTH 311groups are treated as indirect groups. 312The group members of those two groups are treated as groups themselves. 313.El 314.Sh ENVIRONMENT 315Environment variables used by 316.Nm : 317.Bl -tag -width "HOME" 318.It Ev HOME 319Default home directory of real user ID unless modified as 320specified above. 321.It Ev LOGNAME 322The user ID is always the effective ID (the target user ID) after an 323.Nm 324unless the user ID is 0 (root). 325.It Ev PATH 326Default search path of real user ID unless modified as specified above. 327.It Ev TERM 328Provides terminal type which may be retained for the substituted 329user ID. 330.It Ev USER 331The user ID is always the effective ID (the target user ID) after an 332.Nm 333unless the user ID is 0 (root). 334.El 335.Sh EXIT STATUS 336.Nm 337returns the exit status of the executed subshell, or 1 if any error 338occurred while switching privileges. 339.Sh EXAMPLES 340To become user username and use the same environment as in original shell, execute: 341.Bd -literal -offset indent 342su username 343.Ed 344.Pp 345To become user username and use environment as if full login would be performed, 346execute: 347.Bd -literal -offset indent 348su -l username 349.Ed 350.Pp 351When a 352.Fl c 353option is included 354.Em after 355the 356.Ar login 357name it is not a 358.Nm 359option, because any arguments after the 360.Ar login 361are passed to the shell. 362(See 363.Xr csh 1 , 364.Xr ksh 1 365or 366.Xr sh 1 367for details.) 368To execute arbitrary command with privileges of user 369.Em username , 370execute: 371.Bd -literal -offset indent 372su username -c "command args" 373.Ed 374.Sh SEE ALSO 375.Xr csh 1 , 376.Xr kinit 1 , 377.Xr login 1 , 378.Xr sh 1 , 379.Xr skey 1 , 380.Xr setusercontext 3 , 381.Xr group 5 , 382.Xr login.conf 5 , 383.Xr passwd 5 , 384.Xr environ 7 , 385.Xr kerberos 8 386.Sh HISTORY 387An 388.Nm 389utility appeared in 390.At v1 391