'\" te
.\" Copyright 1989 AT&T
.\" Copyright (C) 2004, Sun Microsystems, Inc.
.\" All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SU 1 "Jan 16, 2019"
.SH NAME
su \- become superuser or another user
.SH SYNOPSIS
.LP
.nf
\fBsu\fR [\fB-\fR] [\fIusername\fR [arg...]]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsu\fR command allows one to become another user without logging off or
to assume a role. The default user \fIname\fR is \fBroot\fR (superuser).
.sp
.LP
To use \fBsu\fR, the appropriate password must be supplied (unless the invoker
is already \fBroot\fR). If the password is correct, \fBsu\fR creates a new
shell process that has the real and effective user \fBID,\fR group \fBIDs,\fR
and supplementary group list set to those of the specified \fIusername\fR.
Additionally, the new shell's project ID is set to the default project ID of
the specified user. See \fBgetdefaultproj\fR(3PROJECT),
\fBsetproject\fR(3PROJECT). The new shell will be the shell specified in the
shell field of \fIusername\fR's password file entry (see \fBpasswd\fR(4)). If
no shell is specified, \fB/usr/bin/sh\fR is used (see \fBsh\fR(1)). If
superuser privilege is requested and the shell for the superuser cannot be
invoked using \fBexec\fR(2), \fB/bin/sh\fR is used as a fallback. To return to
normal user \fBID\fR privileges, type an \fBEOF\fR character (CTRL-D) to exit
the new shell.
.sp
.LP
Any additional arguments given on the command line are passed to the new shell.
When using programs such as \fBsh\fR, an \fIarg\fR of the form \fB-c\fR\fI
string\fR executes \fIstring\fR using the shell and an \fIarg\fR of \fB-r\fR
gives the user a restricted shell.
.sp
.LP
To create a login environment, the command \fB"su -"\fR does the following:
.RS +4
.TP
.ie t \(bu
.el o
In addition to what is already propagated, the \fBLC*\fR and \fBLANG\fR
environment variables from the specified user's environment are also
propagated.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Propagate \fBTZ\fR from the user's environment. If \fBTZ\fR is not found in the
user's environment, \fBsu\fR uses the \fBTZ\fR value from the \fBTIMEZONE\fR
parameter found in \fB/etc/default/login\fR.
.RE
.sp
.LP
If the first argument to \fBsu\fR is a dash (-), the environment will be
changed to what would be expected if the user actually logged in as the
specified user. Otherwise, the environment is passed along, with the exception
of \fB$\fR\fBPATH\fR\fB, \fR which is controlled by \fBPATH\fR and
\fBSU\fR\fBPATH\fR in \fB/etc/default/su\fR.
.sp
.LP
All attempts to become another user using \fBsu\fR are logged in the log file
\fB/var/log/sulog\fR (see \fBsulog\fR(4)).
.SH SECURITY
.sp
.LP
\fBsu\fR uses \fBpam\fR(3PAM) with the service name \fBsu\fR for
authentication, account management, and credential establishment.
.SH EXAMPLES
.LP
\fBExample 1 \fRBecoming User \fBbin\fR While Retaining Your Previously
Exported Environment
.sp
.LP
To become user \fBbin\fR while retaining your previously exported environment,
execute:

.sp
.in +2
.nf
example% \fBsu bin\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRBecoming User \fBbin\fR and Changing to \fBbin\fR's Login
Environment
.sp
.LP
To become user \fBbin\fR but change the environment to what would be expected
if \fBbin\fR had originally logged in, execute:

.sp
.in +2
.nf
example% \fBsu - bin\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRExecuting command with user \fBbin\fR's Environment and
Permissions
.sp
.LP
To execute command with the temporary environment and permissions of user
\fBbin\fR, type:

.sp
.in +2
.nf
example% \fBsu - bin -c "\fIcommand args\fR"\fR
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
Variables with \fBLD_\fR prefix are removed for security reasons. Thus, \fBsu
bin\fR will not retain previously exported variables with \fBLD_\fR prefix
while becoming user \fBbin\fR.
.sp
.LP
If any of the \fBLC_*\fR variables ( \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR,
\fBLC_TIME\fR, \fBLC_COLLATE\fR, \fBLC_NUMERIC\fR, and \fBLC_MONETARY\fR) (see
\fBenviron\fR(5)) are not set in the environment, the operational behavior of
\fBsu\fR for each corresponding locale category is determined by the value of
the \fBLANG\fR environment variable. If \fBLC_ALL\fR is set, its contents are
used to override both the \fBLANG\fR and the other \fBLC_*\fR variables. If
none of the above variables are set in the environment, the "C" (U.S. style)
locale determines how \fBsu\fR behaves.
.sp
.ne 2
.na
\fB\fBLC_CTYPE\fR\fR
.ad
.RS 15n
Determines how \fBsu\fR handles characters. When \fBLC_CTYPE\fR is set to a
valid value, \fBsu\fR can display and handle text and filenames containing
valid characters for that locale. \fBsu\fR can display and handle Extended Unix
Code (\fBEUC\fR) characters where any individual character can be \fB1\fR,
\fB2\fR, or \fB3\fR bytes wide. \fBsu\fR can also handle \fBEUC\fR characters
of \fB1\fR, \fB2\fR, or more column widths. In the "C" locale, only characters
from ISO 8859-1 are valid.
.RE

.sp
.ne 2
.na
\fB\fBLC_MESSAGES\fR\fR
.ad
.RS 15n
Determines how diagnostic and informative messages are presented. This includes
the language and style of the messages, and the correct form of affirmative and
negative responses. In the "C" locale, the messages are presented in the
default form found in the program itself (in most cases, U.S. English).
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB$\fR\fBHOME\fR\fB/.profile\fR\fR
.ad
.RS 22n
user's login commands for \fBsh\fR and \fBksh\fR
.RE

.sp
.ne 2
.na
\fB\fB/etc/passwd\fR\fR
.ad
.RS 22n
system's password file
.RE

.sp
.ne 2
.na
\fB\fB/etc/profile\fR\fR
.ad
.RS 22n
system-wide \fBsh\fR and \fBksh\fR login commands
.RE

.sp
.ne 2
.na
\fB\fB/etc/default/login\fR\fR
.ad
.RS 22n
the default parameters in this file are:
.sp
.ne 2
.na
\fB\fBPATH\fR\fR
.ad
.RS 11n
Default path.
.RE

.sp
.ne 2
.na
\fB\fBSUPATH\fR\fR
.ad
.RS 11n
Default path for a user invoking \fBsu\fR to \fBroot\fR.
.RE

.sp
.ne 2
.na
\fB\fBSLEEPTIME\fR\fR
.ad
.RS 11n
Time to sleep after an unsuccessful login attempt in seconds.
.RE

.SH SEE ALSO
.sp
.LP
\fBcsh\fR(1), \fBenv\fR(1), \fBksh\fR(1), \fBlogin\fR(1), \fBroles\fR(1),
\fBsh\fR(1), \fBsyslogd\fR(8), \fBexec\fR(2), \fBgetdefaultproj\fR(3PROJECT),
\fBsetproject\fR(3PROJECT), \fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM),
\fBpam_acct_mgmt\fR(3PAM), \fBpam_setcred\fR(3PAM), \fBpam.conf\fR(4),
\fBpasswd\fR(4), \fBprofile\fR(4), \fBsulog\fR(4), \fBsyslog\fR(3C),
\fBattributes\fR(5), \fBenviron\fR(5)