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
15 interactive shell as root. When user is specified, additional arguments
16 can 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
21 recommended to always use the --login option (instead of its shortcut
22 -) to 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
26 implementations, such as support for a wheel group, have to be
27 configured via 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
31 non-set-user-ID command runuser(1) that does not require authentication
32 and provides separate PAM configuration. If the PAM session is not
33 required at all then the recommended solution is to use command
34 setpriv(1).
35 Note that su in all cases uses PAM (pam_getenvlist(3)) to do the final
37 environment modification. Command-line options such as --login and
38 --preserve-environment affect the environment before it is modified by
39 PAM.
40
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 on
47 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 root
55 user only. The first specified supplementary group is also used as
56 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 a
60 real login:
61 • clears all the environment variables except TERM and variables
63 specified by --whitelist-environment
64 • initializes the environment variables HOME, SHELL, USER,
66 LOGNAME, and PATH
67 • changes to the target user’s home directory
69 • sets argv[0] of the shell to '-' in order to make the shell a
71 login shell
72 -m, -p, --preserve-environment
74 Preserve the entire environment, i.e., do not set HOME, SHELL, USER
75 or LOGNAME. This option is ignored if the option --login is
76 specified.
77 -P, --pty
79 Create a pseudo-terminal for the session. The independent terminal
80 provides better security as the user does not share a terminal with
81 the original session. This can be used to avoid TIOCSTI ioctl
82 terminal injection and other security attacks against terminal file
83 descriptors. The entire session can also be moved to the background
84 (e.g., "su --pty - username -c application &"). If the
85 pseudo-terminal is enabled, then su works as a proxy between the
86 sessions (copy stdin and stdout).
87 This feature is mostly designed for interactive sessions. If the
89 standard input is not a terminal, but for example a pipe (e.g.,
90 echo "date" | su --pty), then the ECHO flag for the pseudo-terminal
91 is disabled to avoid messy output.
92 -s, --shell=shell
94 Run the specified shell instead of the default. The shell to run is
95 selected according to the following rules, in order:
96 • the shell specified with --shell
98 • the shell specified in the environment variable SHELL, if the
100 --preserve-environment option is used
101 • the shell listed in the passwd entry of the target user
103 • /bin/sh
105 If the target user has a restricted shell (i.e., not listed in
107 /etc/shells), the --shell option and the SHELL environment variables
108 are ignored unless the calling user is root.
109 --session-command=command
111 Same as -c, but do not create a new session. (Discouraged.)
112 -w, --whitelist-environment=list
114 Don’t reset the environment variables specified in the
115 comma-separated list when clearing the environment for --login. The
116 whitelist is ignored for the environment variables HOME, SHELL,
117 USER, LOGNAME, and PATH.
118 -V, --version
120 Display version information and exit.
121 -h, --help
123 Display help text and exit.
124
126 Upon receiving either SIGINT, SIGQUIT or SIGTERM, su terminates its
127 child and afterwards terminates itself with the received signal. The
128 child is terminated by SIGTERM, after unsuccessful attempt and 2
129 seconds of delay the child is killed by SIGKILL.
130
132 su reads the /etc/default/su and /etc/login.defs configuration files.
133 The following configuration items are relevant for su:
134 FAIL_DELAY (number)
136 Delay in seconds in case of an authentication failure. The number
137 must be a non-negative integer.
138 ENV_PATH (string)
140 Defines the PATH environment variable for a regular user. The
141 default value is /usr/local/bin:/bin:/usr/bin.
142 ENV_ROOTPATH (string), ENV_SUPATH (string)
144 Defines the PATH environment variable for root. ENV_SUPATH takes
145 precedence. The default value is
146 /usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin.
147 ALWAYS_SET_PATH (boolean)
149 If set to yes and --login and --preserve-environment were not
150 specified su initializes PATH.
151 The environment variable PATH may be different on systems where
153 /bin and /sbin are merged into /usr; this variable is also affected
154 by the --login command-line option and the PAM system setting
155 (e.g., pam_env(8)).
156
158 su normally returns the exit status of the command it executed. If the
159 command was killed by a signal, su returns the number of the signal
160 plus 128.
161 Exit status generated by su itself:
163 1
165 Generic error before executing the requested command
166 126
168 The requested command could not be executed
169 127
171 The requested command was not found
172
174 /etc/pam.d/su
175 default PAM configuration file
176 /etc/pam.d/su-l
178 PAM configuration file if --login is specified
179 /etc/default/su
181 command specific logindef config file
182 /etc/login.defs
184 global logindef config file
185
187 For security reasons, su always logs failed log-in attempts to the btmp
188 file, but it does not write to the lastlog file at all. This solution
189 can be used to control su behavior by PAM configuration. If you want to
190 use the pam_lastlog(8) module to print warning message about failed
191 log-in attempts then pam_lastlog(8) has to be configured to update the
192 lastlog file as well. For example by:
193 session required pam_lastlog.so nowtmp
195
197 This su command was derived from coreutils' su, which was based on an
198 implementation by David MacKenzie. The util-linux version has been
199 refactored by Karel Zak.
200
202 setpriv(1), login.defs(5), shells(5), pam(8), runuser(1)
203
205 For bug reports, use the issue tracker at
206 https://github.com/karelzak/util-linux/issues.
207
209 The su command is part of the util-linux package which can be
210 downloaded from Linux Kernel Archive
211 <https://www.kernel.org/pub/linux/utils/util-linux/>.
212util-linux 2.37.2 2021-06-02 SU(1)