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