//po4a: entry man manual
= runuser(1)
:doctype: manpage
:man manual: User Commands
:man source: util-linux {release-version}
:page-layout: base
:command: runuser

== NAME

runuser - run a command with substitute user and group ID

== SYNOPSIS

*runuser* [options] *-u* _user_ [[--] _command_ [_argument_...]]

*runuser* [options] [*-*] [_user_ [_argument_...]]

== 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) 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)) 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

*-c*, *--command*=_command_::
Pass _command_ to the shell with the *-c* option.
Creates a new session via *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*.

include::man-common/help-version.adoc[]

== 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)).

== 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

_/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

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) 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

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

*setpriv*(1),
*su*(1),
*login.defs*(5),
*shells*(5),
*pam*(8)

include::man-common/bugreports.adoc[]

include::man-common/footer.adoc[]

ifdef::translation[]
include::man-common/translation.adoc[]
endif::[]
