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 commands to be run 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 Note that su in all cases use PAM (pam_getenvlist[1m(3)) to do the final
36 environment modification. Command-line options such as --login and
37 --preserve-environment affect the environment before it is modified by
38 PAM.
39
42 -c, --command=command
43 Pass command to the shell with the -c option.
44 -f, --fast
46 Pass -f to the shell, which may or may not be useful, depending
47 on the shell.
48 -g, --group=group
50 Specify the primary group. This option is available to the root
51 user only.
52 -G, --supp-group=group
54 Specify a supplementary group. This option is available to the
55 root user only. The first specified supplementary group is also
56 used as a primary group if the option --group is not specified.
57 -, -l, --login
59 Start the shell as a login shell with an environment similar to
60 a real login:
61 o clears all the environment variables except TERM and
63 variables specified by --whitelist-environment
64 o initializes the environment variables HOME, SHELL,
66 USER, LOGNAME, and PATH
67 o changes to the target user's home directory
69 o sets argv[0] of the shell to '-' in order to make the
71 shell a login shell
72 -m, -p, --preserve-environment
74 Preserve the entire environment, i.e., do not set HOME, SHELL,
75 USER or LOGNAME. This option is ignored if the option --login
76 is specified.
77 -P, --pty
79 Create a pseudo-terminal for the session. The independent termi‐
80 nal provides better security as the user does not share a termi‐
81 nal with the original session. This can be used to avoid TIOC‐
82 STI ioctl terminal injection and other security attacks against
83 terminal file descriptors. The entire session can also be moved
84 to the background (e.g., "su --pty - username -c application
85 &"). If the pseudo-terminal is enabled, then su works as a
86 proxy between the sessions (copy stdin and stdout).
87 This feature is mostly designed for interactive sessions. If
89 the standard input is not a terminal, but for example a pipe
90 (e.g., echo "date" | su --pty), then the ECHO flag for the
91 pseudo-terminal is disabled to avoid messy output.
92 -s, --shell=shell
94 Run the specified shell instead of the default. The shell to
95 run is selected according to the following rules, in order:
96 o the shell specified with --shell
98 o the shell specified in the environment variable SHELL,
100 if the --preserve-environment option is used
101 o the shell listed in the passwd entry of the target
103 user
104 o /bin/sh
106 If the target user has a restricted shell (i.e., not listed in
108 /etc/shells), the --shell option and the SHELL environment vari‐
109 ables are ignored unless the calling user is root.
110 --session-command=command
112 Same as -c, but do not create a new session. (Discouraged.)
113 -w, --whitelist-environment=list
115 Don't reset the environment variables specified in the comma-
116 separated list when clearing the environment for --login. The
117 whitelist is ignored for the environment variables HOME, SHELL,
118 USER, LOGNAME, and PATH.
119 -V, --version
121 Display version information and exit.
122 -h, --help
124 Display help text and exit.
125
127 Upon receiving either SIGINT, SIGQUIT or SIGTERM, su terminates its
128 child and afterwards terminates itself with the received signal. The
129 child is terminated by SIGTERM, after unsuccessful attempt and 2 sec‐
130 onds of delay the child is killed by SIGKILL.
131
133 su reads the /etc/default/su and /etc/login.defs configuration files.
134 The following configuration items are relevant for su:
135 FAIL_DELAY (number)
137 Delay in seconds in case of an authentication failure. The number
138 must be a non-negative integer.
139 ENV_PATH (string)
141 Defines the PATH environment variable for a regular user. The
142 default value is /usr/local/bin:/bin:/usr/bin.
143 ENV_ROOTPATH (string)
145 ENV_SUPATH (string)
146 Defines the PATH environment variable for root. ENV_SUPATH takes
147 precedence. The default value is /usr/local/sbin:/usr/local/bin:
148 /sbin:/bin:/usr/sbin:/usr/bin.
149 ALWAYS_SET_PATH (boolean)
151 If set to yes and --login and --preserve-environment were not spec‐
152 ified su initializes PATH.
153 The environment variable PATH may be different on systems where /bin
155 and /sbin are merged into /usr; this variable is also affected by the
156 --login command-line option and the PAM system setting (e.g.,
157 pam_env(8)).
158
160 su normally returns the exit status of the command it executed. If the
161 command was killed by a signal, su returns the number of the signal
162 plus 128.
163 Exit status generated by su itself:
165 1 Generic error before executing the requested command
167 126 The requested command could not be executed
169 127 The requested command was not found
171
173 /etc/pam.d/su default PAM configuration file
174 /etc/pam.d/su-l PAM configuration file if --login is specified
175 /etc/default/su command specific logindef config file
176 /etc/login.defs global logindef config file
177
179 For security reasons, su always logs failed log-in attempts to the btmp
180 file, but it does not write to the lastlog file at all. This solution
181 can be used to control su behavior by PAM configuration. If you want
182 to use the pam_lastlog(8) module to print warning message about failed
183 log-in attempts then pam_lastlog(8) has to be configured to update the
184 lastlog file as well. For example by:
185 session required pam_lastlog.so nowtmp
187
189 This su command was derived from coreutils' su, which was based on an
190 implementation by David MacKenzie. The util-linux version has been
191 refactored by Karel Zak.
192
194 setpriv(1), login.defs(5), shells(5), pam(8), runuser(1)
195
197 The su command is part of the util-linux package and is available from
198 Linux Kernel Archive ⟨https://www.kernel.org/pub/linux/utils/util-
199 linux/⟩.
200util-linux July 2014 SU(1)