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