]>
Commit | Line | Data |
---|---|---|
b45413a8 | 1 | .TH SU 1 "July 2014" "util-linux" "User Commands" |
8d581640 | 2 | .SH NAME |
2ab15cb0 | 3 | su \- run a command with substitute user and group ID |
8d581640 | 4 | .SH SYNOPSIS |
b45413a8 | 5 | .BR su " [options] [" \- ] |
60541961 | 6 | .RI [ user " [" argument ...]] |
8d581640 SK |
7 | .SH DESCRIPTION |
8 | .B su | |
60541961 | 9 | allows to run commands with a substitute user and group ID. |
8d581640 | 10 | .PP |
1ffc4f7d | 11 | When called with no |
2fb684f0 | 12 | .I user |
1ffc4f7d | 13 | specified, |
8d581640 | 14 | .B su |
2ab15cb0 LN |
15 | defaults to running an interactive shell as |
16 | .IR root . | |
1ffc4f7d | 17 | When |
2fb684f0 | 18 | .I user |
ebaf1d55 MT |
19 | is specified, additional |
20 | .IR argument s | |
21 | can be supplied, in which case they are passed to the shell. | |
8d581640 | 22 | .PP |
b45413a8 | 23 | For backward compatibility, |
8d581640 | 24 | .B su |
2ab15cb0 | 25 | defaults to not change the current directory and to only set the |
7007991f | 26 | environment variables |
2ab15cb0 LN |
27 | .B HOME |
28 | and | |
29 | .B SHELL | |
30 | (plus | |
31 | .B USER | |
32 | and | |
33 | .B LOGNAME | |
34 | if the target | |
35 | .I user | |
36 | is not root). It is recommended to always use the | |
37 | .B \-\-login | |
60541961 | 38 | option (instead of its shortcut |
2ab15cb0 LN |
39 | .BR \- ) |
40 | to avoid side effects caused by mixing environments. | |
8d581640 | 41 | .PP |
2ab15cb0 | 42 | This version of |
8d581640 | 43 | .B su |
2ab15cb0 LN |
44 | uses PAM for authentication, account and session management. Some |
45 | configuration options found in other | |
8d581640 | 46 | .B su |
2b5e1335 | 47 | implementations, such as support for a wheel group, have to be |
2ab15cb0 | 48 | configured via PAM. |
c424fd83 KZ |
49 | .PP |
50 | .B su | |
51 | is mostly designed for unprivileged users, the recommended solution for | |
eb024893 | 52 | privileged users (e.g., scripts executed by root) is to use |
aedd46f6 | 53 | non-set-user-ID command |
c424fd83 KZ |
54 | .BR runuser (1) |
55 | that does not require authentication and provide separate PAM configuration. If | |
56 | the PAM session is not required at all then the recommend solution is to use | |
57 | command | |
58 | .BR setpriv (1). | |
57b9d60c KZ |
59 | .PP |
60 | Note that | |
61 | .B su | |
62 | in all cases use PAM (pam_getenvlist()) to do final environment modification. The command line options | |
63 | like \fB\-\-login\fR or \fB\-\-preserve\-environment\fR affect environment before it's modified by PAM. | |
c424fd83 | 64 | |
8d581640 SK |
65 | .SH OPTIONS |
66 | .TP | |
b45413a8 | 67 | .BR \-c , " \-\-command" = \fIcommand |
2ab15cb0 LN |
68 | Pass |
69 | .I command | |
70 | to the shell with the | |
71 | .B \-c | |
72 | option. | |
73 | .TP | |
b45413a8 | 74 | .BR \-f , " \-\-fast" |
2ab15cb0 LN |
75 | Pass |
76 | .B \-f | |
60541961 | 77 | to the shell, which may or may not be useful, depending on the shell. |
8d581640 | 78 | .TP |
b45413a8 | 79 | .BR \-g , " \-\-group" = \fIgroup |
2b5e1335 | 80 | Specify the primary group. This option is available to the root user only. |
8528ea2f | 81 | .TP |
b06c1ca6 | 82 | .BR \-G , " \-\-supp\-group" = \fIgroup |
c619d3d1 KZ |
83 | Specify a supplemental group. This option is available to the root user only. The first specified |
84 | supplementary group is also used as a primary group if the option \fB\-\-group\fR is unspecified. | |
8528ea2f | 85 | .TP |
b45413a8 BS |
86 | .BR \- , " \-l" , " \-\-login" |
87 | Start the shell as a login shell with an environment similar to a real | |
2ab15cb0 LN |
88 | login: |
89 | .RS 10 | |
8d581640 | 90 | .TP |
2ab15cb0 | 91 | o |
2b5e1335 | 92 | clears all the environment variables except |
2ab15cb0 | 93 | .B TERM |
75efef98 | 94 | and variables specified by \fB\-\-whitelist\-environment\fR |
2ab15cb0 LN |
95 | .TP |
96 | o | |
97 | initializes the environment variables | |
98 | .BR HOME , | |
99 | .BR SHELL , | |
100 | .BR USER , | |
60541961 | 101 | .BR LOGNAME ", and" |
2ab15cb0 LN |
102 | .B PATH |
103 | .TP | |
104 | o | |
105 | changes to the target user's home directory | |
106 | .TP | |
107 | o | |
108 | sets argv[0] of the shell to | |
109 | .RB ' \- ' | |
110 | in order to make the shell a login shell | |
111 | .RE | |
112 | .TP | |
b06c1ca6 | 113 | .BR \-m , " \-p" , " \-\-preserve\-environment" |
eb024893 | 114 | Preserve the entire environment, i.e., it does not set |
2ab15cb0 LN |
115 | .BR HOME , |
116 | .BR SHELL , | |
117 | .B USER | |
118 | nor | |
119 | .BR LOGNAME . | |
60541961 | 120 | This option is ignored if the option \fB\-\-login\fR is specified. |
2ab15cb0 | 121 | .TP |
04845ec7 | 122 | .BR \-P , " \-\-pty" |
6461eeec KZ |
123 | Create pseudo-terminal for the session. The independent terminal provides |
124 | better security as user does not share terminal with the original | |
125 | session. This allow to avoid TIOCSTI ioctl terminal injection and another | |
126 | security attacks against terminal file descriptors. The all session is also | |
eb024893 | 127 | possible to move to background (e.g., "su \-\-pty \- username \-c |
6461eeec KZ |
128 | application &"). If the pseudo-terminal is enabled then su command works |
129 | as a proxy between the sessions (copy stdin and stdout). | |
64a87be1 KZ |
130 | .sp |
131 | This feature is mostly designed for interactive sessions. If the standard input | |
eb024893 | 132 | is not a terminal, but for example pipe (e.g., echo "date" | su --pty) than ECHO |
64a87be1 | 133 | flag for the pseudo-terminal is disabled to avoid messy output. |
04845ec7 | 134 | .TP |
b45413a8 BS |
135 | .BR \-s , " \-\-shell" = \fIshell |
136 | Run the specified \fIshell\fR instead of the default. The shell to run is | |
60541961 | 137 | selected according to the following rules, in order: |
2ab15cb0 LN |
138 | .RS 10 |
139 | .TP | |
140 | o | |
141 | the shell specified with | |
142 | .B \-\-shell | |
143 | .TP | |
144 | o | |
60541961 BS |
145 | the shell specified in the environment variable |
146 | .BR SHELL , | |
2ab15cb0 | 147 | if the |
b06c1ca6 | 148 | .B \-\-preserve\-environment |
60541961 | 149 | option is used |
8d581640 | 150 | .TP |
2ab15cb0 LN |
151 | o |
152 | the shell listed in the passwd entry of the target user | |
8d581640 | 153 | .TP |
2ab15cb0 LN |
154 | o |
155 | /bin/sh | |
156 | .RE | |
157 | .IP | |
eb024893 | 158 | If the target user has a restricted shell (i.e., not listed in |
60541961 | 159 | /etc/shells), the |
2ab15cb0 LN |
160 | .B \-\-shell |
161 | option and the | |
162 | .B SHELL | |
163 | environment variables are ignored unless the calling user is root. | |
164 | .TP | |
b06c1ca6 | 165 | .BI \-\-session\-command= command |
b45413a8 BS |
166 | Same as |
167 | .B \-c | |
168 | but do not create a new session. (Discouraged.) | |
8d581640 | 169 | .TP |
75efef98 KZ |
170 | .BR \-w , " \-\-whitelist\-environment" = \fIlist |
171 | Don't reset environment variables specified in comma separated \fIlist\fR when clears | |
172 | environment for \fB\-\-login\fR. The whitelist is ignored for the environment variables | |
173 | .BR HOME , | |
174 | .BR SHELL , | |
175 | .BR USER , | |
176 | .BR LOGNAME ", and" | |
177 | .BR PATH "." | |
178 | .TP | |
b45413a8 | 179 | .BR \-V , " \-\-version" |
2ab15cb0 | 180 | Display version information and exit. |
b45413a8 BS |
181 | .TP |
182 | .BR \-h , " \-\-help" | |
183 | Display help text and exit. | |
8960f3ae OO |
184 | .SH SIGNALS |
185 | Upon receiving either | |
186 | .BR SIGINT , | |
0bb7e904 | 187 | .B SIGQUIT |
8960f3ae OO |
188 | or |
189 | .BR SIGTERM , | |
0bb7e904 | 190 | .B su |
0dc75983 KZ |
191 | terminates its child and afterwards terminates itself with the received signal. |
192 | The child is terminated by SIGTERM, after unsuccessful attempt and 2 seconds of | |
193 | delay the child is killed by SIGKILL. | |
2ab15cb0 LN |
194 | .SH CONFIG FILES |
195 | .B su | |
196 | reads the | |
197 | .I /etc/default/su | |
198 | and | |
199 | .I /etc/login.defs | |
200 | configuration files. The following configuration items are relevant | |
201 | for | |
202 | .BR su (1): | |
203 | .PP | |
204 | .B FAIL_DELAY | |
205 | (number) | |
206 | .RS 4 | |
2b5e1335 | 207 | Delay in seconds in case of an authentication failure. The number must be |
2ab15cb0 LN |
208 | a non-negative integer. |
209 | .RE | |
210 | .PP | |
211 | .B ENV_PATH | |
212 | (string) | |
213 | .RS 4 | |
214 | Defines the PATH environment variable for a regular user. The | |
215 | default value is | |
216 | .IR /usr/local/bin:\:/bin:\:/usr/bin . | |
217 | .RE | |
218 | .PP | |
219 | .B ENV_ROOTPATH | |
220 | (string) | |
8d581640 | 221 | .br |
2ab15cb0 LN |
222 | .B ENV_SUPATH |
223 | (string) | |
224 | .RS 4 | |
86f42e5a | 225 | Defines the PATH environment variable for root. ENV_SUPATH takes precedence. The default value is |
2ab15cb0 LN |
226 | .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin . |
227 | .RE | |
228 | .PP | |
229 | .B ALWAYS_SET_PATH | |
230 | (boolean) | |
231 | .RS 4 | |
232 | If set to | |
233 | .I yes | |
234 | and \-\-login and \-\-preserve\-environment were not specified | |
8d581640 | 235 | .B su |
2ab15cb0 LN |
236 | initializes |
237 | .BR PATH . | |
238 | .RE | |
64d11d6b KZ |
239 | .sp |
240 | The environment variable PATH may be different on systems where /bin and /sbin | |
57b9d60c KZ |
241 | are merged into /usr, this variable is also affected by \fB\-\-login\fR command line option and |
242 | PAM system setting (e.g. pam_env). | |
2ab15cb0 LN |
243 | .SH EXIT STATUS |
244 | .B su | |
245 | normally returns the exit status of the command it executed. If the | |
246 | command was killed by a signal, | |
247 | .B su | |
248 | returns the number of the signal plus 128. | |
8d581640 | 249 | .PP |
2ab15cb0 LN |
250 | Exit status generated by |
251 | .B su | |
252 | itself: | |
253 | .RS 10 | |
8d581640 | 254 | .TP |
2ab15cb0 LN |
255 | 1 |
256 | Generic error before executing the requested command | |
8d581640 | 257 | .TP |
2ab15cb0 LN |
258 | 126 |
259 | The requested command could not be executed | |
8d581640 | 260 | .TP |
2ab15cb0 | 261 | 127 |
2b5e1335 | 262 | The requested command was not found |
8d581640 SK |
263 | .RE |
264 | .SH FILES | |
2ab15cb0 LN |
265 | .PD 0 |
266 | .TP 17 | |
267 | /etc/pam.d/su | |
268 | default PAM configuration file | |
8d581640 | 269 | .TP |
2ab15cb0 LN |
270 | /etc/pam.d/su-l |
271 | PAM configuration file if \-\-login is specified | |
272 | .TP | |
273 | /etc/default/su | |
22b49b33 | 274 | command specific logindef config file |
2ab15cb0 LN |
275 | .TP |
276 | /etc/login.defs | |
22b49b33 | 277 | global logindef config file |
2ab15cb0 | 278 | .PD 1 |
d0c10f7d KZ |
279 | .SH NOTES |
280 | For security reasons | |
281 | .B su | |
282 | always logs failed log-in attempts to the btmp file, but it does not write to | |
283 | the lastlog file at all. This solution allows to control | |
284 | .B su | |
285 | behavior by PAM configuration. If you want to use the pam_lastlog module to | |
286 | print warning message about failed log-in attempts then the pam_lastlog has to | |
2b5e1335 | 287 | be configured to update the lastlog file as well. For example by: |
d0c10f7d KZ |
288 | |
289 | .RS | |
290 | .br | |
291 | session required pam_lastlog.so nowtmp | |
292 | .RE | |
5a829806 | 293 | .SH SEE ALSO |
c424fd83 | 294 | .BR setpriv (1), |
f053ff1e | 295 | .BR login.defs (5), |
2ab15cb0 | 296 | .BR shells (5), |
f053ff1e | 297 | .BR pam (8), |
2e028ccc | 298 | .BR runuser (1) |
b45413a8 BS |
299 | .SH HISTORY |
300 | This \fBsu\fR command was | |
301 | derived from coreutils' \fBsu\fR, which was based on an implementation by | |
6461eeec | 302 | David MacKenzie. The util-linux has been refactored by Karel Zak. |
8d581640 | 303 | .SH AVAILABILITY |
22b49b33 | 304 | The su command is part of the util-linux package and is |
8d581640 | 305 | available from |
d673b74e | 306 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
8d581640 SK |
307 | Linux Kernel Archive |
308 | .UE . |