1SU(1) User Commands SU(1)
2
6 su - run a command with substitute user and group ID
7
9 su [options] [-] [user [argument...]]
10
12 su allows to run commands with a substitute user and group ID.
13 When called with no user specified, su defaults to running an interac‐
15 tive shell as root. When user is specified, additional arguments can
16 be supplied, in which case they are passed to the shell.
17 For backward compatibility, su defaults to not change the current
19 directory and to only set the environment variables HOME and SHELL
20 (plus USER and LOGNAME if the target user is not root). It is recom‐
21 mended to always use the --login option (instead of its shortcut -) to
22 avoid side effects caused by mixing environments.
23 This version of su uses PAM for authentication, account and session
25 management. Some configuration options found in other su implementa‐
26 tions, such as support for a wheel group, have to be configured via
27 PAM.
28 su is mostly designed for unprivileged users, the recommended solution
30 for privileged users (e.g., scripts executed by root) is to use non-
31 set-user-ID command runuser(1) that does not require authentication and
32 provide separate PAM configuration. If the PAM session is not required
33 at all then the recommend solution is to use command setpriv(1).
34
37 -c, --command=command
38 Pass command to the shell with the -c option.
39 -f, --fast
41 Pass -f to the shell, which may or may not be useful, depending
42 on the shell.
43 -g, --group=group
45 Specify the primary group. This option is available to the root
46 user only.
47 -G, --supp-group=group
49 Specify a supplemental group. This option is available to the
50 root user only. The first specified supplementary group is also
51 used as a primary group if the option --group is unspecified.
52 -, -l, --login
54 Start the shell as a login shell with an environment similar to
55 a real login:
56 o clears all the environment variables except TERM and
58 variables specified by --whitelist-environment
59 o initializes the environment variables HOME, SHELL,
61 USER, LOGNAME, and PATH
62 o changes to the target user's home directory
64 o sets argv[0] of the shell to '-' in order to make the
66 shell a login shell
67 -m, -p, --preserve-environment
69 Preserve the entire environment, i.e., it does not set HOME,
70 SHELL, USER nor LOGNAME. This option is ignored if the option
71 --login is specified.
72 -P, --pty
74 Create pseudo-terminal for the session. The independent terminal
75 provides better security as user does not share terminal with
76 the original session. This allow to avoid TIOCSTI ioctl termi‐
77 nal injection and another security attacks against terminal file
78 descriptors. The all session is also possible to move to back‐
79 ground (e.g., "su --pty - username -c application &"). If the
80 pseudo-terminal is enabled then su command works as a proxy
81 between the sessions (copy stdin and stdout).
82 This feature is mostly designed for interactive sessions. If the
84 standard input is not a terminal, but for example pipe (e.g.,
85 echo "date" | su --pty) than ECHO flag for the pseudo-terminal
86 is disabled to avoid messy output.
87 -s, --shell=shell
89 Run the specified shell instead of the default. The shell to
90 run is selected according to the following rules, in order:
91 o the shell specified with --shell
93 o the shell specified in the environment variable SHELL,
95 if the --preserve-environment option is used
96 o the shell listed in the passwd entry of the target
98 user
99 o /bin/sh
101 If the target user has a restricted shell (i.e., not listed in
103 /etc/shells), the --shell option and the SHELL environment vari‐
104 ables are ignored unless the calling user is root.
105 --session-command=command
107 Same as -c but do not create a new session. (Discouraged.)
108 -w, --whitelist-environment=list
110 Don't reset environment variables specified in comma separated
111 list when clears environment for --login. The whitelist is
112 ignored for the environment variables HOME, SHELL, USER, LOG‐
113 NAME, and PATH.
114 -V, --version
116 Display version information and exit.
117 -h, --help
119 Display help text and exit.
120
122 Upon receiving either SIGINT, SIGQUIT or SIGTERM, su terminates its
123 child and afterwards terminates itself with the received signal. The
124 child is terminated by SIGTERM, after unsuccessful attempt and 2 sec‐
125 onds of delay the child is killed by SIGKILL.
126
128 su reads the /etc/default/su and /etc/login.defs configuration files.
129 The following configuration items are relevant for su(1):
130 FAIL_DELAY (number)
132 Delay in seconds in case of an authentication failure. The number
133 must be a non-negative integer.
134 ENV_PATH (string)
136 Defines the PATH environment variable for a regular user. The
137 default value is /usr/local/bin:/bin:/usr/bin.
138 ENV_ROOTPATH (string)
140 ENV_SUPATH (string)
141 Defines the PATH environment variable for root. ENV_SUPATH takes
142 precedence. The default value is /usr/local/sbin:/usr/local/bin:
143 /sbin:/bin:/usr/sbin:/usr/bin.
144 ALWAYS_SET_PATH (boolean)
146 If set to yes and --login and --preserve-environment were not spec‐
147 ified su initializes PATH.
148 The environment variable PATH may be different on systems where /bin
150 and /sbin are merged into /usr.
151
153 su normally returns the exit status of the command it executed. If the
154 command was killed by a signal, su returns the number of the signal
155 plus 128.
156 Exit status generated by su itself:
158 1 Generic error before executing the requested command
160 126 The requested command could not be executed
162 127 The requested command was not found
164
166 /etc/pam.d/su default PAM configuration file
167 /etc/pam.d/su-l PAM configuration file if --login is specified
168 /etc/default/su command specific logindef config file
169 /etc/login.defs global logindef config file
170
172 For security reasons su always logs failed log-in attempts to the btmp
173 file, but it does not write to the lastlog file at all. This solution
174 allows to control su behavior by PAM configuration. If you want to use
175 the pam_lastlog module to print warning message about failed log-in
176 attempts then the pam_lastlog has to be configured to update the last‐
177 log file as well. For example by:
178 session required pam_lastlog.so nowtmp
180
182 setpriv(1), login.defs(5), shells(5), pam(8), runuser(1)
183
185 This su command was derived from coreutils' su, which was based on an
186 implementation by David MacKenzie. The util-linux has been refactored
187 by Karel Zak.
188
190 The su command is part of the util-linux package and is available from
191 Linux Kernel Archive ⟨https://www.kernel.org/pub/linux/utils/util-
192 linux/⟩.
193util-linux July 2014 SU(1)