su - run a command with substitute user and group ID
su [options] [-] [user [argument...]]
su allows commands to be run with a substitute user and group ID.
When called with no user specified, su defaults to
running an interactive shell as root. When user is specified,
additional arguments can be supplied, in which case they are passed
to the shell.
For backward compatibility, su defaults to not change the
current directory and to only set the environment variables HOME and
SHELL (plus USER and LOGNAME if the target user
is not root). It is recommended to always use the --login option
(instead of its shortcut -) to avoid side effects caused by mixing
This version of su uses PAM for authentication, account and
session management. Some configuration options found in other su
implementations, such as support for a wheel group, have to be configured
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 runuser(1) that does not require
authentication and provides separate PAM configuration. If the PAM session
is not required at all then the recommended solution is to use command
Note that su in all cases uses 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
Pass command to the shell with the -c
Pass -f to the shell, which may or may not be
useful, depending on the shell.
Specify the primary group. This option is available to
the root user only.
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
TERM and variables specified by --whitelist-environment
•initializes the environment variables
HOME, SHELL, USER, LOGNAME, and PATH
•changes to the target user’s home
•sets argv 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. This option is
ignored if the option --login is specified.
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., "su --pty -
username -c application &"). If the pseudo-terminal is enabled, then
works as a proxy between the sessions (copy 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" | su --pty), then the ECHO flag for the pseudo-terminal is
disabled to avoid messy output.
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
If the target user has a restricted shell (i.e., not listed in
/etc/shells), the --shell option and the SHELL environment
variables are ignored unless the calling user is root.
Same as -c, but do not create a new session.
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.
Display version information and exit.
Display help text and exit.
Upon receiving either SIGINT, SIGQUIT or SIGTERM, su
terminates its child and afterwards terminates itself with the received
signal. The child is terminated by SIGTERM, after unsuccessful attempt
and 2 seconds of delay the child is killed by SIGKILL.
su reads the /etc/default/su and /etc/login.defs
configuration files. The following configuration items are relevant for
Delay in seconds in case of an authentication failure.
The number must be a non-negative integer.
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
su normally returns the exit status of the command it executed. If the
command was killed by a signal, su returns the number of the signal
If set to yes
were not specified su
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 generated by su itself:
Generic error before executing the requested
The requested command could not be executed
The requested command was not found
default PAM configuration file
PAM configuration file if --login is
command specific logindef config file
global logindef config file
For security reasons, su always logs failed log-in attempts to the btmp
file, but it does not write to the lastlog file at all. This solution
can be used to control su behavior by PAM configuration. If you want to
use the pam_lastlog(8) module to print warning message about failed
log-in attempts then pam_lastlog(8) has to be configured to update the
lastlog file as well. For example by:
This su command was derived from coreutils' su, which was based on
an implementation by David MacKenzie. The util-linux version has been
refactored by Karel Zak.
session required pam_lastlog.so nowtmp