summaryrefslogtreecommitdiffstats
path: root/man/man1/su.1
blob: ebd262931aecf1a6330262b3b4d8b3a78a4d1346 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
'\" t
.\"     Title: su
.\"    Author: Julianne Frances Haugh
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 06/21/2024
.\"    Manual: User Commands
.\"    Source: shadow-utils 4.15.2
.\"  Language: English
.\"
.TH "SU" "1" "06/21/2024" "shadow\-utils 4\&.15\&.2" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
su \- change user ID or become superuser
.SH "SYNOPSIS"
.HP \w'\fBsu\fR\ 'u
\fBsu\fR [\fIoptions\fR] [\fI\-\fR] [\fIusername\fR\ [\ \fIargs\fR\ ]]
.SH "DESCRIPTION"
.PP
The
\fBsu\fR
command is used to become another user during a login session\&. Invoked without a
\fBusername\fR,
\fBsu\fR
defaults to becoming the superuser\&. The
\fB\-\fR
option may be used to provide an environment similar to what the user would expect had the user logged in directly\&. The
\fB\-c\fR
option may be used to treat the next argument as a command by most shells\&.
.PP
Options are recognized everywhere in the argument list\&. You can use the
\fB\-\-\fR
argument to stop option parsing\&. The
\fB\-\fR
option is special: it is also recognized after
\fB\-\-\fR, but has to be placed before
\fBusername\fR\&.
.PP
The user will be prompted for a password, if appropriate\&. Invalid passwords will produce an error message\&. All attempts, both valid and invalid, are logged to detect abuse of the system\&.
.PP
The current environment is passed to the new shell\&. The value of
\fB$PATH\fR
is reset to
/bin:/usr/bin
for normal users, or
/sbin:/bin:/usr/sbin:/usr/bin
for the superuser\&. This may be changed with the
\fBENV_PATH\fR
and
\fBENV_SUPATH\fR
definitions in
/etc/login\&.defs\&.
.PP
A subsystem login is indicated by the presence of a "*" as the first character of the login shell\&. The given home directory will be used as the root of a new file system which the user is actually logged into\&.
.SH "OPTIONS"
.PP
The options which apply to the
\fBsu\fR
command are:
.PP
\fB\-c\fR, \fB\-\-command\fR\ \&\fICOMMAND\fR
.RS 4
Specify a command that will be invoked by the shell using its
\fB\-c\fR\&.
.sp
The executed command will have no controlling terminal\&. This option cannot be used to execute interactive programs which need a controlling TTY\&.
.RE
.PP
\fB\-\fR, \fB\-l\fR, \fB\-\-login\fR
.RS 4
Provide an environment similar to what the user would expect had the user logged in directly\&.
.sp
When
\fB\-\fR
is used, it must be specified before any
\fBusername\fR\&. For portability it is recommended to use it as last option, before any
\fBusername\fR\&. The other forms (\fB\-l\fR
and
\fB\-\-login\fR) do not have this restriction\&.
.RE
.PP
\fB\-s\fR, \fB\-\-shell\fR\ \&\fISHELL\fR
.RS 4
The shell that will be invoked\&.
.sp
The invoked shell is chosen from (highest priority first):
.PP
.RS 4
The shell specified with \-\-shell\&.
.RE
.PP
.RS 4
If
\fB\-\-preserve\-environment\fR
is used, the shell specified by the
\fB$SHELL\fR
environment variable\&.
.RE
.PP
.RS 4
The shell indicated in the
/etc/passwd
entry for the target user\&.
.RE
.PP
.RS 4
/bin/sh
if a shell could not be found by any above method\&.
.RE
.sp
If the target user has a restricted shell (i\&.e\&. the shell field of this user\*(Aqs entry in
/etc/passwd
is not listed in
/etc/shells), then the
\fB\-\-shell\fR
option or the
\fB$SHELL\fR
environment variable won\*(Aqt be taken into account, unless
\fBsu\fR
is called by root\&.
.RE
.PP
\fB\-m\fR, \fB\-p\fR, \fB\-\-preserve\-environment\fR
.RS 4
Preserve the current environment, except for:
.PP
\fB$PATH\fR
.RS 4
reset according to the
/etc/login\&.defs
options
\fBENV_PATH\fR
or
\fBENV_SUPATH\fR
(see below);
.RE
.PP
\fB$IFS\fR
.RS 4
reset to
\(lq<space><tab><newline>\(rq, if it was set\&.
.RE
.sp
If the target user has a restricted shell, this option has no effect (unless
\fBsu\fR
is called by root)\&.
.sp
Note that the default behavior for the environment is the following:
.PP
.RS 4
The
\fB$HOME\fR,
\fB$SHELL\fR,
\fB$USER\fR,
\fB$LOGNAME\fR,
\fB$PATH\fR, and
\fB$IFS\fR
environment variables are reset\&.
.RE
.PP
.RS 4
If
\fB\-\-login\fR
is not used, the environment is copied, except for the variables above\&.
.RE
.PP
.RS 4
If
\fB\-\-login\fR
is used, the
\fB$TERM\fR,
\fB$COLORTERM\fR,
\fB$DISPLAY\fR, and
\fB$XAUTHORITY\fR
environment variables are copied if they were set\&.
.RE
.PP
.RS 4
If
\fB\-\-login\fR
is used, the
\fB$TZ\fR,
\fB$HZ\fR, and
\fB$MAIL\fR
environment variables are set according to the
/etc/login\&.defs
options
\fBENV_TZ\fR,
\fBENV_HZ\fR,
\fBMAIL_DIR\fR, and
\fBMAIL_FILE\fR
(see below)\&.
.RE
.PP
.RS 4
If
\fB\-\-login\fR
is used, other environment variables might be set by the
\fBENVIRON_FILE\fR
file (see below)\&.
.RE
.sp
.RE
.SH "CAVEATS"
.PP
This version of
\fBsu\fR
has many compilation options, only some of which may be in use at any particular site\&.
.SH "CONFIGURATION"
.PP
The following configuration variables in
/etc/login\&.defs
change the behavior of this tool:
.PP
\fBCONSOLE\fR (string)
.RS 4
If defined, either full pathname of a file containing device names (one per line) or a ":" delimited list of device names\&. Root logins will be allowed only upon these devices\&.
.sp
If not defined, root will be allowed on any device\&.
.sp
The device should be specified without the /dev/ prefix\&.
.RE
.PP
\fBCONSOLE_GROUPS\fR (string)
.RS 4
List of groups to add to the user\*(Aqs supplementary groups set when logging in on the console (as determined by the CONSOLE setting)\&. Default is none\&.

Use with caution \- it is possible for users to gain permanent access to these groups, even when not logged in on the console\&.
.RE
.PP
\fBDEFAULT_HOME\fR (boolean)
.RS 4
Indicate if login is allowed if we can\*(Aqt cd to the home directory\&. Default is no\&.
.sp
If set to
\fIyes\fR, the user will login in the root (/) directory if it is not possible to cd to her home directory\&.
.RE
.PP
\fBENV_HZ\fR (string)
.RS 4
If set, it will be used to define the HZ environment variable when a user login\&. The value must be preceded by
\fIHZ=\fR\&. A common value on Linux is
\fIHZ=100\fR\&.
.RE
.PP
\fBENVIRON_FILE\fR (string)
.RS 4
If this file exists and is readable, login environment will be read from it\&. Every line should be in the form name=value\&.
.sp
Lines starting with a # are treated as comment lines and ignored\&.
.RE
.PP
\fBENV_PATH\fR (string)
.RS 4
If set, it will be used to define the PATH environment variable when a regular user login\&. The value is a colon separated list of paths (for example
\fI/bin:/usr/bin\fR) and can be preceded by
\fIPATH=\fR\&. The default value is
\fIPATH=/bin:/usr/bin\fR\&.
.RE
.PP
\fBENV_SUPATH\fR (string)
.RS 4
If set, it will be used to define the PATH environment variable when the superuser login\&. The value is a colon separated list of paths (for example
\fI/sbin:/bin:/usr/sbin:/usr/bin\fR) and can be preceded by
\fIPATH=\fR\&. The default value is
\fIPATH=/sbin:/bin:/usr/sbin:/usr/bin\fR\&.
.RE
.PP
\fBENV_TZ\fR (string)
.RS 4
If set, it will be used to define the TZ environment variable when a user login\&. The value can be the name of a timezone preceded by
\fITZ=\fR
(for example
\fITZ=CST6CDT\fR), or the full path to the file containing the timezone specification (for example
/etc/tzname)\&.
.sp
If a full path is specified but the file does not exist or cannot be read, the default is to use
\fITZ=CST6CDT\fR\&.
.RE
.PP
\fBLOGIN_STRING\fR (string)
.RS 4
The string used for prompting a password\&. The default is to use "Password: ", or a translation of that string\&. If you set this variable, the prompt will not be translated\&.
.sp
If the string contains
\fI%s\fR, this will be replaced by the user\*(Aqs name\&.
.RE
.PP
\fBMAIL_CHECK_ENAB\fR (boolean)
.RS 4
Enable checking and display of mailbox status upon login\&.
.sp
You should disable it if the shell startup files already check for mail ("mailx \-e" or equivalent)\&.
.RE
.PP
\fBMAIL_DIR\fR (string)
.RS 4
The mail spool directory\&. This is needed to manipulate the mailbox when its corresponding user account is modified or deleted\&. If not specified, a compile\-time default is used\&. The parameter CREATE_MAIL_SPOOL in
/etc/default/useradd
determines whether the mail spool should be created\&.
.RE
.PP
\fBMAIL_FILE\fR (string)
.RS 4
Defines the location of the users mail spool files relatively to their home directory\&.
.RE
.PP
The
\fBMAIL_DIR\fR
and
\fBMAIL_FILE\fR
variables are used by
\fBuseradd\fR,
\fBusermod\fR, and
\fBuserdel\fR
to create, move, or delete the user\*(Aqs mail spool\&.
.PP
If
\fBMAIL_CHECK_ENAB\fR
is set to
\fIyes\fR, they are also used to define the
\fBMAIL\fR
environment variable\&.
.PP
\fBQUOTAS_ENAB\fR (boolean)
.RS 4
Enable setting of resource limits from
/etc/limits
and ulimit, umask, and niceness from the user\*(Aqs passwd gecos field\&.
.RE
.PP
\fBSULOG_FILE\fR (string)
.RS 4
If defined, all su activity is logged to this file\&.
.RE
.PP
\fBSU_NAME\fR (string)
.RS 4
If defined, the command name to display when running "su \-"\&. For example, if this is defined as "su" then a "ps" will display the command is "\-su"\&. If not defined, then "ps" would display the name of the shell actually being run, e\&.g\&. something like "\-sh"\&.
.RE
.PP
\fBSU_WHEEL_ONLY\fR (boolean)
.RS 4
If
\fIyes\fR, the user must be listed as a member of the first gid 0 group in
/etc/group
(called
\fIroot\fR
on most Linux systems) to be able to
\fBsu\fR
to uid 0 accounts\&. If the group doesn\*(Aqt exist or is empty, no one will be able to
\fBsu\fR
to uid 0\&.
.RE
.PP
\fBSYSLOG_SU_ENAB\fR (boolean)
.RS 4
Enable "syslog" logging of
\fBsu\fR
activity \- in addition to sulog file logging\&.
.RE
.PP
\fBUSERGROUPS_ENAB\fR (boolean)
.RS 4
Enable setting of the umask group bits to be the same as owner bits (examples: 022 \-> 002, 077 \-> 007) for non\-root users, if the uid is the same as gid, and username is the same as the primary group name\&.
.sp
If set to
\fIyes\fR,
\fBuserdel\fR
will remove the user\*(Aqs group if it contains no more members, and
\fBuseradd\fR
will create by default a group with the name of the user\&.
.RE
.SH "FILES"
.PP
/etc/passwd
.RS 4
User account information\&.
.RE
.PP
/etc/shadow
.RS 4
Secure user account information\&.
.RE
.PP
/etc/login\&.defs
.RS 4
Shadow password suite configuration\&.
.RE
.SH "EXIT VALUES"
.PP
On success,
\fBsu\fR
returns the exit value of the command it executed\&.
.PP
If this command was terminated by a signal,
\fBsu\fR
returns the number of this signal plus 128\&.
.PP
If su has to kill the command (because it was asked to terminate, and the command did not terminate in time),
\fBsu\fR
returns 255\&.
.PP
Some exit values from
\fBsu\fR
are independent from the executed command:
.PP
\fI0\fR
.RS 4
success (\fB\-\-help\fR
only)
.RE
.PP
\fI1\fR
.RS 4
System or authentication failure
.RE
.PP
\fI126\fR
.RS 4
The requested command was not found
.RE
.PP
\fI127\fR
.RS 4
The requested command could not be executed
.RE
.SH "SEE ALSO"
.PP
\fBlogin\fR(1),
\fBlogin.defs\fR(5),
\fBsg\fR(1),
\fBsh\fR(1)\&.