]>
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). | |
64a87be1 KZ |
112 | .sp |
113 | This feature is mostly designed for interactive sessions. If the standard input | |
114 | is not a terminal, but for example pipe (e.g. echo "date" | runuser --pty -u user) | |
115 | than ECHO flag for the pseudo-terminal is disabled to avoid messy output. | |
0b07e268 | 116 | .TP |
b06c1ca6 | 117 | .BR \-m , " \-p" , " \-\-preserve\-environment" |
b45413a8 | 118 | Preserve the entire environment, i.e. it does not set |
7ec6adb1 KZ |
119 | .BR HOME , |
120 | .BR SHELL , | |
121 | .B USER | |
122 | nor | |
123 | .BR LOGNAME . | |
9ba27b26 | 124 | The option is ignored if the option \fB\-\-login\fR is specified. |
7ec6adb1 | 125 | .TP |
b45413a8 BS |
126 | .BR \-s , " \-\-shell" = \fIshell |
127 | Run the specified \fIshell\fR instead of the default. The shell to run is | |
128 | selected according to the following rules, in order: | |
7ec6adb1 KZ |
129 | .RS 10 |
130 | .TP | |
131 | o | |
132 | the shell specified with | |
133 | .B \-\-shell | |
134 | .TP | |
135 | o | |
b45413a8 | 136 | the shell specified in the environment variable |
7ec6adb1 KZ |
137 | .B SHELL |
138 | if the | |
b06c1ca6 | 139 | .B \-\-preserve\-environment |
b45413a8 | 140 | option is used |
7ec6adb1 KZ |
141 | .TP |
142 | o | |
143 | the shell listed in the passwd entry of the target user | |
144 | .TP | |
145 | o | |
146 | /bin/sh | |
147 | .RE | |
148 | .IP | |
149 | If the target user has a restricted shell (i.e. not listed in | |
150 | /etc/shells) the | |
151 | .B \-\-shell | |
152 | option and the | |
153 | .B SHELL | |
154 | environment variables are ignored unless the calling user is root. | |
155 | .TP | |
b45413a8 BS |
156 | .BI \-\-session\-command= command |
157 | Same as | |
158 | .B \-c , | |
159 | but do not create a new session. (Discouraged.) | |
7ec6adb1 | 160 | .TP |
75efef98 KZ |
161 | .BR \-w , " \-\-whitelist\-environment" = \fIlist |
162 | Don't reset environment variables specified in comma separated \fIlist\fR when clears | |
163 | environment for \fB\-\-login\fR. The whitelist is ignored for the environment variables | |
164 | .BR HOME , | |
165 | .BR SHELL , | |
166 | .BR USER , | |
167 | .BR LOGNAME ", and" | |
168 | .BR PATH "." | |
169 | .TP | |
b45413a8 | 170 | .BR \-V , " \-\-version" |
7ec6adb1 | 171 | Display version information and exit. |
b45413a8 BS |
172 | .TP |
173 | .BR \-h , " \-\-help" | |
174 | Display help text and exit. | |
7ec6adb1 KZ |
175 | .SH CONFIG FILES |
176 | .B runuser | |
177 | reads the | |
178 | .I /etc/default/runuser | |
179 | and | |
180 | .I /etc/login.defs | |
181 | configuration files. The following configuration items are relevant | |
182 | for | |
183 | .BR runuser : | |
184 | .PP | |
185 | .B ENV_PATH | |
186 | (string) | |
187 | .RS 4 | |
188 | Defines the PATH environment variable for a regular user. The | |
189 | default value is | |
190 | .IR /usr/local/bin:\:/bin:\:/usr/bin . | |
191 | .RE | |
192 | .PP | |
193 | .B ENV_ROOTPATH | |
194 | (string) | |
195 | .br | |
196 | .B ENV_SUPATH | |
197 | (string) | |
198 | .RS 4 | |
86f42e5a | 199 | Defines the PATH environment variable for root. ENV_SUPATH takes precedence. The default value is |
7ec6adb1 KZ |
200 | .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin . |
201 | .RE | |
202 | .PP | |
203 | .B ALWAYS_SET_PATH | |
204 | (boolean) | |
205 | .RS 4 | |
206 | If set to | |
207 | .I yes | |
208 | and \-\-login and \-\-preserve\-environment were not specified | |
209 | .B runuser | |
210 | initializes | |
211 | .BR PATH . | |
212 | .RE | |
64d11d6b KZ |
213 | .sp |
214 | The environment variable PATH may be different on systems where /bin and /sbin | |
215 | are merged into /usr. | |
7ec6adb1 KZ |
216 | .SH EXIT STATUS |
217 | .B runuser | |
218 | normally returns the exit status of the command it executed. If the | |
219 | command was killed by a signal, | |
220 | .B runuser | |
221 | returns the number of the signal plus 128. | |
222 | .PP | |
223 | Exit status generated by | |
224 | .B runuser | |
225 | itself: | |
226 | .RS 10 | |
227 | .TP | |
228 | 1 | |
229 | Generic error before executing the requested command | |
230 | .TP | |
231 | 126 | |
232 | The requested command could not be executed | |
233 | .TP | |
234 | 127 | |
96b65fb3 | 235 | The requested command was not found |
7ec6adb1 KZ |
236 | .RE |
237 | .SH FILES | |
238 | .PD 0 | |
239 | .TP 17 | |
240 | /etc/pam.d/runuser | |
241 | default PAM configuration file | |
242 | .TP | |
243 | /etc/pam.d/runuser-l | |
244 | PAM configuration file if \-\-login is specified | |
245 | .TP | |
246 | /etc/default/runuser | |
247 | runuser specific logindef config file | |
248 | .TP | |
249 | /etc/login.defs | |
250 | global logindef config file | |
251 | .PD 1 | |
252 | .SH "SEE ALSO" | |
f053ff1e | 253 | .BR setpriv (1), |
c424fd83 | 254 | .BR su (1), |
f053ff1e MK |
255 | .BR login.defs (5), |
256 | .BR shells (5), | |
257 | .BR pam (8) | |
b45413a8 BS |
258 | .SH HISTORY |
259 | This \fB runuser\fR command was | |
a55f60a1 | 260 | derived from coreutils' \fBsu\fR, which was based on an implementation by |
b45413a8 | 261 | David MacKenzie, and the Fedora \fBrunuser\fR command by Dan Walsh. |
7ec6adb1 KZ |
262 | .SH AVAILABILITY |
263 | The runuser command is part of the util-linux package and is | |
264 | available from | |
d673b74e | 265 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
7ec6adb1 KZ |
266 | Linux Kernel Archive |
267 | .UE . |