--- name: "su" section: "1" platform: "linux" package: "util-linux" version: "2.42.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd", "openbsd", "macos"] url: "https://new.carta.tech/su" --- # su(1) run a command with substitute user and group ID ## NAME su - run a command with substitute user and group ID ## SYNOPSIS **su** \[options\] \[**-**\] \[*user*\|*UID* \[*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)](/runuser/1.md) 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)](/setpriv/1.md). Note that **su** in all cases uses PAM ([**pam\_getenvlist**(3)](/pam_getenvlist/3.md)) 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** *command* Pass *command* to the shell with the **-c** option. Creates a new session via [**setsid**(2)](/setsid/2.md). Refer to **--session-command** to keep the same session. - **-f**, **--fast** Pass **-f** to the shell, which may or may not be useful, depending on the shell. - **-g**, **--group** *group* Specify the primary group. This option is available to the root user only. - **-G**, **--supp-group** *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. Note that on [**systemd**(1)](/systemd/1.md)-based systems, a new session may be defined as a real entry point to the system. However, **su** does not create a real session (by PAM) from this point of view. You need to use tools like [**systemd-run**(1)](/systemd-run/1.md) or [**machinectl**(1)](/machinectl/1.md) to initiate a complete, real session. **su** does: • clear all the environment variables except **TERM**, **COLORTERM**, **NO\_COLOR** and variables specified by **--whitelist-environment** • initialize the environment variables **HOME**, **SHELL**, **USER**, **LOGNAME**, and **PATH** • change to the target user’s home directory • set 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. Please note security advice about TIOCSTI vulnerability below. The entire session can also be moved to the background (e.g., **su --pty** **-** *user* **-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** *shell* Run the specified *shell* instead of the default. 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. 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 - **--session-command=***command* Same as **-c**, but do not create a new session. (Discouraged.) Please note security advice about TIOCSTI vulnerability below. - **-T**, **--no-pty** Do not create a pseudo-terminal, opposite of **--pty** and **-P**. Please note security advice about TIOCSTI vulnerability below. - **-w**, **--whitelist-environment** *list* 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** Display 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)](/pam_env/8.md)). ## 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 ## SECURITY NOTES If **su** shares a terminal with the original session, it is potentially vulnerable to privilege escalation through TIOCSTI/TIOCLINUX ioctl command injection. There are two built-in ways to prevent this: Either you can use **su** with the **-c** option, which starts a new session via [**setsid**(2)](/setsid/2.md) without a controlling terminal. Or, if your use case requires a controlling terminal, for example an interactive session, you can instruct **su** to use a pseudo terminal with the **--pty** or **-P** option. 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)](/pam_lastlog/8.md) module to print warning message about failed log-in attempts then [**pam\_lastlog**(8)](/pam_lastlog/8.md) 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)](/setpriv/1.md), [**login.defs**(5)](/login.defs/5.md), [**shells**(5)](/shells/5.md), [**pam**(8)](/pam/8.md), [**runuser**(1)](/runuser/1.md) ## REPORTING BUGS For bug reports, use the *issue tracker* \. ## AVAILABILITY The **su** command is part of the util-linux package which can be downloaded from *Linux Kernel Archive* \.