# man > SU(1) > **TLDR:** Switch shell to another user. > - Switch to superuser (requires the root password): `su` - Switch to a given user (requires the user's password): `su {{username}}` - Switch to a given user and simulate a full login shell: `su - {{username}}` - Execute a command as another user: `su - {{username}} {{-c|--command}} "{{command}}"` - Switch to a given user and use a specific shell (e.g., Zsh, fish, Bash): `su {{-s|--shell}} /{{path/to/shell}} {{username}}` - Display help: `su {{-h|--help}}` - Display version: `su {{-V|--version}}` *Source: tldr-pages* --- [_SU_(1)](https://www.chedong.com/phpMan.php/man/SU/1/markdown) User Commands [_SU_(1)](https://www.chedong.com/phpMan.php/man/SU/1/markdown) ## NAME su - run a command with substitute user and group ID ## SYNOPSIS **su **[options] [**-**] [_user_ [_argument_...]] ## DESCRIPTION **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 _argument_s 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 environments. 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 via PAM. **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)](https://www.chedong.com/phpMan.php/man/runuser/1/markdown) 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 [**setpriv**(1)](https://www.chedong.com/phpMan.php/man/setpriv/1/markdown). Note that **su **in all cases uses PAM ([**pam_getenvlist**(3)](https://www.chedong.com/phpMan.php/man/pamgetenvlist/3/markdown)) 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 **su **resets process resource limits RLIMIT_NICE, RLIMIT_RTPRIO, RLIMIT_FSIZE, RLIMIT_AS and RLIMIT_NOFILE. ## OPTIONS ### -c --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 Specify the primary group. This option is available to the root user only. ### -G --supp-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 **TERM **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**. This 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., **su --pty - _**username_ **-c _**application_ **&**). If the pseudo-terminal is enabled, then **su **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" | su --pty**), then the **ECHO **flag for the pseudo-terminal is disabled to avoid messy output. ### -s --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_), 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.) ### -w --whitelist-environment 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 Print version and exit. ## SIGNALS 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**. ## CONFIG FILES **su **reads the _/etc/default/su_ and _/etc/login.defs_ configuration files. The following configuration items are relevant for **su**: ### FAIL_DELAY (number) Delay in seconds in case of an authentication failure. The number must be a non-negative integer. ### 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 **su **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)](https://www.chedong.com/phpMan.php/man/pamenv/8/markdown)). ## EXIT STATUS **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 plus 128. Exit status generated by **su **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/su_ default PAM configuration file _/etc/pam.d/su-l_ PAM configuration file if **--login **is specified _/etc/default/su_ command specific logindef config file _/etc/login.defs_ global logindef config file ## NOTES 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)](https://www.chedong.com/phpMan.php/man/pamlastlog/8/markdown) module to print warning message about failed log-in attempts then [**pam_lastlog**(8)](https://www.chedong.com/phpMan.php/man/pamlastlog/8/markdown) has to be configured to update the _lastlog_ file as well. For example by: session required pam_lastlog.so nowtmp ## HISTORY 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. ## SEE ALSO [**setpriv**(1)](https://www.chedong.com/phpMan.php/man/setpriv/1/markdown), [**login.defs**(5)](https://www.chedong.com/phpMan.php/man/login.defs/5/markdown), [**shells**(5)](https://www.chedong.com/phpMan.php/man/shells/5/markdown), [**pam**(8)](https://www.chedong.com/phpMan.php/man/pam/8/markdown), [**runuser**(1)](https://www.chedong.com/phpMan.php/man/runuser/1/markdown) ## REPORTING BUGS For bug reports, use the issue tracker at . ## AVAILABILITY The **su **command is part of the util-linux package which can be downloaded from Linux Kernel Archive <>. util-linux 2.39.3 2023-10-23 [_SU_(1)](https://www.chedong.com/phpMan.php/man/SU/1/markdown)