| .TH SU 1 "July 2014" "util-linux" "User Commands" |
| .SH NAME |
| su \- run a command with substitute user and group ID |
| .SH SYNOPSIS |
| .BR su " [options] [" \- ] |
| .RI [ user " [" argument ...]] |
| .SH DESCRIPTION |
| .B su |
| allows to run commands with a substitute user and group ID. |
| .PP |
| When called without arguments, |
| .B su |
| defaults to running an interactive shell as |
| .IR root . |
| .PP |
| For backward compatibility, |
| .B su |
| 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). It is recommended to always use the |
| .B \-\-login |
| option (instead of its shortcut |
| .BR \- ) |
| to avoid side effects caused by mixing environments. |
| .PP |
| This version of |
| .B su |
| uses PAM for authentication, account and session management. Some |
| configuration options found in other |
| .B su |
| implementations, such as support for a wheel group, have to be |
| configured via PAM. |
| .PP |
| .B su |
| is mostly designed for unprivileged users, the recommended solution for |
| privileged users (e.g. scripts executed by root) is to use |
| non-set-user-ID command |
| .BR runuser (1) |
| that does not require authentication and provide separate PAM configuration. If |
| the PAM session is not required at all then the recommend solution is to use |
| command |
| .BR setpriv (1). |
| |
| .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 |
| Specify the primary group. This option is available to 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 |
| .B TERM |
| .TP |
| o |
| initializes the environment variables |
| .BR HOME , |
| .BR SHELL , |
| .BR USER , |
| .BR LOGNAME ", and" |
| .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 . |
| This 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 |
| .BR 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 SIGNALS |
| Upon receiving either |
| .BR SIGINT , |
| .BR SIGQUIT |
| or |
| .BR SIGTERM , |
| .BR su |
| terminates its child and afterwards terminates itself with |
| the received signal. |
| .SH CONFIG FILES |
| .B su |
| reads the |
| .I /etc/default/su |
| and |
| .I /etc/login.defs |
| configuration files. The following configuration items are relevant |
| for |
| .BR su (1): |
| .PP |
| .B FAIL_DELAY |
| (number) |
| .RS 4 |
| Delay in seconds in case of an authentication failure. The number must be |
| a non-negative integer. |
| .RE |
| .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 su |
| initializes |
| .BR PATH . |
| .RE |
| .SH EXIT STATUS |
| .B su |
| normally returns the exit status of the command it executed. If the |
| command was killed by a signal, |
| .B su |
| returns the number of the signal plus 128. |
| .PP |
| Exit status generated by |
| .B su |
| 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/su |
| default PAM configuration file |
| .TP |
| /etc/pam.d/su-l |
| PAM configuration file if \-\-login is specified |
| .TP |
| /etc/default/su |
| command specific logindef config file |
| .TP |
| /etc/login.defs |
| global logindef config file |
| .PD 1 |
| .SH NOTES |
| For security reasons |
| .B su |
| always logs failed log-in attempts to the btmp file, but it does not write to |
| the lastlog file at all. This solution allows to control |
| .B su |
| behavior by PAM configuration. If you want to use the pam_lastlog module to |
| print warning message about failed log-in attempts then the pam_lastlog has to |
| be configured to update the lastlog file as well. For example by: |
| |
| .RS |
| .br |
| session required pam_lastlog.so nowtmp |
| .RE |
| .SH "SEE ALSO" |
| .BR setpriv (1), |
| .BR login.defs (5), |
| .BR shells (5), |
| .BR pam (8), |
| .BR runuser (8) |
| .SH HISTORY |
| This \fBsu\fR command was |
| derived from coreutils' \fBsu\fR, which was based on an implementation by |
| David MacKenzie. |
| .SH AVAILABILITY |
| The su 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 . |