1RUNUSER(1) User Commands RUNUSER(1)
2
6 runuser - run a command with substitute user and group ID
7
9 runuser [options] -u user [[--] command [argument...]]
10 runuser [options] [-] [user [argument...]]
12
14 runuser can be used to run commands with a substitute user and group
15 ID. If the option -u is not given, runuser falls back to su-compatible
16 semantics and a shell is executed. The difference between the commands
17 runuser and su is that runuser does not ask for a password (because it
18 may be executed by the root user only) and it uses a different PAM con‐
19 figuration. The command runuser does not have to be installed with
20 set-user-ID permissions.
21 If the PAM session is not required, then the recommended solution is to
23 use the setpriv(1) command.
24 When called without arguments, runuser defaults to running an interac‐
26 tive shell as root.
27 For backward compatibility, runuser defaults to not changing the cur‐
29 rent directory and to setting only the environment variables HOME and
30 SHELL (plus USER and LOGNAME if the target user is not root). This
31 version of runuser uses PAM for session management.
32 Note that runuser in all cases use PAM (pam_getenvlist()) to do the
34 final environment modification. Command-line options such as --login
35 and --preserve-environment affect the environment before it is modified
36 by PAM.
37
39 -c, --command=command
40 Pass command to the shell with the -c option.
41 -f, --fast
43 Pass -f to the shell, which may or may not be useful, depending
44 on the shell.
45 -g, --group=group
47 The primary group to be used. This option is allowed for the
48 root user only.
49 -G, --supp-group=group
51 Specify a supplementary group. This option is available to the
52 root user only. The first specified supplementary group is also
53 used as a primary group if the option --group is not specified.
54 -, -l, --login
56 Start the shell as a login shell with an environment similar to
57 a real login:
58 * clears all the environment variables except for TERM and vari‐
60 ables specified by --whitelist-environment
61 * initializes the environment variables HOME, SHELL, USER, LOG‐
63 NAME, and PATH
64 * changes to the target user's home directory
66 * sets argv[0] of the shell to '-' in order to make the shell a
68 login shell
69 -P, --pty
71 Create a pseudo-terminal for the session. The independent termi‐
72 nal provides better security as the user does not share a termi‐
73 nal with the original session. This can be used to avoid TIOC‐
74 STI ioctl terminal injection and other security attacks against
75 terminal file descriptors. The entire session can also be moved
76 to the background (e.g., "runuser --pty -u username -- command
77 &"). If the pseudo-terminal is enabled, then runuser works as a
78 proxy between the sessions (copy stdin and stdout).
79 This feature is mostly designed for interactive sessions. If
81 the standard input is not a terminal, but for example a pipe
82 (e.g., echo "date" | runuser --pty -u user), then the ECHO flag
83 for the pseudo-terminal is disabled to avoid messy output.
84 -m, -p, --preserve-environment
86 Preserve the entire environment, i.e., do not set HOME, SHELL,
87 USER or LOGNAME. The option is ignored if the option --login is
88 specified.
89 -s, --shell=shell
91 Run the specified shell instead of the default. The shell to
92 run is selected according to the following rules, in order:
93 * the shell specified with --shell
95 * the shell specified in the environment variable SHELL if the
97 --preserve-environment option is used
98 * the shell listed in the passwd entry of the target user
100 * /bin/sh
102 If the target user has a restricted shell (i.e., not listed in
104 /etc/shells), then the --shell option and the SHELL environment
105 variables are ignored unless the calling user is root.
106 --session-command=command
108 Same as -c, but do not create a new session. (Discouraged.)
109 -w, --whitelist-environment=list
111 Don't reset the environment variables specified in the comma-
112 separated list when clearing the environment for --login. The
113 whitelist is ignored for the environment variables HOME, SHELL,
114 USER, LOGNAME, and PATH.
115 -V, --version
117 Display version information and exit.
118 -h, --help
120 Display help text and exit.
121
123 runuser reads the /etc/default/runuser and /etc/login.defs configura‐
124 tion files. The following configuration items are relevant for
125 runuser:
126 ENV_PATH (string)
128 Defines the PATH environment variable for a regular user. The
129 default value is /usr/local/bin:/bin:/usr/bin.
130 ENV_ROOTPATH (string)
132 ENV_SUPATH (string)
133 Defines the PATH environment variable for root. ENV_SUPATH takes
134 precedence. The default value is /usr/local/sbin:/usr/local/bin:
135 /sbin:/bin:/usr/sbin:/usr/bin.
136 ALWAYS_SET_PATH (boolean)
138 If set to yes and --login and --preserve-environment were not spec‐
139 ified runuser initializes PATH.
140 The environment variable PATH may be different on systems where /bin
142 and /sbin are merged into /usr; this variable is also affected by the
143 --login command-line option and the PAM system setting (e.g.,
144 pam_env(8)).
145
147 runuser normally returns the exit status of the command it executed.
148 If the command was killed by a signal, runuser returns the number of
149 the signal plus 128.
150 Exit status generated by runuser itself:
152 1 Generic error before executing the requested command
154 126 The requested command could not be executed
156 127 The requested command was not found
158
160 /etc/pam.d/runuser
161 default PAM configuration file
162 /etc/pam.d/runuser-l
163 PAM configuration file if --login is specified
164 /etc/default/runuser
165 runuser specific logindef config file
166 /etc/login.defs global logindef config file
167
169 This runuser command was derived from coreutils' su, which was based
170 on an implementation by David MacKenzie, and the Fedora runuser command
171 by Dan Walsh.
172
174 setpriv(1), su(1), login.defs(5), shells(5), pam(8)
175
177 The runuser command is part of the util-linux package and is available
178 from Linux Kernel Archive ⟨https://www.kernel.org/pub/linux/utils/util-
179 linux/⟩.
180util-linux July 2014 RUNUSER(1)