'\" te
.\" Copyright 1989 AT&T
.\" Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved.
.TH su 1M "26 Apr 2011" "SunOS 5.11" "System Administration Commands"
.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 \fBgetprojent\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/sbin/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 \fIstring\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
.RS +4
.TP
.ie t \(bu
.el o
Set \fBMAIL\fR to \fB/var/mail/\fInew_user\fR\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/adm/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
.mk
.na
\fB\fBLC_CTYPE\fR\fR
.ad
.RS 15n
.rt  
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
.mk
.na
\fB\fBLC_MESSAGES\fR\fR
.ad
.RS 15n
.rt  
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
.mk
.na
\fB\fB$\fR\fBHOME\fR\fB/.profile\fR\fR
.ad
.sp .6
.RS 4n
user's login commands for \fBsh\fR and \fBksh\fR
.RE

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

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

.sp
.ne 2
.mk
.na
\fB\fB/var/adm/sulog\fR\fR
.ad
.sp .6
.RS 4n
log file
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/default/su\fR\fR
.ad
.sp .6
.RS 4n
the default parameters in this file are: 
.sp
.ne 2
.mk
.na
\fB\fBSULOG\fR\fR
.ad
.RS 11n
.rt  
If defined, all attempts to \fBsu\fR to another user are logged in the indicated file.
.RE

.sp
.ne 2
.mk
.na
\fB\fBCONSOLE\fR\fR
.ad
.RS 11n
.rt  
If defined, all attempts to \fBsu\fR to \fBroot\fR are logged on the console.
.RE

.sp
.ne 2
.mk
.na
\fB\fBPATH\fR\fR
.ad
.RS 11n
.rt  
Default path. (\fB/usr/bin:\fR)
.RE

.sp
.ne 2
.mk
.na
\fB\fBSU\fR\fBPATH\fR\fR
.ad
.RS 11n
.rt  
Default path for a user invoking \fBsu\fR to \fBroot\fR. (\fB/usr/sbin:/usr/bin\fR)
.RE

.sp
.ne 2
.mk
.na
\fB\fBSYSLOG\fR\fR
.ad
.RS 11n
.rt  
Determines whether the \fBsyslog\fR(3C) \fBLOG_AUTH\fR facility should be used to log all \fBsu\fR attempts. \fBLOG_NOTICE\fR messages are generated for \fBsu\fR's to root, \fBLOG_INFO\fR messages are generated for \fBsu\fR's to other users, and \fBLOG_CRIT\fR messages are generated for failed \fBsu\fR attempts.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/default/login\fR\fR
.ad
.sp .6
.RS 4n
the default parameters in this file are:
.sp
.ne 2
.mk
.na
\fB\fBSLEEPTIME\fR\fR
.ad
.RS 13n
.rt  
If present, sets the number of seconds to wait before login failure is printed to the screen and another login attempt is allowed. Default is \fB4\fR seconds. Minimum is \fB0\fR seconds. Maximum is \fB5\fR seconds.
.sp
Both \fBsu\fR and \fBlogin\fR(1) are affected by the value of \fBSLEEPTIME\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIMEZONE\fR\fR
.ad
.RS 13n
.rt  
Sets the TZ environment variable of the shell.
.RE

.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/core-os
.TE

.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(1M), \fBexec\fR(2), \fBgetprojent\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)