share/man/man8/su.8

   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 8 "Feb 26, 2004"
   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 .RS +4
  63 .TP
  64 .ie t \(bu
  65 .el o
  66 Set \fBMAIL\fR to \fB/var/mail/\fInew_user\fR\fR.
  67 .RE
  68 .sp
  69 .LP
  70 If the first argument to \fBsu\fR is a dash (-), the environment will be
  71 changed to what would be expected if the user actually logged in as the
  72 specified user. Otherwise, the environment is passed along, with the exception
  73 of \fB$\fR\fBPATH\fR\fB, \fR which is controlled by \fBPATH\fR and
  74 \fBSU\fR\fBPATH\fR in \fB/etc/default/su\fR.
  75 .sp
  76 .LP
  77 All attempts to become another user using \fBsu\fR are logged in the log file
  78 \fB/var/adm/sulog\fR (see \fBsulog\fR(4)).
  79 .SH SECURITY
  80 .sp
  81 .LP
  82 \fBsu\fR uses \fBpam\fR(3PAM) with the service name \fBsu\fR for
  83 authentication, account management, and credential establishment.
  84 .SH EXAMPLES
  85 .LP
  86 \fBExample 1 \fRBecoming User \fBbin\fR While Retaining Your Previously
  87 Exported Environment
  88 .sp
  89 .LP
  90 To become user \fBbin\fR while retaining your previously exported environment,
  91 execute:
  92
  93 .sp
  94 .in +2
  95 .nf
  96 example% \fBsu bin\fR
  97 .fi
  98 .in -2
  99 .sp
 100
 101 .LP
 102 \fBExample 2 \fRBecoming User \fBbin\fR and Changing to \fBbin\fR's Login
 103 Environment
 104 .sp
 105 .LP
 106 To become user \fBbin\fR but change the environment to what would be expected
 107 if \fBbin\fR had originally logged in, execute:
 108
 109 .sp
 110 .in +2
 111 .nf
 112 example% \fBsu - bin\fR
 113 .fi
 114 .in -2
 115 .sp
 116
 117 .LP
 118 \fBExample 3 \fRExecuting command with user \fBbin\fR's Environment and
 119 Permissions
 120 .sp
 121 .LP
 122 To execute command with the temporary environment and permissions of user
 123 \fBbin\fR, type:
 124
 125 .sp
 126 .in +2
 127 .nf
 128 example% \fBsu - bin -c "\fIcommand args\fR"\fR
 129 .fi
 130 .in -2
 131 .sp
 132
 133 .SH ENVIRONMENT VARIABLES
 134 .sp
 135 .LP
 136 Variables with \fBLD_\fR prefix are removed for security reasons. Thus, \fBsu
 137 bin\fR will not retain previously exported variables with \fBLD_\fR prefix
 138 while becoming user \fBbin\fR.
 139 .sp
 140 .LP
 141 If any of the \fBLC_*\fR variables ( \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR,
 142 \fBLC_TIME\fR, \fBLC_COLLATE\fR, \fBLC_NUMERIC\fR, and \fBLC_MONETARY\fR) (see
 143 \fBenviron\fR(5)) are not set in the environment, the operational behavior of
 144 \fBsu\fR for each corresponding locale category is determined by the value of
 145 the \fBLANG\fR environment variable. If \fBLC_ALL\fR is set, its contents are
 146 used to override both the \fBLANG\fR and the other \fBLC_*\fR variables. If
 147 none of the above variables are set in the environment, the "C" (U.S. style)
 148 locale determines how \fBsu\fR behaves.
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBLC_CTYPE\fR\fR
 153 .ad
 154 .RS 15n
 155 Determines how \fBsu\fR handles characters. When \fBLC_CTYPE\fR is set to a
 156 valid value, \fBsu\fR can display and handle text and filenames containing
 157 valid characters for that locale. \fBsu\fR can display and handle Extended Unix
 158 Code (\fBEUC\fR) characters where any individual character can be \fB1\fR,
 159 \fB2\fR, or \fB3\fR bytes wide. \fBsu\fR can also handle \fBEUC\fR characters
 160 of \fB1\fR, \fB2\fR, or more column widths. In the "C" locale, only characters
 161 from ISO 8859-1 are valid.
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBLC_MESSAGES\fR\fR
 168 .ad
 169 .RS 15n
 170 Determines how diagnostic and informative messages are presented. This includes
 171 the language and style of the messages, and the correct form of affirmative and
 172 negative responses. In the "C" locale, the messages are presented in the
 173 default form found in the program itself (in most cases, U.S. English).
 174 .RE
 175
 176 .SH FILES
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fB$\fR\fBHOME\fR\fB/.profile\fR\fR
 181 .ad
 182 .RS 22n
 183 user's login commands for \fBsh\fR and \fBksh\fR
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fB/etc/passwd\fR\fR
 190 .ad
 191 .RS 22n
 192 system's password file
 193 .RE
 194
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fB/etc/profile\fR\fR
 199 .ad
 200 .RS 22n
 201 system-wide \fBsh\fR and \fBksh\fR login commands
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fB/var/adm/sulog\fR\fR
 208 .ad
 209 .RS 22n
 210 log file
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fB/etc/default/su\fR\fR
 217 .ad
 218 .RS 22n
 219 the default parameters in this file are:
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fBSULOG\fR\fR
 224 .ad
 225 .RS 11n
 226 If defined, all attempts to \fBsu\fR to another user are logged in the
 227 indicated file.
 228 .RE
 229
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBCONSOLE\fR\fR
 234 .ad
 235 .RS 11n
 236 If defined, all attempts to \fBsu\fR to \fBroot\fR are logged on the console.
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fBPATH\fR\fR
 243 .ad
 244 .RS 11n
 245 Default path. (\fB/usr/bin:\fR)
 246 .RE
 247
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fBSU\fR\fBPATH\fR\fR
 252 .ad
 253 .RS 11n
 254 Default path for a user invoking \fBsu\fR to \fBroot\fR.
 255 (\fB/usr/sbin:/usr/bin\fR)
 256 .RE
 257
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fBSYSLOG\fR\fR
 262 .ad
 263 .RS 11n
 264 Determines whether the \fBsyslog\fR(3C) \fBLOG_AUTH\fR facility should be used
 265 to log all \fBsu\fR attempts. \fBLOG_NOTICE\fR messages are generated for
 266 \fBsu\fR's to root, \fBLOG_INFO\fR messages are generated for \fBsu\fR's to
 267 other users, and \fBLOG_CRIT\fR messages are generated for failed \fBsu\fR
 268 attempts.
 269 .RE
 270
 271 .RE
 272
 273 .sp
 274 .ne 2
 275 .na
 276 \fB\fB/etc/default/login\fR\fR
 277 .ad
 278 .RS 22n
 279 the default parameters in this file are:
 280 .sp
 281 .ne 2
 282 .na
 283 \fB\fBTIMEZONE\fR\fR
 284 .ad
 285 .RS 12n
 286 Sets the TZ environment variable of the shell.
 287 .RE
 288
 289 .RE
 290
 291 .SH SEE ALSO
 292 .sp
 293 .LP
 294 \fBcsh\fR(1), \fBenv\fR(1), \fBksh\fR(1), \fBlogin\fR(1), \fBroles\fR(1),
 295 \fBsh\fR(1), \fBsyslogd\fR(8), \fBexec\fR(2), \fBgetdefaultproj\fR(3PROJECT),
 296 \fBsetproject\fR(3PROJECT), \fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM),
 297 \fBpam_acct_mgmt\fR(3PAM), \fBpam_setcred\fR(3PAM), \fBpam.conf\fR(4),
 298 \fBpasswd\fR(4), \fBprofile\fR(4), \fBsulog\fR(4), \fBsyslog\fR(3C),
 299 \fBattributes\fR(5), \fBenviron\fR(5)