# 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()) 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.
    
           **-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. This can be used to avoid
               TIOCSTI ioctl terminal injection and other security attacks
               against terminal file descriptors. 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.)
    
           **-T** , **--no-pty**
               Do not create a pseudo-terminal, opposite of **--pty** and **-P**.
               Note that running without a pseudo-terminal opens the security
               risk of privilege escalation through TIOCSTI/TIOCLINUX ioctl
               command injection.
    
           **-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



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


## 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/>. This page is
           part of the _util-linux_ (a random collection of Linux utilities)
           project. Information about the project can be found at 
           ⟨https://www.kernel.org/pub/linux/utils/util-linux/⟩. If you have a
           bug report for this manual page, send it to
           util-linux@vger.kernel.org. This page was obtained from the
           project's upstream Git repository
           ⟨git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git⟩ on
           2025-08-11. (At that time, the date of the most recent commit that
           was found in the repository was 2025-08-05.) If you discover any
           rendering problems in this HTML version of the page, or you
           believe there is a better or more up-to-date source for the page,
           or you have corrections or improvements to the information in this
           COLOPHON (which is _not_ part of the original manual page), send a
           mail to man-pages@man7.org
    
    util-linux 2.42-start-521-ec46  2025-08-09                     _RUNUSER_(1)
    


* * *