]>
Commit | Line | Data |
---|---|---|
2ab15cb0 | 1 | .TH SU "1" "June 2012" "util-linux" "User Commands" |
8d581640 | 2 | .SH NAME |
2ab15cb0 | 3 | su \- run a command with substitute user and group ID |
8d581640 SK |
4 | .SH SYNOPSIS |
5 | .B su | |
2ab15cb0 | 6 | [options...] [\-] [user [args...]] |
8d581640 SK |
7 | .SH DESCRIPTION |
8 | .B su | |
2ab15cb0 | 9 | allows to run commands with substitute user and group ID. |
8d581640 | 10 | .PP |
2ab15cb0 | 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 |
22b49b33 | 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 | |
31 | option (instead it's shortcut | |
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 |
2ab15cb0 LN |
40 | implementations such as e.g. support of a wheel group have to be |
41 | configured via PAM. | |
8d581640 SK |
42 | .SH OPTIONS |
43 | .TP | |
2ab15cb0 LN |
44 | \fB\-c\fR \fIcommand\fR, \fB\-\-command\fR=\fIcommand\fR |
45 | Pass | |
46 | .I command | |
47 | to the shell with the | |
48 | .B \-c | |
49 | option. | |
50 | .TP | |
51 | \fB\-\-session\-command\fR=\fIcommand\fR | |
52 | Same as | |
53 | .B \-c | |
54 | but do not create a new session (discouraged). | |
8d581640 SK |
55 | .TP |
56 | \fB\-f\fR, \fB\-\-fast\fR | |
2ab15cb0 LN |
57 | Pass |
58 | .B \-f | |
59 | to the shell which may or may not be useful depending on the | |
60 | shell. | |
8d581640 | 61 | .TP |
8528ea2f KZ |
62 | \fB\-g\fR, \fB\-\-group\fR=\fIgroup\fR\fR |
63 | specify the primary group, this option is allowed for root user only | |
64 | .TP | |
65 | \fB\-G\fR, \fB\-\-supp-group\fR=\fIgroup\fR\fR | |
66 | specify a supplemental group, this option is allowed for root user only | |
67 | .TP | |
8d581640 | 68 | \fB\-\fR, \fB\-l\fR, \fB\-\-login\fR |
2ab15cb0 LN |
69 | Starts the shell as login shell with an environment similar to a real |
70 | login: | |
71 | .RS 10 | |
8d581640 | 72 | .TP |
2ab15cb0 LN |
73 | o |
74 | clears all environment variables except for | |
75 | .B TERM | |
76 | .TP | |
77 | o | |
78 | initializes the environment variables | |
79 | .BR HOME , | |
80 | .BR SHELL , | |
81 | .BR USER , | |
82 | .BR LOGNAME , | |
83 | .B PATH | |
84 | .TP | |
85 | o | |
86 | changes to the target user's home directory | |
87 | .TP | |
88 | o | |
89 | sets argv[0] of the shell to | |
90 | .RB ' \- ' | |
91 | in order to make the shell a login shell | |
92 | .RE | |
93 | .TP | |
94 | \fB\-m\fR, \fB\-p\fR, \fB\-\-preserve-environment\fR | |
95 | Preserves the whole environment, ie does not set | |
96 | .BR HOME , | |
97 | .BR SHELL , | |
98 | .B USER | |
99 | nor | |
100 | .BR LOGNAME . | |
3e5c0a2d | 101 | The option is ignored if the option \fB\-\-login\fR is specified. |
2ab15cb0 LN |
102 | .TP |
103 | \fB\-s\fR \fISHELL\fR, \fB\-\-shell\fR=\fISHELL\fR | |
104 | Runs the specified shell instead of the default. The shell to run is | |
105 | selected according to the following rules in order: | |
106 | .RS 10 | |
107 | .TP | |
108 | o | |
109 | the shell specified with | |
110 | .B \-\-shell | |
111 | .TP | |
112 | o | |
113 | The shell specified in the environment variable | |
114 | .B SHELL | |
115 | if the | |
116 | .B \-\-preserve-environment | |
117 | option is used. | |
8d581640 | 118 | .TP |
2ab15cb0 LN |
119 | o |
120 | the shell listed in the passwd entry of the target user | |
8d581640 | 121 | .TP |
2ab15cb0 LN |
122 | o |
123 | /bin/sh | |
124 | .RE | |
125 | .IP | |
126 | If the target user has a restricted shell (i.e. not listed in | |
127 | /etc/shells) the | |
128 | .B \-\-shell | |
129 | option and the | |
130 | .B SHELL | |
131 | environment variables are ignored unless the calling user is root. | |
132 | .TP | |
133 | \fB\-\-help\fR | |
134 | Display help text and exit. | |
8d581640 | 135 | .TP |
2ab15cb0 LN |
136 | \fB\-\-version\fR |
137 | Display version information and exit. | |
138 | .SH CONFIG FILES | |
139 | .B su | |
140 | reads the | |
141 | .I /etc/default/su | |
142 | and | |
143 | .I /etc/login.defs | |
144 | configuration files. The following configuration items are relevant | |
145 | for | |
146 | .BR su (1): | |
147 | .PP | |
148 | .B FAIL_DELAY | |
149 | (number) | |
150 | .RS 4 | |
151 | Delay in seconds in case of authentication failure. Number must be | |
152 | a non-negative integer. | |
153 | .RE | |
154 | .PP | |
155 | .B ENV_PATH | |
156 | (string) | |
157 | .RS 4 | |
158 | Defines the PATH environment variable for a regular user. The | |
159 | default value is | |
160 | .IR /usr/local/bin:\:/bin:\:/usr/bin . | |
161 | .RE | |
162 | .PP | |
163 | .B ENV_ROOTPATH | |
164 | (string) | |
8d581640 | 165 | .br |
2ab15cb0 LN |
166 | .B ENV_SUPATH |
167 | (string) | |
168 | .RS 4 | |
169 | Defines the PATH environment variable for root. The default value is | |
170 | .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin . | |
171 | .RE | |
172 | .PP | |
173 | .B ALWAYS_SET_PATH | |
174 | (boolean) | |
175 | .RS 4 | |
176 | If set to | |
177 | .I yes | |
178 | and \-\-login and \-\-preserve\-environment were not specified | |
8d581640 | 179 | .B su |
2ab15cb0 LN |
180 | initializes |
181 | .BR PATH . | |
182 | .RE | |
183 | .SH EXIT STATUS | |
184 | .B su | |
185 | normally returns the exit status of the command it executed. If the | |
186 | command was killed by a signal, | |
187 | .B su | |
188 | returns the number of the signal plus 128. | |
8d581640 | 189 | .PP |
2ab15cb0 LN |
190 | Exit status generated by |
191 | .B su | |
192 | itself: | |
193 | .RS 10 | |
8d581640 | 194 | .TP |
2ab15cb0 LN |
195 | 1 |
196 | Generic error before executing the requested command | |
8d581640 | 197 | .TP |
2ab15cb0 LN |
198 | 126 |
199 | The requested command could not be executed | |
8d581640 | 200 | .TP |
2ab15cb0 LN |
201 | 127 |
202 | The requested command could was not found | |
8d581640 SK |
203 | .RE |
204 | .SH FILES | |
2ab15cb0 LN |
205 | .PD 0 |
206 | .TP 17 | |
207 | /etc/pam.d/su | |
208 | default PAM configuration file | |
8d581640 | 209 | .TP |
2ab15cb0 LN |
210 | /etc/pam.d/su-l |
211 | PAM configuration file if \-\-login is specified | |
212 | .TP | |
213 | /etc/default/su | |
22b49b33 | 214 | command specific logindef config file |
2ab15cb0 LN |
215 | .TP |
216 | /etc/login.defs | |
22b49b33 | 217 | global logindef config file |
2ab15cb0 | 218 | .PD 1 |
8d581640 | 219 | .SH "SEE ALSO" |
7a7f9d38 | 220 | .BR runuser (8), |
2ab15cb0 LN |
221 | .BR pam (8), |
222 | .BR shells (5), | |
22b49b33 | 223 | .BR login.defs (5) |
2ab15cb0 | 224 | .SH AUTHOR |
22b49b33 | 225 | Derived from coreutils' su which was based on an implementation from |
2ab15cb0 | 226 | David MacKenzie. |
8d581640 | 227 | .SH AVAILABILITY |
22b49b33 | 228 | The su command is part of the util-linux package and is |
8d581640 SK |
229 | available from |
230 | .UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ | |
231 | Linux Kernel Archive | |
232 | .UE . |