1.\" $OpenBSD: su.1,v 1.30 2014/04/24 14:14:08 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: April 24 2014 $ 33.Dt SU 1 34.Os 35.Sh NAME 36.Nm su 37.Nd substitute user identity 38.Sh SYNOPSIS 39.Nm su 40.Bk -words 41.Op Fl fKLlm 42.Op Fl a Ar auth-type 43.Op Fl c Ar login-class 44.Op Fl s Ar login-shell 45.Op Ar login Op Ar "shell arguments" 46.Ek 47.Sh DESCRIPTION 48The 49.Nm 50utility allows a user to run a shell with the user and group ID of another user 51without having to log out and in as that other user. 52.Pp 53By default, the environment is unmodified with the exception of 54.Ev LOGNAME , 55.Ev HOME , 56.Ev SHELL , 57and 58.Ev USER . 59.Ev HOME 60and 61.Ev SHELL 62are set to the target login's default values. 63.Ev LOGNAME 64and 65.Ev USER 66are set to the target login, unless the target login has a user ID of 0 67and the 68.Fl l 69flag was not specified, 70in which case it is unmodified. 71The invoked shell is the target login's. 72This is the traditional behavior of 73.Nm su . 74.Pp 75If not using 76.Fl m 77and the target login has a user ID of 0 then the 78.Ev PATH 79variable and umask value 80(see 81.Xr umask 2 ) 82are always set according to the 83.Pa /etc/login.conf 84file (see 85.Xr login.conf 5 ) . 86.Pp 87The options are as follows: 88.Bl -tag -width Ds 89.It Fl 90Same as the 91.Fl l 92option (deprecated). 93.It Fl a Ar auth-type 94Specify an authentication type such as 95.Dq skey 96or 97.Dq radius . 98.It Fl c Ar login-class 99Specify a login class. 100You may only override the default class if you're already root. 101.It Fl f 102If the invoked shell is 103.Xr csh 1 , 104this option prevents it from reading the 105.Dq Pa .cshrc 106file. 107.It Fl K 108This is shorthand for 109.Dq Nm Fl a Ar passwd , 110provided for backwards compatibility. 111.It Fl L 112Loop until a correct username and password combination is entered, 113similar to 114.Xr login 1 . 115Note that in this mode target 116.Ar login 117must be specified explicitly, either on the command line or interactively. 118Additionally, 119.Nm 120will prompt for the password even when invoked by root. 121.It Fl l 122Simulate a full login. 123The environment is discarded except for 124.Ev HOME , 125.Ev SHELL , 126.Ev PATH , 127.Ev TERM , 128.Ev LOGNAME , 129and 130.Ev USER . 131.Ev HOME 132and 133.Ev SHELL 134are modified as above. 135.Ev LOGNAME 136and 137.Ev USER 138are set to the target login. 139.Ev PATH 140is set to the value specified by the 141.Dq path 142entry in 143.Xr login.conf 5 . 144.Ev TERM 145is imported from your current environment. 146The invoked shell is the target login's, and 147.Nm 148will change directory to the target login's home directory. 149.It Fl m 150Leave the environment unmodified. 151The invoked shell is your login shell, and no directory changes are made. 152As a security precaution, if the target user's shell is a non-standard 153shell (as defined by 154.Xr getusershell 3 ) 155and the caller's real UID is 156non-zero, 157.Nm 158will fail. 159.It Fl s Ar login-shell 160Specify the path to an alternate login shell. 161You may only override the shell if you're already root. 162This option will override the shell even if the 163.Fl m 164option is specified. 165.El 166.Pp 167The 168.Fl l 169and 170.Fl m 171options are mutually exclusive; the last one specified 172overrides any previous ones. 173.Pp 174If the optional 175.Ar "shell arguments" 176are provided on the command line, they are passed to the login shell of 177the target login. 178This allows it to pass arbitrary commands via the 179.Fl c 180option as understood by most shells. 181Note that 182.Fl c 183usually expects a single argument only; you have to quote it when 184passing multiple words. 185.Pp 186If group 0 (normally 187.Dq wheel ) 188has users listed then only those users can 189.Nm 190to 191.Dq root . 192It is not sufficient to change a user's 193.Pa /etc/passwd 194entry to add them to the 195.Dq wheel 196group; they must explicitly be listed in 197.Pa /etc/group . 198If no one is in the 199.Dq wheel 200group, it is ignored, and anyone who knows the root password is permitted to 201.Nm 202to 203.Dq root . 204.Pp 205By default (unless the prompt is reset by a startup file) the superuser 206prompt is set to 207.Dq Sy \&# 208to remind one of its awesome power. 209.Sh ENVIRONMENT 210.Bl -tag -width LOGNAME 211.It Ev HOME 212Default home directory of real user ID unless modified as 213specified above. 214.It Ev LOGNAME 215The user ID is always the effective ID (the target user ID) after an 216.Nm 217unless the user ID is 0 (root). 218.It Ev PATH 219Default search path of real user ID unless modified as specified above. 220.It Ev TERM 221Provides terminal type which may be retained for the substituted 222user ID. 223.It Ev USER 224Same as 225.Ev LOGNAME . 226.El 227.Sh EXAMPLES 228Run the command 229.Dq makewhatis 230as user 231.Dq bin . 232You will be asked for bin's password unless your real UID is 0. 233.Pp 234.Dl $ su bin -c makewhatis 235.Pp 236Same as above, but the target command consists of more than a 237single word: 238.Pp 239.Dl $ su bin -c 'makewhatis /usr/local/man' 240.Pp 241Same as above, but the target command is run with the resource 242limits of the login class 243.Dq staff . 244Note that the first 245.Fl c 246option applies to 247.Nm 248while the second is an argument to the shell. 249.Pp 250.Dl $ su -c staff bin -c 'makewhatis /usr/local/man' 251.Pp 252Pretend a login for user 253.Dq foo : 254.Pp 255.Dl $ su -l foo 256.Pp 257Same as above, but use S/Key for authentication: 258.Pp 259.Dl $ su -a skey -l foo 260.Sh SEE ALSO 261.Xr login 1 , 262.Xr setusercontext 3 , 263.Xr group 5 , 264.Xr login.conf 5 , 265.Xr passwd 5 , 266.Xr environ 7 , 267.Xr sudo 8 268.Sh HISTORY 269A 270.Nm 271command appeared in 272.At v7 . 273.Sh BUGS 274The login name is not optional for root if there are shell arguments. 275