1SU(1)                            User Commands                           SU(1)
2
3
4

NAME

6       su - run a command with substitute user and group ID
7

SYNOPSIS

9       su [options] [-] [user [argument...]]
10

DESCRIPTION

12       su allows commands to be run with a substitute user and group ID.
13
14       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
18       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
24       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
29       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
36       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
41       Since version 2.38 su resets process resource limits RLIMIT_NICE,
42       RLIMIT_RTPRIO, RLIMIT_FSIZE, RLIMIT_AS and RLIMIT_NOFILE.
43

OPTIONS

45       -c, --command=command
46           Pass command to the shell with the -c option.
47
48       -f, --fast
49           Pass -f to the shell, which may or may not be useful, depending on
50           the shell.
51
52       -g, --group=group
53           Specify the primary group. This option is available to the root
54           user only.
55
56       -G, --supp-group=group
57           Specify a supplementary group. This option is available to the root
58           user only. The first specified supplementary group is also used as
59           a primary group if the option --group is not specified.
60
61       -, -l, --login
62           Start the shell as a login shell with an environment similar to a
63           real login:
64
65           •   clears all the environment variables except TERM and variables
66               specified by --whitelist-environment
67
68           •   initializes the environment variables HOME, SHELL, USER,
69               LOGNAME, and PATH
70
71           •   changes to the target user’s home directory
72
73           •   sets argv[0] of the shell to '-' in order to make the shell a
74               login shell
75
76       -m, -p, --preserve-environment
77           Preserve the entire environment, i.e., do not set HOME, SHELL, USER
78           or LOGNAME. This option is ignored if the option --login is
79           specified.
80
81       -P, --pty
82           Create a pseudo-terminal for the session. The independent terminal
83           provides better security as the user does not share a terminal with
84           the original session. This can be used to avoid TIOCSTI ioctl
85           terminal injection and other security attacks against terminal file
86           descriptors. The entire session can also be moved to the background
87           (e.g., su --pty - username -c application &). If the
88           pseudo-terminal is enabled, then su works as a proxy between the
89           sessions (sync stdin and stdout).
90
91           This feature is mostly designed for interactive sessions. If the
92           standard input is not a terminal, but for example a pipe (e.g.,
93           echo "date" | su --pty), then the ECHO flag for the pseudo-terminal
94           is disabled to avoid messy output.
95
96       -s, --shell=shell
97           Run the specified shell instead of the default. The shell to run is
98           selected according to the following rules, in order:
99
100           •   the shell specified with --shell
101
102           •   the shell specified in the environment variable SHELL, if the
103               --preserve-environment option is used
104
105           •   the shell listed in the passwd entry of the target user
106
107           •   /bin/sh
108
109       If the target user has a restricted shell (i.e., not listed in
110       /etc/shells), the --shell option and the SHELL environment variables
111       are ignored unless the calling user is root.
112
113       --session-command=command
114           Same as -c, but do not create a new session. (Discouraged.)
115
116       -w, --whitelist-environment=list
117           Don’t reset the environment variables specified in the
118           comma-separated list when clearing the environment for --login. The
119           whitelist is ignored for the environment variables HOME, SHELL,
120           USER, LOGNAME, and PATH.
121
122       -h, --help
123           Display help text and exit.
124
125       -V, --version
126           Print version and exit.
127

SIGNALS

129       Upon receiving either SIGINT, SIGQUIT or SIGTERM, su terminates its
130       child and afterwards terminates itself with the received signal. The
131       child is terminated by SIGTERM, after unsuccessful attempt and 2
132       seconds of delay the child is killed by SIGKILL.
133

CONFIG FILES

135       su reads the /etc/default/su and /etc/login.defs configuration files.
136       The following configuration items are relevant for su:
137
138       FAIL_DELAY (number)
139           Delay in seconds in case of an authentication failure. The number
140           must be a non-negative integer.
141
142       ENV_PATH (string)
143           Defines the PATH environment variable for a regular user. The
144           default value is /usr/local/bin:/bin:/usr/bin.
145
146       ENV_ROOTPATH (string), ENV_SUPATH (string)
147           Defines the PATH environment variable for root. ENV_SUPATH takes
148           precedence. The default value is
149           /usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin.
150
151       ALWAYS_SET_PATH (boolean)
152           If set to yes and --login and --preserve-environment were not
153           specified su initializes PATH.
154
155           The environment variable PATH may be different on systems where
156           /bin and /sbin are merged into /usr; this variable is also affected
157           by the --login command-line option and the PAM system setting
158           (e.g., pam_env(8)).
159

EXIT STATUS

161       su normally returns the exit status of the command it executed. If the
162       command was killed by a signal, su returns the number of the signal
163       plus 128.
164
165       Exit status generated by su itself:
166
167       1
168           Generic error before executing the requested command
169
170       126
171           The requested command could not be executed
172
173       127
174           The requested command was not found
175

FILES

177       /etc/pam.d/su
178           default PAM configuration file
179
180       /etc/pam.d/su-l
181           PAM configuration file if --login is specified
182
183       /etc/default/su
184           command specific logindef config file
185
186       /etc/login.defs
187           global logindef config file
188

NOTES

190       For security reasons, su always logs failed log-in attempts to the btmp
191       file, but it does not write to the lastlog file at all. This solution
192       can be used to control su behavior by PAM configuration. If you want to
193       use the pam_lastlog(8) module to print warning message about failed
194       log-in attempts then pam_lastlog(8) has to be configured to update the
195       lastlog file as well. For example by:
196
197          session required pam_lastlog.so nowtmp
198

HISTORY

200       This su command was derived from coreutils' su, which was based on an
201       implementation by David MacKenzie. The util-linux version has been
202       refactored by Karel Zak.
203

SEE ALSO

205       setpriv(1), login.defs(5), shells(5), pam(8), runuser(1)
206

REPORTING BUGS

208       For bug reports, use the issue tracker at
209       https://github.com/util-linux/util-linux/issues.
210

AVAILABILITY

212       The su command is part of the util-linux package which can be
213       downloaded from Linux Kernel Archive
214       <https://www.kernel.org/pub/linux/utils/util-linux/>.
215
216
217
218util-linux 2.39.2                 2023-06-14                             SU(1)
Impressum