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