RUNUSER(1) User Commands RUNUSER(1) # [NAME](#NAME) runuser - run a command with substitute user and group ID # [SYNOPSIS](#SYNOPSIS) **runuser** \[options] **-u** *user* \[\[--] *command* \[*argument*...]] **runuser** \[options] \[**-**] \[*user* \[*argument*...]] # [DESCRIPTION](#DESCRIPTION) **runuser** can be used to run commands with a substitute user and group ID. If the option **-u** is not given, **runuser** falls back to **su**-compatible semantics and a shell is executed. The difference between the commands **runuser** and **su** is that **runuser** does not ask for a password (because it may be executed by the root user only) and it uses a different PAM configuration. The command **runuser** does not have to be installed with set-user-ID permissions. If the PAM session is not required, then the recommended solution is to use the [**setpriv**(1)](/man/os/util-linux/setpriv.1) command. When called without arguments, **runuser** defaults to running an interactive shell as *root*. For backward compatibility, **runuser** defaults to not changing the current directory and to setting only the environment variables **HOME** and **SHELL** (plus **USER** and **LOGNAME** if the target *user* is not root). This version of **runuser** uses PAM for session management. Note that **runuser** in all cases use PAM ([**pam\_getenvlist**(3)](/man/os/util-linux/pam_getenvlist.3)) to do the final environment modification. Command-line options such as **--login** and **--preserve-environment** affect the environment before it is modified by PAM. Since version 2.38 **runuser** resets process resource limits RLIMIT\_NICE, RLIMIT\_RTPRIO, RLIMIT\_FSIZE, RLIMIT\_AS and RLIMIT\_NOFILE. # [OPTIONS](#OPTIONS) **-c**, **--command**=*command* Pass *command* to the shell with the **-c** option. Creates a new session via [**setsid**(2)](/man/os/util-linux/setsid.2). Refer to **--session-command** to keep the same session. **-f**, **--fast** Pass **-f** to the shell, which may or may not be useful, depending on the shell. **-g**, **--group**=*group* The primary group to be used. This option is allowed for the root user only. **-G**, **--supp-group**=*group* Specify a supplementary group. This option is available to the root user only. The first specified supplementary group is also used as a primary group if the option **--group** is not specified. **-**, **-l**, **--login** Start the shell as a login shell with an environment similar to a real login: •clears all the environment variables except for **TERM**, **COLORTERM**, **NO\_COLOR** and variables specified by **--whitelist-environment** •initializes the environment variables **HOME**, **SHELL**, **USER**, **LOGNAME**, and **PATH** •changes to the target user’s home directory •sets argv\[0] of the shell to '**-**' in order to make the shell a login shell **-m**, **-p**, **--preserve-environment** Preserve the entire environment, i.e., do not set **HOME**, **SHELL**, **USER** or **LOGNAME**. The option is ignored if the option **--login** is specified. **-P**, **--pty** Create a pseudo-terminal for the session. The independent terminal provides better security as the user does not share a terminal with the original session. Please note security advice about TIOCSTI vulnerability below. The entire session can also be moved to the background (e.g., **runuser --pty** **-u** *user* **--** *command* **&**). If the pseudo-terminal is enabled, then **runuser** works as a proxy between the sessions (sync stdin and stdout). This feature is mostly designed for interactive sessions. If the standard input is not a terminal, but for example a pipe (e.g., **echo "date" | runuser --pty -u** *user*), then the **ECHO** flag for the pseudo-terminal is disabled to avoid messy output. **-s**, **--shell**=*shell* Run the specified *shell* instead of the default. The shell to run is selected according to the following rules, in order: •the shell specified with **--shell** •the shell specified in the environment variable **SHELL** if the **--preserve-environment** option is used •the shell listed in the passwd entry of the target user •/bin/sh If the target user has a restricted shell (i.e., not listed in */etc/shells*), then the **--shell** option and the **SHELL** environment variables are ignored unless the calling user is root. **--session-command=command** Same as **-c**, but do not create a new session. (Discouraged.) Please note security advice about TIOCSTI vulnerability below. **-T**, **--no-pty** Do not create a pseudo-terminal, opposite of **--pty** and **-P**. Please note security advice about TIOCSTI vulnerability below. **-u**, **--user**=*user* Run *command* with the effective user ID and group ID of the user name *user*. **-w**, **--whitelist-environment**=*list* Don’t reset the environment variables specified in the comma-separated *list* when clearing the environment for **--login**. The whitelist is ignored for the environment variables **HOME**, **SHELL**, **USER**, **LOGNAME**, and **PATH**. **-h**, **--help** Display help text and exit. **-V**, **--version** Display version and exit. # [CONFIG FILES](#CONFIG_FILES) **runuser** reads the */etc/default/runuser* and */etc/login.defs* configuration files. The following configuration items are relevant for **runuser**: **ENV\_PATH** (string) Defines the PATH environment variable for a regular user. The default value is */usr/local/bin:/bin:/usr/bin*. **ENV\_ROOTPATH** (string), **ENV\_SUPATH** (string) Defines the **PATH** environment variable for root. **ENV\_SUPATH** takes precedence. The default value is */usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin*. **ALWAYS\_SET\_PATH** (boolean) If set to *yes* and **--login** and **--preserve-environment** were not specified **runuser** initializes **PATH**. The environment variable **PATH** may be different on systems where */bin* and */sbin* are merged into */usr*; this variable is also affected by the **--login** command-line option and the PAM system setting (e.g., [**pam\_env**(8)](/man/os/util-linux/pam_env.8)). # [EXIT STATUS](#EXIT_STATUS) **runuser** normally returns the exit status of the command it executed. If the command was killed by a signal, **runuser** returns the number of the signal plus 128. Exit status generated by **runuser** itself: 1 Generic error before executing the requested command 126 The requested command could not be executed 127 The requested command was not found # [FILES](#FILES) */etc/pam.d/runuser* default PAM configuration file */etc/pam.d/runuser-l* PAM configuration file if **--login** is specified */etc/default/runuser* runuser specific logindef config file */etc/login.defs* global logindef config file # [SECURITY NOTES](#SECURITY_NOTES) If **runuser** shares a terminal with the original session, it is potentially vulnerable to privilege escalation through TIOCSTI/TIOCLINUX ioctl command injection. There are two built-in ways to prevent this: Either you can use **runuser** with the **-c** option, which starts a new session via [**setsid**(2)](/man/os/util-linux/setsid.2) without a controlling terminal. Or, if your use case requires a controlling terminal, for example an interactive session, you can instruct **runuser** to use a pseudo terminal with the **--pty** or **-P** option. # [HISTORY](#HISTORY) This **runuser** command was derived from coreutils' **su**, which was based on an implementation by David MacKenzie, and the Fedora **runuser** command by Dan Walsh. # [SEE ALSO](#SEE_ALSO) [**setpriv**(1)](/man/os/util-linux/setpriv.1), [**su**(1)](/man/os/util-linux/su.1), [**login.defs**(5)](/man/os/util-linux/login.defs.5), [**shells**(5)](/man/os/util-linux/shells.5), [**pam**(8)](/man/os/util-linux/pam.8) # [REPORTING BUGS](#REPORTING_BUGS) For bug reports, use the *issue tracker* <https://github.com/util-linux/util-linux/issues>. # [AVAILABILITY](#AVAILABILITY) The **runuser** command is part of the util-linux package which can be downloaded from *Linux Kernel Archive* <https://www.kernel.org/pub/linux/utils/util-linux/>. 2026-10-30 util-linux 2.42.4 --- Document: runuser(1) from util-linux 2.42.4-r2 (Chainguard OS)