| .TH RUNUSER 1 "July 2014" "util-linux" "User Commands" |
| .SH NAME |
| runuser \- run a command with substitute user and group ID |
| .SH SYNOPSIS |
| .BR runuser " [options] " \-u |
| .I user |
| .RI "[[\-\-] " command " ["argument "...]]" |
| .LP |
| .BR runuser " [options] [" \- ] |
| .RI [ user " [" argument "...]]" |
| .SH DESCRIPTION |
| .B runuser |
| allows to run commands with a substitute user and group ID. |
| If the option \fB\-u\fR is not given, it falls back to |
| .BR su -compatible |
| semantics and a shell is executed. |
| The difference between the commands |
| .B runuser |
| and |
| .B su |
| is that |
| .B 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 |
| .B runuser |
| does not have to be installed with set-user-ID permissions. |
| .PP |
| If the PAM session is not required then recommended solution is to use |
| .BR setpriv (1) |
| command. |
| .PP |
| When called without arguments, |
| .B runuser |
| defaults to running an interactive shell as |
| .IR root . |
| .PP |
| For backward compatibility, |
| .B runuser |
| defaults to not change the current directory and to only set the |
| environment variables |
| .B HOME |
| and |
| .B SHELL |
| (plus |
| .B USER |
| and |
| .B LOGNAME |
| if the target |
| .I user |
| is not root). |
| This version of |
| .B runuser |
| uses PAM for session management. |
| .SH OPTIONS |
| .TP |
| .BR \-c , " \-\-command" = \fIcommand |
| Pass |
| .I command |
| to the shell with the |
| .B \-c |
| option. |
| .TP |
| .BR \-f , " \-\-fast" |
| Pass |
| .B \-f |
| to the shell, which may or may not be useful depending on the |
| shell. |
| .TP |
| .BR \-g , " \-\-group" = \fIgroup |
| The primary group to be used. This option is allowed for the root user only. |
| .TP |
| .BR \-G , " \-\-supp\-group" = \fIgroup |
| Specify a supplemental 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 \fB\-\-group\fR is unspecified. |
| .TP |
| .BR \- , " \-l" , " \-\-login" |
| Start the shell as a login shell with an environment similar to a real |
| login: |
| .RS 10 |
| .TP |
| o |
| clears all the environment variables except for |
| .B TERM |
| .TP |
| o |
| initializes the environment variables |
| .BR HOME , |
| .BR SHELL , |
| .BR USER , |
| .BR LOGNAME , |
| .B PATH |
| .TP |
| o |
| changes to the target user's home directory |
| .TP |
| o |
| sets argv[0] of the shell to |
| .RB ' \- ' |
| in order to make the shell a login shell |
| .RE |
| .TP |
| .BR \-m , " \-p" , " \-\-preserve\-environment" |
| Preserve the entire environment, i.e. it does not set |
| .BR HOME , |
| .BR SHELL , |
| .B USER |
| nor |
| .BR LOGNAME . |
| The option is ignored if the option \fB\-\-login\fR is specified. |
| .TP |
| .BR \-s , " \-\-shell" = \fIshell |
| Run the specified \fIshell\fR instead of the default. The shell to run is |
| selected according to the following rules, in order: |
| .RS 10 |
| .TP |
| o |
| the shell specified with |
| .B \-\-shell |
| .TP |
| o |
| the shell specified in the environment variable |
| .B SHELL |
| if the |
| .B \-\-preserve\-environment |
| option is used |
| .TP |
| o |
| the shell listed in the passwd entry of the target user |
| .TP |
| o |
| /bin/sh |
| .RE |
| .IP |
| If the target user has a restricted shell (i.e. not listed in |
| /etc/shells) the |
| .B \-\-shell |
| option and the |
| .B SHELL |
| environment variables are ignored unless the calling user is root. |
| .TP |
| .BI \-\-session\-command= command |
| Same as |
| .B \-c , |
| but do not create a new session. (Discouraged.) |
| .TP |
| .BR \-V , " \-\-version" |
| Display version information and exit. |
| .TP |
| .BR \-h , " \-\-help" |
| Display help text and exit. |
| .SH CONFIG FILES |
| .B runuser |
| reads the |
| .I /etc/default/runuser |
| and |
| .I /etc/login.defs |
| configuration files. The following configuration items are relevant |
| for |
| .BR runuser : |
| .PP |
| .B ENV_PATH |
| (string) |
| .RS 4 |
| Defines the PATH environment variable for a regular user. The |
| default value is |
| .IR /usr/local/bin:\:/bin:\:/usr/bin . |
| .RE |
| .PP |
| .B ENV_ROOTPATH |
| (string) |
| .br |
| .B ENV_SUPATH |
| (string) |
| .RS 4 |
| Defines the PATH environment variable for root. The default value is |
| .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin . |
| .RE |
| .PP |
| .B ALWAYS_SET_PATH |
| (boolean) |
| .RS 4 |
| If set to |
| .I yes |
| and \-\-login and \-\-preserve\-environment were not specified |
| .B runuser |
| initializes |
| .BR PATH . |
| .RE |
| .SH EXIT STATUS |
| .B runuser |
| normally returns the exit status of the command it executed. If the |
| command was killed by a signal, |
| .B runuser |
| returns the number of the signal plus 128. |
| .PP |
| Exit status generated by |
| .B runuser |
| itself: |
| .RS 10 |
| .TP |
| 1 |
| Generic error before executing the requested command |
| .TP |
| 126 |
| The requested command could not be executed |
| .TP |
| 127 |
| The requested command was not found |
| .RE |
| .SH FILES |
| .PD 0 |
| .TP 17 |
| /etc/pam.d/runuser |
| default PAM configuration file |
| .TP |
| /etc/pam.d/runuser-l |
| PAM configuration file if \-\-login is specified |
| .TP |
| /etc/default/runuser |
| runuser specific logindef config file |
| .TP |
| /etc/login.defs |
| global logindef config file |
| .PD 1 |
| .SH "SEE ALSO" |
| .BR setpriv (1), |
| .BR su (1), |
| .BR login.defs (5), |
| .BR shells (5), |
| .BR pam (8) |
| .SH HISTORY |
| This \fB runuser\fR command was |
| derived from coreutils' \fBsu\fR, which was based on an implementation by |
| David MacKenzie, and the Fedora \fBrunuser\fR command by Dan Walsh. |
| .SH AVAILABILITY |
| The runuser command is part of the util-linux package and is |
| available from |
| .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
| Linux Kernel Archive |
| .UE . |