]>
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 | |
7a7f9d38 KZ |
7 | .IR "command " [ argument ...] |
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 KZ |
84 | .B TERM |
85 | .TP | |
86 | o | |
87 | initializes the environment variables | |
88 | .BR HOME , | |
89 | .BR SHELL , | |
90 | .BR USER , | |
91 | .BR LOGNAME , | |
92 | .B PATH | |
93 | .TP | |
94 | o | |
95 | changes to the target user's home directory | |
96 | .TP | |
97 | o | |
98 | sets argv[0] of the shell to | |
99 | .RB ' \- ' | |
100 | in order to make the shell a login shell | |
101 | .RE | |
102 | .TP | |
b06c1ca6 | 103 | .BR \-m , " \-p" , " \-\-preserve\-environment" |
b45413a8 | 104 | Preserve the entire environment, i.e. it does not set |
7ec6adb1 KZ |
105 | .BR HOME , |
106 | .BR SHELL , | |
107 | .B USER | |
108 | nor | |
109 | .BR LOGNAME . | |
9ba27b26 | 110 | The option is ignored if the option \fB\-\-login\fR is specified. |
7ec6adb1 | 111 | .TP |
b45413a8 BS |
112 | .BR \-s , " \-\-shell" = \fIshell |
113 | Run the specified \fIshell\fR instead of the default. The shell to run is | |
114 | selected according to the following rules, in order: | |
7ec6adb1 KZ |
115 | .RS 10 |
116 | .TP | |
117 | o | |
118 | the shell specified with | |
119 | .B \-\-shell | |
120 | .TP | |
121 | o | |
b45413a8 | 122 | the shell specified in the environment variable |
7ec6adb1 KZ |
123 | .B SHELL |
124 | if the | |
b06c1ca6 | 125 | .B \-\-preserve\-environment |
b45413a8 | 126 | option is used |
7ec6adb1 KZ |
127 | .TP |
128 | o | |
129 | the shell listed in the passwd entry of the target user | |
130 | .TP | |
131 | o | |
132 | /bin/sh | |
133 | .RE | |
134 | .IP | |
135 | If the target user has a restricted shell (i.e. not listed in | |
136 | /etc/shells) the | |
137 | .B \-\-shell | |
138 | option and the | |
139 | .B SHELL | |
140 | environment variables are ignored unless the calling user is root. | |
141 | .TP | |
b45413a8 BS |
142 | .BI \-\-session\-command= command |
143 | Same as | |
144 | .B \-c , | |
145 | but do not create a new session. (Discouraged.) | |
7ec6adb1 | 146 | .TP |
b45413a8 | 147 | .BR \-V , " \-\-version" |
7ec6adb1 | 148 | Display version information and exit. |
b45413a8 BS |
149 | .TP |
150 | .BR \-h , " \-\-help" | |
151 | Display help text and exit. | |
7ec6adb1 KZ |
152 | .SH CONFIG FILES |
153 | .B runuser | |
154 | reads the | |
155 | .I /etc/default/runuser | |
156 | and | |
157 | .I /etc/login.defs | |
158 | configuration files. The following configuration items are relevant | |
159 | for | |
160 | .BR runuser : | |
161 | .PP | |
162 | .B ENV_PATH | |
163 | (string) | |
164 | .RS 4 | |
165 | Defines the PATH environment variable for a regular user. The | |
166 | default value is | |
167 | .IR /usr/local/bin:\:/bin:\:/usr/bin . | |
168 | .RE | |
169 | .PP | |
170 | .B ENV_ROOTPATH | |
171 | (string) | |
172 | .br | |
173 | .B ENV_SUPATH | |
174 | (string) | |
175 | .RS 4 | |
176 | Defines the PATH environment variable for root. The default value is | |
177 | .IR /usr/local/sbin:\:/usr/local/bin:\:/sbin:\:/bin:\:/usr/sbin:\:/usr/bin . | |
178 | .RE | |
179 | .PP | |
180 | .B ALWAYS_SET_PATH | |
181 | (boolean) | |
182 | .RS 4 | |
183 | If set to | |
184 | .I yes | |
185 | and \-\-login and \-\-preserve\-environment were not specified | |
186 | .B runuser | |
187 | initializes | |
188 | .BR PATH . | |
189 | .RE | |
190 | .SH EXIT STATUS | |
191 | .B runuser | |
192 | normally returns the exit status of the command it executed. If the | |
193 | command was killed by a signal, | |
194 | .B runuser | |
195 | returns the number of the signal plus 128. | |
196 | .PP | |
197 | Exit status generated by | |
198 | .B runuser | |
199 | itself: | |
200 | .RS 10 | |
201 | .TP | |
202 | 1 | |
203 | Generic error before executing the requested command | |
204 | .TP | |
205 | 126 | |
206 | The requested command could not be executed | |
207 | .TP | |
208 | 127 | |
96b65fb3 | 209 | The requested command was not found |
7ec6adb1 KZ |
210 | .RE |
211 | .SH FILES | |
212 | .PD 0 | |
213 | .TP 17 | |
214 | /etc/pam.d/runuser | |
215 | default PAM configuration file | |
216 | .TP | |
217 | /etc/pam.d/runuser-l | |
218 | PAM configuration file if \-\-login is specified | |
219 | .TP | |
220 | /etc/default/runuser | |
221 | runuser specific logindef config file | |
222 | .TP | |
223 | /etc/login.defs | |
224 | global logindef config file | |
225 | .PD 1 | |
226 | .SH "SEE ALSO" | |
f053ff1e | 227 | .BR setpriv (1), |
c424fd83 | 228 | .BR su (1), |
f053ff1e MK |
229 | .BR login.defs (5), |
230 | .BR shells (5), | |
231 | .BR pam (8) | |
b45413a8 BS |
232 | .SH HISTORY |
233 | This \fB runuser\fR command was | |
a55f60a1 | 234 | derived from coreutils' \fBsu\fR, which was based on an implementation by |
b45413a8 | 235 | David MacKenzie, and the Fedora \fBrunuser\fR command by Dan Walsh. |
7ec6adb1 KZ |
236 | .SH AVAILABILITY |
237 | The runuser command is part of the util-linux package and is | |
238 | available from | |
d673b74e | 239 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
7ec6adb1 KZ |
240 | Linux Kernel Archive |
241 | .UE . |