diff options
Diffstat (limited to '')
-rw-r--r-- | login-utils/runuser.1 | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/login-utils/runuser.1 b/login-utils/runuser.1 new file mode 100644 index 0000000..bf0d024 --- /dev/null +++ b/login-utils/runuser.1 @@ -0,0 +1,254 @@ +.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 +and variables specified by \fB\-\-whitelist\-environment\fR +.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 \-w , " \-\-whitelist\-environment" = \fIlist +Don't reset environment variables specified in comma separated \fIlist\fR when clears +environment for \fB\-\-login\fR. The whitelist is ignored for the environment variables +.BR HOME , +.BR SHELL , +.BR USER , +.BR LOGNAME ", and" +.BR PATH "." +.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 +.sp +The environment variable PATH may be different on systems where /bin and /sbin +are merged into /usr. +.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 . |