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 October 3, 2004 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 flms 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 s 126Set the MAC label to the user's default label as part of the user 127credential setup. 128Setting the MAC label may fail if the MAC label of the invoking process 129is not sufficient to transition to the user's default MAC label. 130If the label cannot be set, 131.Nm 132will fail. 133.It Fl c Ar class 134Use the settings of the specified login class. 135Only allowed for the super-user. 136.El 137.Pp 138The 139.Fl l 140(or 141.Fl ) 142and 143.Fl m 144options are mutually exclusive; the last one specified 145overrides any previous ones. 146.Pp 147If the optional 148.Ar args 149are provided on the command line, they are passed to the login shell of 150the target login. 151Note that all command line arguments before the target login name are 152processed by 153.Nm 154itself, everything after the target login name gets passed to the login 155shell. 156.Pp 157By default (unless the prompt is reset by a startup file) the super-user 158prompt is set to 159.Dq Sy \&# 160to remind one of its awesome power. 161.Sh ENVIRONMENT 162Environment variables used by 163.Nm : 164.Bl -tag -width HOME 165.It Ev HOME 166Default home directory of real user ID unless modified as 167specified above. 168.It Ev PATH 169Default search path of real user ID unless modified as specified above. 170.It Ev TERM 171Provides terminal type which may be retained for the substituted 172user ID. 173.It Ev USER 174The user ID is always the effective ID (the target user ID) after an 175.Nm 176unless the user ID is 0 (root). 177.El 178.Sh FILES 179.Bl -tag -width ".Pa /etc/pam.d/su" -compact 180.It Pa /etc/pam.d/su 181PAM configuration for 182.Nm . 183.El 184.Sh EXAMPLES 185.Bl -tag -width 5n -compact 186.It Li "su man -c catman" 187Runs the command 188.Li catman 189as user 190.Li man . 191You will be asked for man's password unless your real UID is 0. 192.It Li "su man -c 'catman /usr/share/man /usr/local/man /usr/X11R6/man'" 193Same as above, but the target command consists of more than a 194single word and hence is quoted for use with the 195.Fl c 196option being passed to the shell. 197(Most shells expect the argument to 198.Fl c 199to be a single word). 200.It Li "su -c staff man -c 'catman /usr/share/man /usr/local/man /usr/X11R6/man'" 201Same as above, but the target command is run with the resource limits of 202the login class 203.Dq staff . 204Note: in this example, the first 205.Fl c 206option applies to 207.Nm 208while the second is an argument to the shell being invoked. 209.It Li "su -l foo" 210Simulate a login for user foo. 211.It Li "su - foo" 212Same as above. 213.It Li "su -" 214Simulate a login for root. 215.El 216.Sh SEE ALSO 217.Xr csh 1 , 218.Xr sh 1 , 219.Xr group 5 , 220.Xr login.conf 5 , 221.Xr passwd 5 , 222.Xr environ 7 , 223.Xr pam 8 224.Sh HISTORY 225A 226.Nm 227command appeared in 228.At v1 . 229