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