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 .TP
  86 o
  87 initializes the environment variables
  88 .BR HOME ,
  89 .BR SHELL ,
  90 .BR USER ,
  91 .BR LOGNAME ,
  92 .B PATH
  93 .TP
  94 o
  95 changes to the target user's home directory
  96 .TP
  97 o
  98 sets argv[0] of the shell to
  99 .RB ' \- '
 100 in order to make the shell a login shell
 101 .RE
 102 .TP
 103 .BR \-m , " \-p" , " \-\-preserve\-environment"
 104 Preserve the entire environment, i.e. it does not set
 105 .BR HOME ,
 106 .BR SHELL ,
 107 .B USER
 108 nor
 109 .BR LOGNAME .
 110 The option is ignored if the option \fB\-\-login\fR is specified.
 111 .TP
 112 .BR \-s , " \-\-shell" = \fIshell
 113 Run the specified \fIshell\fR instead of the default.  The shell to run is
 114 selected according to the following rules, in order:
 115 .RS 10
 116 .TP
 117 o
 118 the shell specified with
 119 .B \-\-shell
 120 .TP
 121 o
 122 the shell specified in the environment variable
 123 .B SHELL
 124 if the
 125 .B \-\-preserve\-environment
 126 option is used
 127 .TP
 128 o
 129 the shell listed in the passwd entry of the target user
 130 .TP
 131 o
 132 /bin/sh
 133 .RE
 134 .IP
 135 If the target user has a restricted shell (i.e. not listed in
 136 /etc/shells) the
 137 .B \-\-shell
 138 option and the
 139 .B SHELL
 140 environment variables are ignored unless the calling user is root.
 141 .TP
 142 .BI \-\-session\-command= command
 143 Same as
 144 .B \-c ,
 145 but do not create a new session.  (Discouraged.)
 146 .TP
 147 .BR \-V , " \-\-version"
 148 Display version information and exit.
 149 .TP
 150 .BR \-h , " \-\-help"
 151 Display help text and exit.
 152 .SH CONFIG FILES
 153 .B runuser
 154 reads the
 155 .I /etc/default/runuser
 156 and
 157 .I /etc/login.defs
 158 configuration files.  The following configuration items are relevant
 159 for
 160 .BR runuser :
 161 .PP
 162 .B ENV_PATH
 163 (string)
 164 .RS 4
 165 Defines the PATH environment variable for a regular user.  The
 166 default value is
 167 .IR /usr/local/bin:\:/bin:\:/usr/bin .
 168 .RE
 169 .PP
 170 .B ENV_ROOTPATH
 171 (string)
 172 .br
 173 .B ENV_SUPATH
 174 (string)
 175 .RS 4
 176 Defines the PATH environment variable for root. The default value is
 177 .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin .
 178 .RE
 179 .PP
 180 .B ALWAYS_SET_PATH
 181 (boolean)
 182 .RS 4
 183 If set to
 184 .I yes
 185 and \-\-login and \-\-preserve\-environment were not specified
 186 .B runuser
 187 initializes
 188 .BR PATH .
 189 .RE
 190 .SH EXIT STATUS
 191 .B runuser
 192 normally returns the exit status of the command it executed.  If the
 193 command was killed by a signal,
 194 .B runuser
 195 returns the number of the signal plus 128.
 196 .PP
 197 Exit status generated by
 198 .B runuser
 199 itself:
 200 .RS 10
 201 .TP
 202 1
 203 Generic error before executing the requested command
 204 .TP
 205 126
 206 The requested command could not be executed
 207 .TP
 208 127
 209 The requested command was not found
 210 .RE
 211 .SH FILES
 212 .PD 0
 213 .TP 17
 214 /etc/pam.d/runuser
 215 default PAM configuration file
 216 .TP
 217 /etc/pam.d/runuser-l
 218 PAM configuration file if \-\-login is specified
 219 .TP
 220 /etc/default/runuser
 221 runuser specific logindef config file
 222 .TP
 223 /etc/login.defs
 224 global logindef config file
 225 .PD 1
 226 .SH "SEE ALSO"
 227 .BR setpriv (1),
 228 .BR su (1),
 229 .BR login.defs (5),
 230 .BR shells (5),
 231 .BR pam (8)
 232 .SH HISTORY
 233 This \fB runuser\fR command was
 234 derived from coreutils' \fBsu\fR, which was based on an implementation by
 235 David MacKenzie, and the Fedora \fBrunuser\fR command by Dan Walsh.
 236 .SH AVAILABILITY
 237 The runuser command is part of the util-linux package and is
 238 available from
 239 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 240 Linux Kernel Archive
 241 .UE .