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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)su.1 8.2 (Berkeley) 4/18/94 33.\" $FreeBSD$ 34.\" 35.Dd April 18, 1994 36.Dt SU 1 37.Os 38.Sh NAME 39.Nm su 40.Nd substitute user identity 41.Sh SYNOPSIS 42.Nm 43.Op Fl 44.Op Fl flm 45.Op Fl c Ar class 46.Op Ar login Op Ar args 47.Sh DESCRIPTION 48.Nm Su 49requests appropriate user credentials via PAM 50and switches to that user ID 51(the default user is the superuser). 52A shell is then executed. 53.Pp 54PAM is used to set all policy. 55.Pp 56By default, the environment is unmodified with the exception of 57.Ev USER , 58.Ev HOME , 59and 60.Ev SHELL . 61.Ev HOME 62and 63.Ev SHELL 64are set to the target login's default values. 65.Ev USER 66is set to the target login, unless the target login has a user ID of 0, 67in which case it is unmodified. 68The invoked shell is the one belonging to the target login. 69This is the traditional behavior of 70.Nm . 71Resource limits and session priority applicable to the original user's 72login class (See 73.Xr login.conf 5 ) 74are also normally retained unless the target login as a user ID of 0. 75.Pp 76The options are as follows: 77.Bl -tag -width Ds 78.It Fl f 79If the invoked shell is 80.Xr csh 1 , 81this option prevents it from reading the 82.Dq Pa .cshrc 83file. 84.It Fl l 85Simulate a full login. 86The environment is discarded except for 87.Ev HOME , 88.Ev SHELL , 89.Ev PATH , 90.Ev TERM , 91and 92.Ev USER . 93.Ev HOME 94and 95.Ev SHELL 96are modified as above. 97.Ev USER 98is set to the target login. 99.Ev PATH 100is set to 101.Dq Pa /bin:/usr/bin . 102.Ev TERM 103is imported from your current environment. 104Environment variables may be set or overridden from the login class 105capabilities database according to the class of the target login. 106The invoked shell is the target login's, and 107.Nm 108will change directory to the target login's home directory. 109Resource limits and session priority are modified to that for the 110target account's login class. 111.It Fl 112(no letter) The same as 113.Fl l . 114.It Fl m 115Leave the environment unmodified. 116The invoked shell is your login shell, and no directory changes are made. 117As a security precaution, if the target user's shell is a non-standard 118shell (as defined by 119.Xr getusershell 3 ) 120and the caller's real uid is 121non-zero, 122.Nm 123will fail. 124.It Fl c Ar class 125Use the settings of the specified login class. 126Only allowed for the super-user. 127.El 128.Pp 129The 130.Fl l 131(or 132.Fl ) 133and 134.Fl m 135options are mutually exclusive; the last one specified 136overrides any previous ones. 137.Pp 138If the optional 139.Ar args 140are provided on the command line, they are passed to the login shell of 141the target login. 142.Pp 143By default (unless the prompt is reset by a startup file) the super-user 144prompt is set to 145.Dq Sy \&# 146to remind one of its awesome power. 147.Sh FILES 148.Bl -tag -width /etc/pam.conf -compact 149.It Pa /etc/pam.conf 150.Nm 151is configured with PAM support; it uses 152.Pa /etc/pam.conf 153entries with service name 154.Dq su 155.El 156.Sh SEE ALSO 157.Xr csh 1 , 158.Xr sh 1 , 159.Xr group 5 , 160.Xr login.conf 5 , 161.Xr passwd 5 , 162.Xr environ 7 , 163.Xr pam 8 164.Sh ENVIRONMENT 165Environment variables used by 166.Nm : 167.Bl -tag -width HOME 168.It Ev HOME 169Default home directory of real user ID unless modified as 170specified above. 171.It Ev PATH 172Default search path of real user ID unless modified as specified above. 173.It Ev TERM 174Provides terminal type which may be retained for the substituted 175user ID. 176.It Ev USER 177The user ID is always the effective ID (the target user ID) after an 178.Nm 179unless the user ID is 0 (root). 180.El 181.Sh EXAMPLES 182.Bl -tag -width 5n -compact 183.It Li "su man -c catman" 184Runs the command 185.Li catman 186as user 187.Li man . 188You will be asked for man's password unless your real UID is 0. 189.It Li "su man -c 'catman /usr/share/man /usr/local/man /usr/X11R6/man'" 190Same as above, but the target command constitutes of more than a 191single word and hence is quoted for use with the 192.Fl c 193option being passed to the shell. (Most shells expect the argument to 194.Fl c 195to be a single word). 196.It Li "su -c staff man -c 'catman /usr/share/man /usr/local/man /usr/X11R6/man'" 197Same as above, but the target command is run with the resource limits of 198the login class 199.Dq staff . 200Note: in this example, the first 201.Fl c 202option applies to 203.Nm 204while the second is an argument to the shell being invoked. 205.It Li "su -l foo" 206Simulate a login for user foo. 207.It Li "su - foo" 208Same as above. 209.It Li "su - " 210Simulate a login for root. 211.El 212.Sh HISTORY 213A 214.Nm 215command appeared in 216.At v1 . 217