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 48The 49.Nm 50utility requests appropriate user credentials via PAM 51and switches to that user ID 52(the default user is the superuser). 53A shell is then executed. 54.Pp 55PAM is used to set all policy. 56.Pp 57By default, the environment is unmodified with the exception of 58.Ev USER , 59.Ev HOME , 60and 61.Ev SHELL . 62.Ev HOME 63and 64.Ev SHELL 65are set to the target login's default values. 66.Ev USER 67is set to the target login, unless the target login has a user ID of 0, 68in which case it is unmodified. 69The invoked shell is the one belonging to the target login. 70This is the traditional behavior of 71.Nm . 72Resource limits and session priority applicable to the original user's 73login class (See 74.Xr login.conf 5 ) 75are also normally retained unless the target login has a user ID of 0. 76.Pp 77The options are as follows: 78.Bl -tag -width Ds 79.It Fl f 80If the invoked shell is 81.Xr csh 1 , 82this option prevents it from reading the 83.Dq Pa .cshrc 84file. 85.It Fl l 86Simulate a full login. 87The environment is discarded except for 88.Ev HOME , 89.Ev SHELL , 90.Ev PATH , 91.Ev TERM , 92and 93.Ev USER . 94.Ev HOME 95and 96.Ev SHELL 97are modified as above. 98.Ev USER 99is set to the target login. 100.Ev PATH 101is set to 102.Dq Pa /bin:/usr/bin . 103.Ev TERM 104is imported from your current environment. 105Environment variables may be set or overridden from the login class 106capabilities database according to the class of the target login. 107The invoked shell is the target login's, and 108.Nm 109will change directory to the target login's home directory. 110Resource limits and session priority are modified to that for the 111target account's login class. 112.It Fl 113(no letter) The same as 114.Fl l . 115.It Fl m 116Leave the environment unmodified. 117The invoked shell is your login shell, and no directory changes are made. 118As a security precaution, if the target user's shell is a non-standard 119shell (as defined by 120.Xr getusershell 3 ) 121and the caller's real uid is 122non-zero, 123.Nm 124will fail. 125.It Fl c Ar class 126Use the settings of the specified login class. 127Only allowed for the super-user. 128.El 129.Pp 130The 131.Fl l 132(or 133.Fl ) 134and 135.Fl m 136options are mutually exclusive; the last one specified 137overrides any previous ones. 138.Pp 139If the optional 140.Ar args 141are provided on the command line, they are passed to the login shell of 142the target login. 143.Pp 144By default (unless the prompt is reset by a startup file) the super-user 145prompt is set to 146.Dq Sy \&# 147to remind one of its awesome power. 148.Sh FILES 149.Bl -tag -width /etc/pam.conf -compact 150.It Pa /etc/pam.conf 151.Nm 152is configured with PAM support; it uses 153.Pa /etc/pam.conf 154entries with service name 155.Dq su 156.El 157.Sh SEE ALSO 158.Xr csh 1 , 159.Xr sh 1 , 160.Xr group 5 , 161.Xr login.conf 5 , 162.Xr passwd 5 , 163.Xr environ 7 , 164.Xr pam 8 165.Sh ENVIRONMENT 166Environment variables used by 167.Nm : 168.Bl -tag -width HOME 169.It Ev HOME 170Default home directory of real user ID unless modified as 171specified above. 172.It Ev PATH 173Default search path of real user ID unless modified as specified above. 174.It Ev TERM 175Provides terminal type which may be retained for the substituted 176user ID. 177.It Ev USER 178The user ID is always the effective ID (the target user ID) after an 179.Nm 180unless the user ID is 0 (root). 181.El 182.Sh EXAMPLES 183.Bl -tag -width 5n -compact 184.It Li "su man -c catman" 185Runs the command 186.Li catman 187as user 188.Li man . 189You will be asked for man's password unless your real UID is 0. 190.It Li "su man -c 'catman /usr/share/man /usr/local/man /usr/X11R6/man'" 191Same as above, but the target command consists of more than a 192single word and hence is quoted for use with the 193.Fl c 194option being passed to the shell. (Most shells expect the argument to 195.Fl c 196to be a single word). 197.It Li "su -c staff man -c 'catman /usr/share/man /usr/local/man /usr/X11R6/man'" 198Same as above, but the target command is run with the resource limits of 199the login class 200.Dq staff . 201Note: in this example, the first 202.Fl c 203option applies to 204.Nm 205while the second is an argument to the shell being invoked. 206.It Li "su -l foo" 207Simulate a login for user foo. 208.It Li "su - foo" 209Same as above. 210.It Li "su - " 211Simulate a login for root. 212.El 213.Sh HISTORY 214A 215.Nm 216command appeared in 217.At v1 . 218