]>
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). | |
118 | ||
119 | This feature is EXPERIMENTAL for now and may be removed in the next releases. | |
120 | ||
04845ec7 | 121 | .TP |
b45413a8 BS |
122 | .BR \-s , " \-\-shell" = \fIshell |
123 | Run the specified \fIshell\fR instead of the default. The shell to run is | |
60541961 | 124 | selected according to the following rules, in order: |
2ab15cb0 LN |
125 | .RS 10 |
126 | .TP | |
127 | o | |
128 | the shell specified with | |
129 | .B \-\-shell | |
130 | .TP | |
131 | o | |
60541961 BS |
132 | the shell specified in the environment variable |
133 | .BR SHELL , | |
2ab15cb0 | 134 | if the |
b06c1ca6 | 135 | .B \-\-preserve\-environment |
60541961 | 136 | option is used |
8d581640 | 137 | .TP |
2ab15cb0 LN |
138 | o |
139 | the shell listed in the passwd entry of the target user | |
8d581640 | 140 | .TP |
2ab15cb0 LN |
141 | o |
142 | /bin/sh | |
143 | .RE | |
144 | .IP | |
145 | If the target user has a restricted shell (i.e. not listed in | |
60541961 | 146 | /etc/shells), the |
2ab15cb0 LN |
147 | .B \-\-shell |
148 | option and the | |
149 | .B SHELL | |
150 | environment variables are ignored unless the calling user is root. | |
151 | .TP | |
b06c1ca6 | 152 | .BI \-\-session\-command= command |
b45413a8 BS |
153 | Same as |
154 | .B \-c | |
155 | but do not create a new session. (Discouraged.) | |
8d581640 | 156 | .TP |
75efef98 KZ |
157 | .BR \-w , " \-\-whitelist\-environment" = \fIlist |
158 | Don't reset environment variables specified in comma separated \fIlist\fR when clears | |
159 | environment for \fB\-\-login\fR. The whitelist is ignored for the environment variables | |
160 | .BR HOME , | |
161 | .BR SHELL , | |
162 | .BR USER , | |
163 | .BR LOGNAME ", and" | |
164 | .BR PATH "." | |
165 | .TP | |
b45413a8 | 166 | .BR \-V , " \-\-version" |
2ab15cb0 | 167 | Display version information and exit. |
b45413a8 BS |
168 | .TP |
169 | .BR \-h , " \-\-help" | |
170 | Display help text and exit. | |
8960f3ae OO |
171 | .SH SIGNALS |
172 | Upon receiving either | |
173 | .BR SIGINT , | |
0bb7e904 | 174 | .B SIGQUIT |
8960f3ae OO |
175 | or |
176 | .BR SIGTERM , | |
0bb7e904 | 177 | .B su |
0dc75983 KZ |
178 | terminates its child and afterwards terminates itself with the received signal. |
179 | The child is terminated by SIGTERM, after unsuccessful attempt and 2 seconds of | |
180 | delay the child is killed by SIGKILL. | |
2ab15cb0 LN |
181 | .SH CONFIG FILES |
182 | .B su | |
183 | reads the | |
184 | .I /etc/default/su | |
185 | and | |
186 | .I /etc/login.defs | |
187 | configuration files. The following configuration items are relevant | |
188 | for | |
189 | .BR su (1): | |
190 | .PP | |
191 | .B FAIL_DELAY | |
192 | (number) | |
193 | .RS 4 | |
2b5e1335 | 194 | Delay in seconds in case of an authentication failure. The number must be |
2ab15cb0 LN |
195 | a non-negative integer. |
196 | .RE | |
197 | .PP | |
198 | .B ENV_PATH | |
199 | (string) | |
200 | .RS 4 | |
201 | Defines the PATH environment variable for a regular user. The | |
202 | default value is | |
203 | .IR /usr/local/bin:\:/bin:\:/usr/bin . | |
204 | .RE | |
205 | .PP | |
206 | .B ENV_ROOTPATH | |
207 | (string) | |
8d581640 | 208 | .br |
2ab15cb0 LN |
209 | .B ENV_SUPATH |
210 | (string) | |
211 | .RS 4 | |
60541961 | 212 | Defines the PATH environment variable for root. The default value is |
2ab15cb0 LN |
213 | .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin . |
214 | .RE | |
215 | .PP | |
216 | .B ALWAYS_SET_PATH | |
217 | (boolean) | |
218 | .RS 4 | |
219 | If set to | |
220 | .I yes | |
221 | and \-\-login and \-\-preserve\-environment were not specified | |
8d581640 | 222 | .B su |
2ab15cb0 LN |
223 | initializes |
224 | .BR PATH . | |
225 | .RE | |
226 | .SH EXIT STATUS | |
227 | .B su | |
228 | normally returns the exit status of the command it executed. If the | |
229 | command was killed by a signal, | |
230 | .B su | |
231 | returns the number of the signal plus 128. | |
8d581640 | 232 | .PP |
2ab15cb0 LN |
233 | Exit status generated by |
234 | .B su | |
235 | itself: | |
236 | .RS 10 | |
8d581640 | 237 | .TP |
2ab15cb0 LN |
238 | 1 |
239 | Generic error before executing the requested command | |
8d581640 | 240 | .TP |
2ab15cb0 LN |
241 | 126 |
242 | The requested command could not be executed | |
8d581640 | 243 | .TP |
2ab15cb0 | 244 | 127 |
2b5e1335 | 245 | The requested command was not found |
8d581640 SK |
246 | .RE |
247 | .SH FILES | |
2ab15cb0 LN |
248 | .PD 0 |
249 | .TP 17 | |
250 | /etc/pam.d/su | |
251 | default PAM configuration file | |
8d581640 | 252 | .TP |
2ab15cb0 LN |
253 | /etc/pam.d/su-l |
254 | PAM configuration file if \-\-login is specified | |
255 | .TP | |
256 | /etc/default/su | |
22b49b33 | 257 | command specific logindef config file |
2ab15cb0 LN |
258 | .TP |
259 | /etc/login.defs | |
22b49b33 | 260 | global logindef config file |
2ab15cb0 | 261 | .PD 1 |
d0c10f7d KZ |
262 | .SH NOTES |
263 | For security reasons | |
264 | .B su | |
265 | always logs failed log-in attempts to the btmp file, but it does not write to | |
266 | the lastlog file at all. This solution allows to control | |
267 | .B su | |
268 | behavior by PAM configuration. If you want to use the pam_lastlog module to | |
269 | print warning message about failed log-in attempts then the pam_lastlog has to | |
2b5e1335 | 270 | be configured to update the lastlog file as well. For example by: |
d0c10f7d KZ |
271 | |
272 | .RS | |
273 | .br | |
274 | session required pam_lastlog.so nowtmp | |
275 | .RE | |
8d581640 | 276 | .SH "SEE ALSO" |
c424fd83 | 277 | .BR setpriv (1), |
f053ff1e | 278 | .BR login.defs (5), |
2ab15cb0 | 279 | .BR shells (5), |
f053ff1e MK |
280 | .BR pam (8), |
281 | .BR runuser (8) | |
b45413a8 BS |
282 | .SH HISTORY |
283 | This \fBsu\fR command was | |
284 | derived from coreutils' \fBsu\fR, which was based on an implementation by | |
6461eeec | 285 | David MacKenzie. The util-linux has been refactored by Karel Zak. |
8d581640 | 286 | .SH AVAILABILITY |
22b49b33 | 287 | The su command is part of the util-linux package and is |
8d581640 | 288 | available from |
d673b74e | 289 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
8d581640 SK |
290 | Linux Kernel Archive |
291 | .UE . |