login-utils/runuser.1

   1 .TH RUNUSER 1 "July 2014" "util-linux" "User Commands"
   2 .SH NAME
   3 runuser \- run a command with substitute user and group ID
   4 .SH SYNOPSIS
   5 .BR runuser " [options] " \-u
   6 .I user
   7 .RI "[[\-\-] " command " ["argument "...]]"
   8 .LP
   9 .BR runuser " [options] [" \- ]
  10 .RI [ user " [" argument "...]]"
  11 .SH DESCRIPTION
  12 .B runuser
  13 allows to run commands with a substitute user and group ID.
  14 If the option \fB\-u\fR is not given, it falls back to
  15 .BR su -compatible
  16 semantics and a shell is executed.
  17 The difference between the commands
  18 .B runuser
  19 and
  20 .B su
  21 is that
  22 .B runuser
  23 does not ask for a password (because it may be executed by the root user only) and
  24 it uses a different PAM configuration.
  25 The command
  26 .B runuser
  27 does not have to be installed with set-user-ID permissions.
  28 .PP
  29 If the PAM session is not required then recommended solution is to use
  30 .BR setpriv (1)
  31 command.
  32 .PP
  33 When called without arguments,
  34 .B runuser
  35 defaults to running an interactive shell as
  36 .IR root .
  37 .PP
  38 For backward compatibility,
  39 .B runuser
  40 defaults to not change the current directory and to only set the
  41 environment variables
  42 .B HOME
  43 and
  44 .B SHELL
  45 (plus
  46 .B USER
  47 and
  48 .B LOGNAME
  49 if the target
  50 .I user
  51 is not root).
  52 This version of
  53 .B runuser
  54 uses PAM for session management.
  55 .SH OPTIONS
  56 .TP
  57 .BR \-c , " \-\-command" = \fIcommand
  58 Pass
  59 .I command
  60 to the shell with the
  61 .B \-c
  62 option.
  63 .TP
  64 .BR \-f , " \-\-fast"
  65 Pass
  66 .B \-f
  67 to the shell, which may or may not be useful depending on the
  68 shell.
  69 .TP
  70 .BR \-g , " \-\-group" = \fIgroup
  71 The primary group to be used.  This option is allowed for the root user only.
  72 .TP
  73 .BR \-G , " \-\-supp\-group" = \fIgroup
  74 Specify a supplemental group.  This option is available to the root user only.  The first specified
  75 supplementary group is also used as a primary group if the option \fB\-\-group\fR is unspecified.
  76 .TP
  77 .BR \- , " \-l" , " \-\-login"
  78 Start the shell as a login shell with an environment similar to a real
  79 login:
  80 .RS 10
  81 .TP
  82 o
  83 clears all the environment variables except for
  84 .B TERM
  85 and variables specified by \fB\-\-whitelist\-environment\fR
  86 .TP
  87 o
  88 initializes the environment variables
  89 .BR HOME ,
  90 .BR SHELL ,
  91 .BR USER ,
  92 .BR LOGNAME ,
  93 .B PATH
  94 .TP
  95 o
  96 changes to the target user's home directory
  97 .TP
  98 o
  99 sets argv[0] of the shell to
 100 .RB ' \- '
 101 in order to make the shell a login shell
 102 .RE
 103 .TP
 104 .BR \-P , " \-\-pty"
 105 Create pseudo-terminal for the session. The independent terminal provides
 106 better security as user does not share terminal with the original
 107 session.  This allow to avoid TIOCSTI ioctl terminal injection and another
 108 security attacks against terminal file descriptors. The all session is also
 109 possible to move to background (e.g. "runuser --pty -u username -- command &").
 110 If the pseudo-terminal is enabled then runuser command works
 111 as a proxy between the sessions (copy stdin and stdout).
 112 .sp
 113 This feature is mostly designed for interactive sessions. If the standard input
 114 is not a terminal, but for example pipe (e.g. echo "date" | runuser --pty -u user)
 115 than ECHO flag for the pseudo-terminal is disabled to avoid messy output.
 116 .TP
 117 .BR \-m , " \-p" , " \-\-preserve\-environment"
 118 Preserve the entire environment, i.e. it does not set
 119 .BR HOME ,
 120 .BR SHELL ,
 121 .B USER
 122 nor
 123 .BR LOGNAME .
 124 The option is ignored if the option \fB\-\-login\fR is specified.
 125 .TP
 126 .BR \-s , " \-\-shell" = \fIshell
 127 Run the specified \fIshell\fR instead of the default.  The shell to run is
 128 selected according to the following rules, in order:
 129 .RS 10
 130 .TP
 131 o
 132 the shell specified with
 133 .B \-\-shell
 134 .TP
 135 o
 136 the shell specified in the environment variable
 137 .B SHELL
 138 if the
 139 .B \-\-preserve\-environment
 140 option is used
 141 .TP
 142 o
 143 the shell listed in the passwd entry of the target user
 144 .TP
 145 o
 146 /bin/sh
 147 .RE
 148 .IP
 149 If the target user has a restricted shell (i.e. not listed in
 150 /etc/shells) the
 151 .B \-\-shell
 152 option and the
 153 .B SHELL
 154 environment variables are ignored unless the calling user is root.
 155 .TP
 156 .BI \-\-session\-command= command
 157 Same as
 158 .B \-c ,
 159 but do not create a new session.  (Discouraged.)
 160 .TP
 161 .BR \-w , " \-\-whitelist\-environment" = \fIlist
 162 Don't reset environment variables specified in comma separated \fIlist\fR when clears
 163 environment for \fB\-\-login\fR. The whitelist is ignored for the environment variables
 164 .BR HOME ,
 165 .BR SHELL ,
 166 .BR USER ,
 167 .BR LOGNAME ", and"
 168 .BR PATH "."
 169 .TP
 170 .BR \-V , " \-\-version"
 171 Display version information and exit.
 172 .TP
 173 .BR \-h , " \-\-help"
 174 Display help text and exit.
 175 .SH CONFIG FILES
 176 .B runuser
 177 reads the
 178 .I /etc/default/runuser
 179 and
 180 .I /etc/login.defs
 181 configuration files.  The following configuration items are relevant
 182 for
 183 .BR runuser :
 184 .PP
 185 .B ENV_PATH
 186 (string)
 187 .RS 4
 188 Defines the PATH environment variable for a regular user.  The
 189 default value is
 190 .IR /usr/local/bin:\:/bin:\:/usr/bin .
 191 .RE
 192 .PP
 193 .B ENV_ROOTPATH
 194 (string)
 195 .br
 196 .B ENV_SUPATH
 197 (string)
 198 .RS 4
 199 Defines the PATH environment variable for root.  ENV_SUPATH takes precedence.  The default value is
 200 .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin .
 201 .RE
 202 .PP
 203 .B ALWAYS_SET_PATH
 204 (boolean)
 205 .RS 4
 206 If set to
 207 .I yes
 208 and \-\-login and \-\-preserve\-environment were not specified
 209 .B runuser
 210 initializes
 211 .BR PATH .
 212 .RE
 213 .sp
 214 The environment variable PATH may be different on systems where /bin and /sbin
 215 are merged into /usr.
 216 .SH EXIT STATUS
 217 .B runuser
 218 normally returns the exit status of the command it executed.  If the
 219 command was killed by a signal,
 220 .B runuser
 221 returns the number of the signal plus 128.
 222 .PP
 223 Exit status generated by
 224 .B runuser
 225 itself:
 226 .RS 10
 227 .TP
 228 1
 229 Generic error before executing the requested command
 230 .TP
 231 126
 232 The requested command could not be executed
 233 .TP
 234 127
 235 The requested command was not found
 236 .RE
 237 .SH FILES
 238 .PD 0
 239 .TP 17
 240 /etc/pam.d/runuser
 241 default PAM configuration file
 242 .TP
 243 /etc/pam.d/runuser-l
 244 PAM configuration file if \-\-login is specified
 245 .TP
 246 /etc/default/runuser
 247 runuser specific logindef config file
 248 .TP
 249 /etc/login.defs
 250 global logindef config file
 251 .PD 1
 252 .SH "SEE ALSO"
 253 .BR setpriv (1),
 254 .BR su (1),
 255 .BR login.defs (5),
 256 .BR shells (5),
 257 .BR pam (8)
 258 .SH HISTORY
 259 This \fB runuser\fR command was
 260 derived from coreutils' \fBsu\fR, which was based on an implementation by
 261 David MacKenzie, and the Fedora \fBrunuser\fR command by Dan Walsh.
 262 .SH AVAILABILITY
 263 The runuser command is part of the util-linux package and is
 264 available from
 265 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 266 Linux Kernel Archive
 267 .UE .