1.\" $OpenBSD: su.1,v 1.24 2007/05/31 19:20:17 jmc Exp $ 2.\" 3.\" Copyright (c) 1988, 1990 The Regents of the University of California. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" from: @(#)su.1 6.12 (Berkeley) 7/29/91 31.\" 32.Dd $Mdocdate: May 31 2007 $ 33.Dt SU 1 34.Os 35.Sh NAME 36.Nm su 37.Nd substitute user identity 38.Sh SYNOPSIS 39.Nm su 40.Op Fl fKLlm 41.Op Fl a Ar auth-type 42.Op Fl c Ar login-class 43.Op Ar login Op Ar "shell arguments" 44.Sh DESCRIPTION 45.Nm 46requests the Kerberos password for 47.Ar login 48(or for 49.Dq Ar login Ns .root , 50if no login is provided), and switches to 51that user and group ID after obtaining a Kerberos ticket granting access. 52A shell is then executed, and any additional 53.Ar "shell arguments" 54after the login name 55are passed to the shell. 56.Nm 57will resort to the local password file to find the password for 58.Ar login 59if there is a Kerberos error or if Kerberos is not installed. 60If 61.Nm 62is executed by root, no password is requested and a shell 63with the appropriate user ID is executed; no additional Kerberos tickets 64are obtained. 65.Pp 66By default, the environment is unmodified with the exception of 67.Ev LOGNAME , 68.Ev HOME , 69.Ev SHELL , 70and 71.Ev USER . 72.Ev HOME 73and 74.Ev SHELL 75are set to the target login's default values. 76.Ev LOGNAME 77and 78.Ev USER 79are set to the target login, unless the target login has a user ID of 0 80and the 81.Fl l 82flag was not specified, 83in which case it is unmodified. 84The invoked shell is the target login's. 85This is the traditional behavior of 86.Nm su . 87.Pp 88If not using 89.Fl m 90and the target login has a user ID of 0 then the 91.Ev PATH 92variable and umask value 93(see 94.Xr umask 2 ) 95are always set according to the 96.Pa /etc/login.conf 97file (see 98.Xr login.conf 5 ) . 99.Pp 100The options are as follows: 101.Bl -tag -width Ds 102.It Fl 103Same as the 104.Fl l 105option (deprecated). 106.It Fl a Ar auth-type 107Specify an authentication type such as 108.Dq skey , 109.Dq securid , 110or 111.Dq krb5 . 112.It Fl c Ar login-class 113Specify a login class. 114You may only override the default class if you're already root. 115.It Fl f 116If the invoked shell is 117.Xr csh 1 , 118this option prevents it from reading the 119.Dq Pa .cshrc 120file. 121.It Fl K 122Do not attempt to use Kerberos to authenticate the user. 123.It Fl L 124Loop until a correct username and password combination is entered, 125similar to 126.Xr login 1 . 127Note that in this mode target 128.Ar login 129must be specified explicitly, either on the command line or interactively. 130Additionally, 131.Nm 132will prompt for the password even when invoked by root. 133.It Fl l 134Simulate a full login. 135The environment is discarded except for 136.Ev HOME , 137.Ev SHELL , 138.Ev PATH , 139.Ev TERM , 140.Ev LOGNAME , 141and 142.Ev USER . 143.Ev HOME 144and 145.Ev SHELL 146are modified as above. 147.Ev LOGNAME 148and 149.Ev USER 150are set to the target login. 151.Ev PATH 152is set to the value specified by the 153.Dq path 154entry in 155.Xr login.conf 5 . 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 m 162Leave the environment unmodified. 163The invoked shell is your login shell, and no directory changes are made. 164As a security precaution, if the target user's shell is a non-standard 165shell (as defined by 166.Xr getusershell 3 ) 167and the caller's real UID is 168non-zero, 169.Nm 170will fail. 171.El 172.Pp 173The 174.Fl l 175and 176.Fl m 177options are mutually exclusive; the last one specified 178overrides any previous ones. 179.Pp 180If the optional 181.Ar "shell arguments" 182are provided on the command line, they are passed to the login shell of 183the target login. 184This allows it to pass arbitrary commands via the 185.Fl c 186option as understood by most shells. 187Note that 188.Fl c 189usually expects a single argument only; you have to quote it when 190passing multiple words. 191.Pp 192If group 0 (normally 193.Dq wheel ) 194has users listed then only those users can 195.Nm 196to 197.Dq root . 198It is not sufficient to change a user's 199.Pa /etc/passwd 200entry to add them to the 201.Dq wheel 202group; they must explicitly be listed in 203.Pa /etc/group . 204If no one is in the 205.Dq wheel 206group, it is ignored, and anyone who knows the root password is permitted to 207.Nm 208to 209.Dq root . 210.Pp 211By default (unless the prompt is reset by a startup file) the superuser 212prompt is set to 213.Dq Sy \&# 214to remind one of its awesome power. 215.Sh ENVIRONMENT 216.Bl -tag -width LOGNAME 217.It Ev HOME 218Default home directory of real user ID unless modified as 219specified above. 220.It Ev LOGNAME 221The user ID is always the effective ID (the target user ID) after an 222.Nm 223unless the user ID is 0 (root). 224.It Ev PATH 225Default search path of real user ID unless modified as specified above. 226.It Ev TERM 227Provides terminal type which may be retained for the substituted 228user ID. 229.It Ev USER 230Same as 231.Ev LOGNAME . 232.El 233.Sh EXAMPLES 234Run the command 235.Dq makewhatis 236as user 237.Dq bin . 238You will be asked for bin's password unless your real UID is 0. 239.Pp 240.Dl $ su bin -c makewhatis 241.Pp 242Same as above, but the target command consists of more than a 243single word: 244.Pp 245.Dl $ su bin -c 'makewhatis /usr/local/man' 246.Pp 247Same as above, but the target command is run with the resource 248limits of the login class 249.Dq staff . 250Note that the first 251.Fl c 252option applies to 253.Nm 254while the second is an argument to the shell. 255.Pp 256.Dl $ su -c staff bin -c 'makewhatis /usr/local/man' 257.Pp 258Pretend a login for user 259.Dq foo : 260.Pp 261.Dl $ su -l foo 262.Pp 263Same as above, but use S/Key for authentication: 264.Pp 265.Dl $ su -a skey -l foo 266.Sh SEE ALSO 267.Xr csh 1 , 268.Xr kinit 1 , 269.Xr login 1 , 270.Xr sh 1 , 271.Xr skey 1 , 272.Xr setusercontext 3 , 273.Xr group 5 , 274.Xr login.conf 5 , 275.Xr passwd 5 , 276.Xr environ 7 , 277.Xr sudo 8 278.Sh HISTORY 279A 280.Nm 281command appeared in 282.At v7 . 283.Sh BUGS 284There is no direct way to force a particular shell to be used. 285.Pp 286The login name is not optional for root if there are shell arguments. 287