login-utils/su.1

   1 .TH SU 1 "July 2014" "util-linux" "User Commands"
   2 .SH NAME
   3 su \- run a command with substitute user and group ID
   4 .SH SYNOPSIS
   5 .BR su " [options] [" \- ]
   6 .RI [ user " [" argument ...]]
   7 .SH DESCRIPTION
   8 .B su
   9 allows to run commands with a substitute user and group ID.
  10 .PP
  11 When called with no
  12 .I user
  13 specified,
  14 .B su
  15 defaults to running an interactive shell as
  16 .IR root .
  17 When
  18 .I user
  19 is specified, additional
  20 .IR argument s
  21 can be supplied, in which case they are passed to the shell.
  22 .PP
  23 For backward compatibility,
  24 .B su
  25 defaults to not change the current directory and to only set the
  26 environment variables
  27 .B HOME
  28 and
  29 .B SHELL
  30 (plus
  31 .B USER
  32 and
  33 .B LOGNAME
  34 if the target
  35 .I user
  36 is not root).  It is recommended to always use the
  37 .B \-\-login
  38 option (instead of its shortcut
  39 .BR \- )
  40 to avoid side effects caused by mixing environments.
  41 .PP
  42 This version of
  43 .B su
  44 uses PAM for authentication, account and session management.  Some
  45 configuration options found in other
  46 .B su
  47 implementations, such as support for a wheel group, have to be
  48 configured via PAM.
  49 .PP
  50 .B su
  51 is mostly designed for unprivileged users, the recommended solution for
  52 privileged users (e.g., scripts executed by root) is to use
  53 non-set-user-ID command
  54 .BR runuser (1)
  55 that does not require authentication and provide separate PAM configuration. If
  56 the PAM session is not required at all then the recommend solution is to use
  57 command
  58 .BR setpriv (1).
  59 .PP
  60 Note that
  61 .B su
  62 in all cases use PAM (pam_getenvlist()) to do final environment modification.  The command line options
  63 like \fB\-\-login\fR or \fB\-\-preserve\-environment\fR affect environment before it's modified by PAM.
  64
  65 .SH OPTIONS
  66 .TP
  67 .BR \-c , " \-\-command" = \fIcommand
  68 Pass
  69 .I command
  70 to the shell with the
  71 .B \-c
  72 option.
  73 .TP
  74 .BR \-f , " \-\-fast"
  75 Pass
  76 .B \-f
  77 to the shell, which may or may not be useful, depending on the shell.
  78 .TP
  79 .BR \-g , " \-\-group" = \fIgroup
  80 Specify the primary group.  This option is available to the root user only.
  81 .TP
  82 .BR \-G , " \-\-supp\-group" = \fIgroup
  83 Specify a supplemental group.  This option is available to the root user only.  The first specified
  84 supplementary group is also used as a primary group if the option \fB\-\-group\fR is unspecified.
  85 .TP
  86 .BR \- , " \-l" , " \-\-login"
  87 Start the shell as a login shell with an environment similar to a real
  88 login:
  89 .RS 10
  90 .TP
  91 o
  92 clears all the environment variables except
  93 .B TERM
  94 and variables specified by \fB\-\-whitelist\-environment\fR
  95 .TP
  96 o
  97 initializes the environment variables
  98 .BR HOME ,
  99 .BR SHELL ,
 100 .BR USER ,
 101 .BR LOGNAME ", and"
 102 .B PATH
 103 .TP
 104 o
 105 changes to the target user's home directory
 106 .TP
 107 o
 108 sets argv[0] of the shell to
 109 .RB ' \- '
 110 in order to make the shell a login shell
 111 .RE
 112 .TP
 113 .BR \-m , " \-p" , " \-\-preserve\-environment"
 114 Preserve the entire environment, i.e., it does not set
 115 .BR HOME ,
 116 .BR SHELL ,
 117 .B USER
 118 nor
 119 .BR LOGNAME .
 120 This option is ignored if the option \fB\-\-login\fR is specified.
 121 .TP
 122 .BR \-P , " \-\-pty"
 123 Create pseudo-terminal for the session. The independent terminal provides
 124 better security as user does not share terminal with the original
 125 session.  This allow to avoid TIOCSTI ioctl terminal injection and another
 126 security attacks against terminal file descriptors. The all session is also
 127 possible to move to background (e.g., "su \-\-pty \- username \-c
 128 application &"). If the pseudo-terminal is enabled then su command works
 129 as a proxy between the sessions (copy stdin and stdout).
 130 .sp
 131 This feature is mostly designed for interactive sessions. If the standard input
 132 is not a terminal, but for example pipe (e.g., echo "date" | su --pty) than ECHO
 133 flag for the pseudo-terminal is disabled to avoid messy output.
 134 .TP
 135 .BR \-s , " \-\-shell" = \fIshell
 136 Run the specified \fIshell\fR instead of the default.  The shell to run is
 137 selected according to the following rules, in order:
 138 .RS 10
 139 .TP
 140 o
 141 the shell specified with
 142 .B \-\-shell
 143 .TP
 144 o
 145 the shell specified in the environment variable
 146 .BR SHELL ,
 147 if the
 148 .B \-\-preserve\-environment
 149 option is used
 150 .TP
 151 o
 152 the shell listed in the passwd entry of the target user
 153 .TP
 154 o
 155 /bin/sh
 156 .RE
 157 .IP
 158 If the target user has a restricted shell (i.e., not listed in
 159 /etc/shells), the
 160 .B \-\-shell
 161 option and the
 162 .B SHELL
 163 environment variables are ignored unless the calling user is root.
 164 .TP
 165 .BI \-\-session\-command= command
 166 Same as
 167 .B \-c
 168 but do not create a new session.  (Discouraged.)
 169 .TP
 170 .BR \-w , " \-\-whitelist\-environment" = \fIlist
 171 Don't reset environment variables specified in comma separated \fIlist\fR when clears
 172 environment for \fB\-\-login\fR. The whitelist is ignored for the environment variables
 173 .BR HOME ,
 174 .BR SHELL ,
 175 .BR USER ,
 176 .BR LOGNAME ", and"
 177 .BR PATH "."
 178 .TP
 179 .BR \-V , " \-\-version"
 180 Display version information and exit.
 181 .TP
 182 .BR \-h , " \-\-help"
 183 Display help text and exit.
 184 .SH SIGNALS
 185 Upon receiving either
 186 .BR SIGINT ,
 187 .B SIGQUIT
 188 or
 189 .BR SIGTERM ,
 190 .B su
 191 terminates its child and afterwards terminates itself with the received signal.
 192 The child is terminated by SIGTERM, after unsuccessful attempt and 2 seconds of
 193 delay the child is killed by SIGKILL.
 194 .SH CONFIG FILES
 195 .B su
 196 reads the
 197 .I /etc/default/su
 198 and
 199 .I /etc/login.defs
 200 configuration files.  The following configuration items are relevant
 201 for
 202 .BR su (1):
 203 .PP
 204 .B FAIL_DELAY
 205 (number)
 206 .RS 4
 207 Delay in seconds in case of an authentication failure. The number must be
 208 a non-negative integer.
 209 .RE
 210 .PP
 211 .B ENV_PATH
 212 (string)
 213 .RS 4
 214 Defines the PATH environment variable for a regular user.  The
 215 default value is
 216 .IR /usr/local/bin:\:/bin:\:/usr/bin .
 217 .RE
 218 .PP
 219 .B ENV_ROOTPATH
 220 (string)
 221 .br
 222 .B ENV_SUPATH
 223 (string)
 224 .RS 4
 225 Defines the PATH environment variable for root.  ENV_SUPATH takes precedence.  The default value is
 226 .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin .
 227 .RE
 228 .PP
 229 .B ALWAYS_SET_PATH
 230 (boolean)
 231 .RS 4
 232 If set to
 233 .I yes
 234 and \-\-login and \-\-preserve\-environment were not specified
 235 .B su
 236 initializes
 237 .BR PATH .
 238 .RE
 239 .sp
 240 The environment variable PATH may be different on systems where /bin and /sbin
 241 are merged into /usr, this variable is also affected by \fB\-\-login\fR command line option and
 242 PAM system setting (e.g. pam_env).
 243 .SH EXIT STATUS
 244 .B su
 245 normally returns the exit status of the command it executed.  If the
 246 command was killed by a signal,
 247 .B su
 248 returns the number of the signal plus 128.
 249 .PP
 250 Exit status generated by
 251 .B su
 252 itself:
 253 .RS 10
 254 .TP
 255 1
 256 Generic error before executing the requested command
 257 .TP
 258 126
 259 The requested command could not be executed
 260 .TP
 261 127
 262 The requested command was not found
 263 .RE
 264 .SH FILES
 265 .PD 0
 266 .TP 17
 267 /etc/pam.d/su
 268 default PAM configuration file
 269 .TP
 270 /etc/pam.d/su-l
 271 PAM configuration file if \-\-login is specified
 272 .TP
 273 /etc/default/su
 274 command specific logindef config file
 275 .TP
 276 /etc/login.defs
 277 global logindef config file
 278 .PD 1
 279 .SH NOTES
 280 For security reasons
 281 .B su
 282 always logs failed log-in attempts to the btmp file, but it does not write to
 283 the lastlog file at all.  This solution allows to control
 284 .B su
 285 behavior by PAM configuration.  If you want to use the pam_lastlog module to
 286 print warning message about failed log-in attempts then the pam_lastlog has to
 287 be configured to update the lastlog file as well. For example by:
 288
 289 .RS
 290 .br
 291 session  required  pam_lastlog.so nowtmp
 292 .RE
 293 .SH SEE ALSO
 294 .BR setpriv (1),
 295 .BR login.defs (5),
 296 .BR shells (5),
 297 .BR pam (8),
 298 .BR runuser (1)
 299 .SH HISTORY
 300 This \fBsu\fR command was
 301 derived from coreutils' \fBsu\fR, which was based on an implementation by
 302 David MacKenzie. The util-linux has been refactored by Karel Zak.
 303 .SH AVAILABILITY
 304 The su command is part of the util-linux package and is
 305 available from
 306 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 307 Linux Kernel Archive
 308 .UE .