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