bin/su/su.1

   1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (C) 2004, Sun Microsystems, Inc.
   4 .\" All Rights Reserved.
   5 .\" 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.
   6 .\" 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.
   7 .\" 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]
   8 .TH SU 1 "Jan 16, 2019"
   9 .SH NAME
  10 su \- become superuser or another user
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBsu\fR [\fB-\fR] [\fIusername\fR [arg...]]
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 The \fBsu\fR command allows one to become another user without logging off or
  21 to assume a role. The default user \fIname\fR is \fBroot\fR (superuser).
  22 .sp
  23 .LP
  24 To use \fBsu\fR, the appropriate password must be supplied (unless the invoker
  25 is already \fBroot\fR). If the password is correct, \fBsu\fR creates a new
  26 shell process that has the real and effective user \fBID,\fR group \fBIDs,\fR
  27 and supplementary group list set to those of the specified \fIusername\fR.
  28 Additionally, the new shell's project ID is set to the default project ID of
  29 the specified user. See \fBgetdefaultproj\fR(3PROJECT),
  30 \fBsetproject\fR(3PROJECT). The new shell will be the shell specified in the
  31 shell field of \fIusername\fR's password file entry (see \fBpasswd\fR(4)). If
  32 no shell is specified, \fB/usr/bin/sh\fR is used (see \fBsh\fR(1)). If
  33 superuser privilege is requested and the shell for the superuser cannot be
  34 invoked using \fBexec\fR(2), \fB/bin/sh\fR is used as a fallback. To return to
  35 normal user \fBID\fR privileges, type an \fBEOF\fR character (CTRL-D) to exit
  36 the new shell.
  37 .sp
  38 .LP
  39 Any additional arguments given on the command line are passed to the new shell.
  40 When using programs such as \fBsh\fR, an \fIarg\fR of the form \fB-c\fR\fI
  41 string\fR executes \fIstring\fR using the shell and an \fIarg\fR of \fB-r\fR
  42 gives the user a restricted shell.
  43 .sp
  44 .LP
  45 To create a login environment, the command \fB"su -"\fR does the following:
  46 .RS +4
  47 .TP
  48 .ie t \(bu
  49 .el o
  50 In addition to what is already propagated, the \fBLC*\fR and \fBLANG\fR
  51 environment variables from the specified user's environment are also
  52 propagated.
  53 .RE
  54 .RS +4
  55 .TP
  56 .ie t \(bu
  57 .el o
  58 Propagate \fBTZ\fR from the user's environment. If \fBTZ\fR is not found in the
  59 user's environment, \fBsu\fR uses the \fBTZ\fR value from the \fBTIMEZONE\fR
  60 parameter found in \fB/etc/default/login\fR.
  61 .RE
  62 .sp
  63 .LP
  64 If the first argument to \fBsu\fR is a dash (-), the environment will be
  65 changed to what would be expected if the user actually logged in as the
  66 specified user. Otherwise, the environment is passed along, with the exception
  67 of \fB$\fR\fBPATH\fR\fB, \fR which is controlled by \fBPATH\fR and
  68 \fBSU\fR\fBPATH\fR in \fB/etc/default/su\fR.
  69 .sp
  70 .LP
  71 All attempts to become another user using \fBsu\fR are logged in the log file
  72 \fB/var/adm/sulog\fR (see \fBsulog\fR(4)).
  73 .SH SECURITY
  74 .sp
  75 .LP
  76 \fBsu\fR uses \fBpam\fR(3PAM) with the service name \fBsu\fR for
  77 authentication, account management, and credential establishment.
  78 .SH EXAMPLES
  79 .LP
  80 \fBExample 1 \fRBecoming User \fBbin\fR While Retaining Your Previously
  81 Exported Environment
  82 .sp
  83 .LP
  84 To become user \fBbin\fR while retaining your previously exported environment,
  85 execute:
  86
  87 .sp
  88 .in +2
  89 .nf
  90 example% \fBsu bin\fR
  91 .fi
  92 .in -2
  93 .sp
  94
  95 .LP
  96 \fBExample 2 \fRBecoming User \fBbin\fR and Changing to \fBbin\fR's Login
  97 Environment
  98 .sp
  99 .LP
 100 To become user \fBbin\fR but change the environment to what would be expected
 101 if \fBbin\fR had originally logged in, execute:
 102
 103 .sp
 104 .in +2
 105 .nf
 106 example% \fBsu - bin\fR
 107 .fi
 108 .in -2
 109 .sp
 110
 111 .LP
 112 \fBExample 3 \fRExecuting command with user \fBbin\fR's Environment and
 113 Permissions
 114 .sp
 115 .LP
 116 To execute command with the temporary environment and permissions of user
 117 \fBbin\fR, type:
 118
 119 .sp
 120 .in +2
 121 .nf
 122 example% \fBsu - bin -c "\fIcommand args\fR"\fR
 123 .fi
 124 .in -2
 125 .sp
 126
 127 .SH ENVIRONMENT VARIABLES
 128 .sp
 129 .LP
 130 Variables with \fBLD_\fR prefix are removed for security reasons. Thus, \fBsu
 131 bin\fR will not retain previously exported variables with \fBLD_\fR prefix
 132 while becoming user \fBbin\fR.
 133 .sp
 134 .LP
 135 If any of the \fBLC_*\fR variables ( \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR,
 136 \fBLC_TIME\fR, \fBLC_COLLATE\fR, \fBLC_NUMERIC\fR, and \fBLC_MONETARY\fR) (see
 137 \fBenviron\fR(5)) are not set in the environment, the operational behavior of
 138 \fBsu\fR for each corresponding locale category is determined by the value of
 139 the \fBLANG\fR environment variable. If \fBLC_ALL\fR is set, its contents are
 140 used to override both the \fBLANG\fR and the other \fBLC_*\fR variables. If
 141 none of the above variables are set in the environment, the "C" (U.S. style)
 142 locale determines how \fBsu\fR behaves.
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBLC_CTYPE\fR\fR
 147 .ad
 148 .RS 15n
 149 Determines how \fBsu\fR handles characters. When \fBLC_CTYPE\fR is set to a
 150 valid value, \fBsu\fR can display and handle text and filenames containing
 151 valid characters for that locale. \fBsu\fR can display and handle Extended Unix
 152 Code (\fBEUC\fR) characters where any individual character can be \fB1\fR,
 153 \fB2\fR, or \fB3\fR bytes wide. \fBsu\fR can also handle \fBEUC\fR characters
 154 of \fB1\fR, \fB2\fR, or more column widths. In the "C" locale, only characters
 155 from ISO 8859-1 are valid.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBLC_MESSAGES\fR\fR
 162 .ad
 163 .RS 15n
 164 Determines how diagnostic and informative messages are presented. This includes
 165 the language and style of the messages, and the correct form of affirmative and
 166 negative responses. In the "C" locale, the messages are presented in the
 167 default form found in the program itself (in most cases, U.S. English).
 168 .RE
 169
 170 .SH FILES
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fB$\fR\fBHOME\fR\fB/.profile\fR\fR
 175 .ad
 176 .RS 22n
 177 user's login commands for \fBsh\fR and \fBksh\fR
 178 .RE
 179
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fB/etc/passwd\fR\fR
 184 .ad
 185 .RS 22n
 186 system's password file
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fB/etc/profile\fR\fR
 193 .ad
 194 .RS 22n
 195 system-wide \fBsh\fR and \fBksh\fR login commands
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fB/etc/default/login\fR\fR
 202 .ad
 203 .RS 22n
 204 the default parameters in this file are:
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBPATH\fR\fR
 209 .ad
 210 .RS 11n
 211 Default path.
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBSUPATH\fR\fR
 218 .ad
 219 .RS 11n
 220 Default path for a user invoking \fBsu\fR to \fBroot\fR.
 221 .RE
 222
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBSLEEPTIME\fR\fR
 227 .ad
 228 .RS 11n
 229 Time to sleep after an unsuccessful login attempt in seconds.
 230 .RE
 231
 232 .SH SEE ALSO
 233 .sp
 234 .LP
 235 \fBcsh\fR(1), \fBenv\fR(1), \fBksh\fR(1), \fBlogin\fR(1), \fBroles\fR(1),
 236 \fBsh\fR(1), \fBsyslogd\fR(8), \fBexec\fR(2), \fBgetdefaultproj\fR(3PROJECT),
 237 \fBsetproject\fR(3PROJECT), \fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM),
 238 \fBpam_acct_mgmt\fR(3PAM), \fBpam_setcred\fR(3PAM), \fBpam.conf\fR(4),
 239 \fBpasswd\fR(4), \fBprofile\fR(4), \fBsulog\fR(4), \fBsyslog\fR(3C),
 240 \fBattributes\fR(5), \fBenviron\fR(5)