]>
Commit | Line | Data |
---|---|---|
b45413a8 | 1 | .TH RUNUSER 1 "July 2014" "util-linux" "User Commands" |
7ec6adb1 KZ |
2 | .SH NAME |
3 | runuser \- run a command with substitute user and group ID | |
4 | .SH SYNOPSIS | |
b45413a8 BS |
5 | .BR runuser " [options] " \-u |
6 | .I user | |
281873b8 | 7 | .RI "[[\-\-] " command " ["argument "...]]" |
7a7f9d38 | 8 | .LP |
b45413a8 BS |
9 | .BR runuser " [options] [" \- ] |
10 | .RI [ user " [" argument "...]]" | |
7ec6adb1 KZ |
11 | .SH DESCRIPTION |
12 | .B runuser | |
b45413a8 BS |
13 | allows to run commands with a substitute user and group ID. |
14 | If the option \fB\-u\fR is not given, it falls back to | |
15 | .BR su -compatible | |
16 | semantics and a shell is executed. | |
7ec6adb1 KZ |
17 | The difference between the commands |
18 | .B runuser | |
19 | and | |
20 | .B su | |
21 | is that | |
22 | .B runuser | |
96b65fb3 | 23 | does not ask for a password (because it may be executed by the root user only) and |
4f2c0b2d | 24 | it uses a different PAM configuration. |
7ec6adb1 KZ |
25 | The command |
26 | .B runuser | |
aedd46f6 | 27 | does not have to be installed with set-user-ID permissions. |
7ec6adb1 | 28 | .PP |
c424fd83 KZ |
29 | If the PAM session is not required then recommended solution is to use |
30 | .BR setpriv (1) | |
31 | command. | |
32 | .PP | |
96b65fb3 | 33 | When called without arguments, |
7ec6adb1 KZ |
34 | .B runuser |
35 | defaults to running an interactive shell as | |
36 | .IR root . | |
37 | .PP | |
b45413a8 | 38 | For backward compatibility, |
7ec6adb1 KZ |
39 | .B runuser |
40 | defaults to not change the current directory and to only set the | |
41 | environment variables | |
42 | .B HOME | |
43 | and | |
44 | .B SHELL | |
45 | (plus | |
46 | .B USER | |
47 | and | |
48 | .B LOGNAME | |
49 | if the target | |
50 | .I user | |
7a7f9d38 | 51 | is not root). |
7ec6adb1 KZ |
52 | This version of |
53 | .B runuser | |
54 | uses PAM for session management. | |
55 | .SH OPTIONS | |
56 | .TP | |
b45413a8 | 57 | .BR \-c , " \-\-command" = \fIcommand |
7ec6adb1 KZ |
58 | Pass |
59 | .I command | |
60 | to the shell with the | |
61 | .B \-c | |
62 | option. | |
63 | .TP | |
b45413a8 | 64 | .BR \-f , " \-\-fast" |
7ec6adb1 KZ |
65 | Pass |
66 | .B \-f | |
96b65fb3 | 67 | to the shell, which may or may not be useful depending on the |
7ec6adb1 KZ |
68 | shell. |
69 | .TP | |
b45413a8 BS |
70 | .BR \-g , " \-\-group" = \fIgroup |
71 | The primary group to be used. This option is allowed for the root user only. | |
7ec6adb1 | 72 | .TP |
b06c1ca6 | 73 | .BR \-G , " \-\-supp\-group" = \fIgroup |
c619d3d1 KZ |
74 | Specify a supplemental group. This option is available to the root user only. The first specified |
75 | supplementary group is also used as a primary group if the option \fB\-\-group\fR is unspecified. | |
7ec6adb1 | 76 | .TP |
b45413a8 BS |
77 | .BR \- , " \-l" , " \-\-login" |
78 | Start the shell as a login shell with an environment similar to a real | |
7ec6adb1 KZ |
79 | login: |
80 | .RS 10 | |
81 | .TP | |
82 | o | |
96b65fb3 | 83 | clears all the environment variables except for |
7ec6adb1 | 84 | .B TERM |
75efef98 | 85 | and variables specified by \fB\-\-whitelist\-environment\fR |
7ec6adb1 KZ |
86 | .TP |
87 | o | |
88 | initializes the environment variables | |
89 | .BR HOME , | |
90 | .BR SHELL , | |
91 | .BR USER , | |
92 | .BR LOGNAME , | |
93 | .B PATH | |
94 | .TP | |
95 | o | |
96 | changes to the target user's home directory | |
97 | .TP | |
98 | o | |
99 | sets argv[0] of the shell to | |
100 | .RB ' \- ' | |
101 | in order to make the shell a login shell | |
102 | .RE | |
103 | .TP | |
0b07e268 KZ |
104 | .BR \-P , " \-\-pty" |
105 | Create pseudo-terminal for the session. The independent terminal provides | |
106 | better security as user does not share terminal with the original | |
107 | session. This allow to avoid TIOCSTI ioctl terminal injection and another | |
108 | security attacks against terminal file descriptors. The all session is also | |
109 | possible to move to background (e.g. "runuser --pty -u username -- command &"). | |
110 | If the pseudo-terminal is enabled then runuser command works | |
111 | as a proxy between the sessions (copy stdin and stdout). | |
112 | .TP | |
b06c1ca6 | 113 | .BR \-m , " \-p" , " \-\-preserve\-environment" |
b45413a8 | 114 | Preserve the entire environment, i.e. it does not set |
7ec6adb1 KZ |
115 | .BR HOME , |
116 | .BR SHELL , | |
117 | .B USER | |
118 | nor | |
119 | .BR LOGNAME . | |
9ba27b26 | 120 | The option is ignored if the option \fB\-\-login\fR is specified. |
7ec6adb1 | 121 | .TP |
b45413a8 BS |
122 | .BR \-s , " \-\-shell" = \fIshell |
123 | Run the specified \fIshell\fR instead of the default. The shell to run is | |
124 | selected according to the following rules, in order: | |
7ec6adb1 KZ |
125 | .RS 10 |
126 | .TP | |
127 | o | |
128 | the shell specified with | |
129 | .B \-\-shell | |
130 | .TP | |
131 | o | |
b45413a8 | 132 | the shell specified in the environment variable |
7ec6adb1 KZ |
133 | .B SHELL |
134 | if the | |
b06c1ca6 | 135 | .B \-\-preserve\-environment |
b45413a8 | 136 | option is used |
7ec6adb1 KZ |
137 | .TP |
138 | o | |
139 | the shell listed in the passwd entry of the target user | |
140 | .TP | |
141 | o | |
142 | /bin/sh | |
143 | .RE | |
144 | .IP | |
145 | If the target user has a restricted shell (i.e. not listed in | |
146 | /etc/shells) the | |
147 | .B \-\-shell | |
148 | option and the | |
149 | .B SHELL | |
150 | environment variables are ignored unless the calling user is root. | |
151 | .TP | |
b45413a8 BS |
152 | .BI \-\-session\-command= command |
153 | Same as | |
154 | .B \-c , | |
155 | but do not create a new session. (Discouraged.) | |
7ec6adb1 | 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" |
7ec6adb1 | 167 | Display version information and exit. |
b45413a8 BS |
168 | .TP |
169 | .BR \-h , " \-\-help" | |
170 | Display help text and exit. | |
7ec6adb1 KZ |
171 | .SH CONFIG FILES |
172 | .B runuser | |
173 | reads the | |
174 | .I /etc/default/runuser | |
175 | and | |
176 | .I /etc/login.defs | |
177 | configuration files. The following configuration items are relevant | |
178 | for | |
179 | .BR runuser : | |
180 | .PP | |
181 | .B ENV_PATH | |
182 | (string) | |
183 | .RS 4 | |
184 | Defines the PATH environment variable for a regular user. The | |
185 | default value is | |
186 | .IR /usr/local/bin:\:/bin:\:/usr/bin . | |
187 | .RE | |
188 | .PP | |
189 | .B ENV_ROOTPATH | |
190 | (string) | |
191 | .br | |
192 | .B ENV_SUPATH | |
193 | (string) | |
194 | .RS 4 | |
86f42e5a | 195 | Defines the PATH environment variable for root. ENV_SUPATH takes precedence. The default value is |
7ec6adb1 KZ |
196 | .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin . |
197 | .RE | |
198 | .PP | |
199 | .B ALWAYS_SET_PATH | |
200 | (boolean) | |
201 | .RS 4 | |
202 | If set to | |
203 | .I yes | |
204 | and \-\-login and \-\-preserve\-environment were not specified | |
205 | .B runuser | |
206 | initializes | |
207 | .BR PATH . | |
208 | .RE | |
64d11d6b KZ |
209 | .sp |
210 | The environment variable PATH may be different on systems where /bin and /sbin | |
211 | are merged into /usr. | |
7ec6adb1 KZ |
212 | .SH EXIT STATUS |
213 | .B runuser | |
214 | normally returns the exit status of the command it executed. If the | |
215 | command was killed by a signal, | |
216 | .B runuser | |
217 | returns the number of the signal plus 128. | |
218 | .PP | |
219 | Exit status generated by | |
220 | .B runuser | |
221 | itself: | |
222 | .RS 10 | |
223 | .TP | |
224 | 1 | |
225 | Generic error before executing the requested command | |
226 | .TP | |
227 | 126 | |
228 | The requested command could not be executed | |
229 | .TP | |
230 | 127 | |
96b65fb3 | 231 | The requested command was not found |
7ec6adb1 KZ |
232 | .RE |
233 | .SH FILES | |
234 | .PD 0 | |
235 | .TP 17 | |
236 | /etc/pam.d/runuser | |
237 | default PAM configuration file | |
238 | .TP | |
239 | /etc/pam.d/runuser-l | |
240 | PAM configuration file if \-\-login is specified | |
241 | .TP | |
242 | /etc/default/runuser | |
243 | runuser specific logindef config file | |
244 | .TP | |
245 | /etc/login.defs | |
246 | global logindef config file | |
247 | .PD 1 | |
248 | .SH "SEE ALSO" | |
f053ff1e | 249 | .BR setpriv (1), |
c424fd83 | 250 | .BR su (1), |
f053ff1e MK |
251 | .BR login.defs (5), |
252 | .BR shells (5), | |
253 | .BR pam (8) | |
b45413a8 BS |
254 | .SH HISTORY |
255 | This \fB runuser\fR command was | |
a55f60a1 | 256 | derived from coreutils' \fBsu\fR, which was based on an implementation by |
b45413a8 | 257 | David MacKenzie, and the Fedora \fBrunuser\fR command by Dan Walsh. |
7ec6adb1 KZ |
258 | .SH AVAILABILITY |
259 | The runuser command is part of the util-linux package and is | |
260 | available from | |
d673b74e | 261 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
7ec6adb1 KZ |
262 | Linux Kernel Archive |
263 | .UE . |