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 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. 151.Pp 152By default (unless the prompt is reset by a startup file) the super-user 153prompt is set to 154.Dq Sy \&# 155to remind one of its awesome power. 156.Sh FILES 157.Bl -tag -width /etc/pam.conf -compact 158.It Pa /etc/pam.conf 159.Nm 160is configured with PAM support; it uses 161.Pa /etc/pam.conf 162entries with service name 163.Dq su 164.El 165.Sh SEE ALSO 166.Xr csh 1 , 167.Xr sh 1 , 168.Xr group 5 , 169.Xr login.conf 5 , 170.Xr passwd 5 , 171.Xr environ 7 , 172.Xr pam 8 173.Sh ENVIRONMENT 174Environment variables used by 175.Nm : 176.Bl -tag -width HOME 177.It Ev HOME 178Default home directory of real user ID unless modified as 179specified above. 180.It Ev PATH 181Default search path of real user ID unless modified as specified above. 182.It Ev TERM 183Provides terminal type which may be retained for the substituted 184user ID. 185.It Ev USER 186The user ID is always the effective ID (the target user ID) after an 187.Nm 188unless the user ID is 0 (root). 189.El 190.Sh EXAMPLES 191.Bl -tag -width 5n -compact 192.It Li "su man -c catman" 193Runs the command 194.Li catman 195as user 196.Li man . 197You will be asked for man's password unless your real UID is 0. 198.It Li "su man -c 'catman /usr/share/man /usr/local/man /usr/X11R6/man'" 199Same as above, but the target command consists of more than a 200single word and hence is quoted for use with the 201.Fl c 202option being passed to the shell. (Most shells expect the argument to 203.Fl c 204to be a single word). 205.It Li "su -c staff man -c 'catman /usr/share/man /usr/local/man /usr/X11R6/man'" 206Same as above, but the target command is run with the resource limits of 207the login class 208.Dq staff . 209Note: in this example, the first 210.Fl c 211option applies to 212.Nm 213while the second is an argument to the shell being invoked. 214.It Li "su -l foo" 215Simulate a login for user foo. 216.It Li "su - foo" 217Same as above. 218.It Li "su - " 219Simulate a login for root. 220.El 221.Sh HISTORY 222A 223.Nm 224command appeared in 225.At v1 . 226