Debian Codegraph @

upstream/debian-unstable/man1/run0.1

raw
1 '\" t
2 .TH "RUN0" "1" "" "systemd 261~rc3" "run0"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 run0 \- Elevate privileges
24 .SH "SYNOPSIS"
25 .HP \w'\fBrun0\fR\ 'u
26 \fBrun0\fR [OPTIONS...] [COMMAND...]
27 .SH "DESCRIPTION"
28 .PP
29 \fBrun0\fR
30 may be used to temporarily and interactively acquire elevated or different privileges\&. It serves a similar purpose as
31 \fBsudo\fR(8), but operates differently in a couple of key areas:
32 .sp
33 .RS 4
34 .ie n \{\
35 \h'-04'\(bu\h'+03'\c
36 .\}
37 .el \{\
38 .sp -1
39 .IP \(bu 2.3
40 .\}
41 No execution or security context credentials are inherited from the caller into the invoked commands, as they are invoked from a fresh, isolated service forked off by the service manager\&.
42 .RE
43 .sp
44 .RS 4
45 .ie n \{\
46 \h'-04'\(bu\h'+03'\c
47 .\}
48 .el \{\
49 .sp -1
50 .IP \(bu 2.3
51 .\}
52 Authentication takes place via
53 \m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2, thus isolating the authentication prompt from the terminal (if possible)\&.
54 .RE
55 .sp
56 .RS 4
57 .ie n \{\
58 \h'-04'\(bu\h'+03'\c
59 .\}
60 .el \{\
61 .sp -1
62 .IP \(bu 2.3
63 .\}
64 An independent pseudo\-tty is allocated for the invoked command, detaching its lifecycle and isolating it for security\&.
65 .RE
66 .sp
67 .RS 4
68 .ie n \{\
69 \h'-04'\(bu\h'+03'\c
70 .\}
71 .el \{\
72 .sp -1
73 .IP \(bu 2.3
74 .\}
75 No SetUID/SetGID file access bit functionality is used for the implementation\&.
76 .RE
77 .PP
78 Altogether this should provide a safer and more robust alternative to the
79 \fBsudo\fR
80 mechanism, in particular in OS environments where SetUID/SetGID support is not available (for example by setting the
81 \fINoNewPrivileges=\fR
82 variable in
83 \fBsystemd-system.conf\fR(5))\&.
84 .PP
85 Any session invoked via
86 \fBrun0\fR
87 will run through the
88 "systemd\-run0"
89 PAM stack\&.
90 .PP
91 Note that
92 \fBrun0\fR
93 is implemented as an alternative multi\-call invocation of
94 \fBsystemd-run\fR(1)\&. That is,
95 \fBrun0\fR
96 is a symbolic link to
97 \fBsystemd\-run\fR
98 executable file, and it behaves as
99 \fBrun0\fR
100 if it is invoked through the symbolic link, otherwise behaves as
101 \fBsystemd\-run\fR\&.
102 .SH "OPTIONS"
103 .PP
104 The following options are understood:
105 .PP
106 \fB\-\-unit=\fR
107 .RS 4
108 Use this unit name instead of an automatically generated one\&.
109 .sp
110 Added in version 256\&.
111 .RE
112 .PP
113 \fB\-\-property=\fR
114 .RS 4
115 Sets a property of the service unit that is created\&. This option takes an assignment in the same format as
116 \fBsystemctl\fR(1)\*(Aqs
117 \fBset\-property\fR
118 command\&.
119 .sp
120 Added in version 256\&.
121 .RE
122 .PP
123 \fB\-\-description=\fR
124 .RS 4
125 Provide a description for the service unit that is invoked\&. If not specified, the command itself will be used as a description\&. See
126 \fIDescription=\fR
127 in
128 \fBsystemd.unit\fR(5)\&.
129 .sp
130 Added in version 256\&.
131 .RE
132 .PP
133 \fB\-\-slice=\fR
134 .RS 4
135 Make the new
136 \&.service
137 unit part of the specified slice, instead of
138 user\&.slice\&.
139 .sp
140 Added in version 256\&.
141 .RE
142 .PP
143 \fB\-\-slice\-inherit\fR
144 .RS 4
145 Make the new
146 \&.service
147 unit part of the slice the
148 \fBrun0\fR
149 itself has been invoked in\&. This option may be combined with
150 \fB\-\-slice=\fR, in which case the slice specified via
151 \fB\-\-slice=\fR
152 is placed within the slice the
153 \fBrun0\fR
154 command is invoked in\&.
155 .sp
156 Example: consider
157 \fBrun0\fR
158 being invoked in the slice
159 foo\&.slice, and the
160 \fB\-\-slice=\fR
161 argument is
162 bar\&. The unit will then be placed under
163 foo\-bar\&.slice\&.
164 .sp
165 Added in version 256\&.
166 .RE
167 .PP
168 \fB\-\-user=\fR, \fB\-u\fR, \fB\-\-group=\fR, \fB\-g\fR
169 .RS 4
170 Switches to the specified user/group\&. If not specified defaults to
171 "root", unless
172 \fB\-\-area=\fR
173 or
174 \fB\-\-empower\fR
175 are used (see below), in which case this defaults to the invoking user\&.
176 .sp
177 Added in version 256\&.
178 .RE
179 .PP
180 \fB\-\-nice=\fR
181 .RS 4
182 Runs the invoked session with the specified nice level\&.
183 .sp
184 Added in version 256\&.
185 .RE
186 .PP
187 \fB\-\-chdir=\fR, \fB\-D\fR
188 .RS 4
189 Runs the invoked session with the specified working directory\&. If not specified defaults to the client\*(Aqs current working directory if switching to the root user, or the target user\*(Aqs home directory otherwise\&.
190 .sp
191 Added in version 256\&.
192 .RE
193 .PP
194 \fB\-\-via\-shell\fR
195 .RS 4
196 Invokes the target user\*(Aqs login shell and runs the specified command (if any) via it\&.
197 .sp
198 Added in version 258\&.
199 .RE
200 .PP
201 \fB\-i\fR
202 .RS 4
203 Shortcut for
204 \fB\-\-via\-shell \-\-chdir=\*(Aq~\*(Aq\fR\&.
205 .sp
206 Added in version 258\&.
207 .RE
208 .PP
209 \fB\-\-setenv=\fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR
210 .RS 4
211 Runs the invoked session with the specified environment variable set\&. This parameter may be used more than once to set multiple variables\&. When
212 "="
213 and
214 \fIVALUE\fR
215 are omitted, the value of the variable with the same name in the invoking environment will be used\&.
216 .sp
217 Added in version 256\&.
218 .RE
219 .PP
220 \fB\-\-background=\fR\fB\fICOLOR\fR\fR
221 .RS 4
222 Change the terminal background color to the specified ANSI color as long as the session lasts\&. If not specified, the background will be tinted in a reddish tone when operating as root, and in a yellowish tone when operating under another UID, as reminder of the changed privileges\&. The color specified should be an ANSI X3\&.64 SGR background color, i\&.e\&. strings such as
223 "40",
224 "41", \&...,
225 "47",
226 "48;2;\&...",
227 "48;5;\&..."\&. See
228 \m[blue]\fBANSI Escape Code (Wikipedia)\fR\m[]\&\s-2\u[2]\d\s+2
229 for details\&. Set to an empty string to disable\&.
230 .sp
231 Example:
232 "\-\-background=44"
233 for a blue background\&.
234 .sp
235 Added in version 256\&.
236 .RE
237 .PP
238 \fB\-\-pty\fR, \fB\-\-pty\-late\fR, \fB\-\-pipe\fR
239 .RS 4
240 Request allocation of a pseudo TTY for the
241 \fBrun0\fR
242 session (in case of
243 \fB\-\-pty\fR
244 or
245 \fB\-\-pty\-late\fR), or request passing the caller\*(Aqs STDIO file descriptors directly through (in case of
246 \fB\-\-pipe\fR)\&.
247 \fB\-\-pty\-late\fR
248 is very similar to
249 \fB\-\-pty\fR
250 but begins the TTY processing only once unit startup is complete, leaving input to any passwords/polkit agents until that time\&. If neither switch is specified, or if both
251 \fB\-\-pipe\fR
252 and one of
253 \fB\-\-pty\fR/\fB\-\-pty\-late\fR
254 are specified, the mode will be picked automatically: if standard input, standard output, and standard error output are all connected to a TTY then a pseudo TTY is allocated (in
255 \fB\-\-pty\-late\fR
256 mode unless
257 \fB\-\-no\-ask\-password\fR
258 is specified in which case
259 \fB\-\-pty\fR
260 is selected), otherwise the relevant file descriptors are passed through directly\&.
261 .sp
262 \fB\-\-pty\fR
263 and
264 \fB\-\-pipe\fR
265 were added in v257\&.
266 .sp
267 \fB\-\-pty\-late\fR
268 was added in v258\&.
269 .RE
270 .PP
271 \fB\-\-shell\-prompt\-prefix=\fR\fB\fISTRING\fR\fR
272 .RS 4
273 Set a shell prompt prefix string\&. This ultimately controls the
274 \fI$SHELL_PROMPT_PREFIX\fR
275 environment variable for the invoked program, which is typically imported into the shell prompt\&. By default \(en if emojis are supported \(en, a superhero emoji is shown (🦸)\&. This default may also be changed (or turned off) by passing the
276 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
277 environment variable to
278 \fIrun0\fR, see below\&. Set to an empty string to disable shell prompt prefixing\&.
279 .sp
280 Added in version 257\&.
281 .RE
282 .PP
283 \fB\-\-lightweight=\fR\fB\fIBOOLEAN\fR\fR
284 .RS 4
285 Controls whether to activate the per\-user service manager for the target user\&. By default (unset or set to
286 \fBauto\fR), if the target user is
287 "root"
288 or a system user the per\-user service manager is not activated as effect of the
289 \fBrun0\fR
290 invocation, otherwise it is\&.
291 .sp
292 This ultimately controls the
293 \fI$XDG_SESSION_CLASS\fR
294 environment variable
295 \fBpam_systemd\fR(8)
296 respects\&.
297 .sp
298 Added in version 258\&.
299 .RE
300 .PP
301 \fB\-\-area=\fR\fB\fIAREA\fR\fR
302 .RS 4
303 Controls the "area" of the target account to log into\&. Areas are secondary home directories within the primary home directory of the target user, i\&.e\&. logging into area
304 "foobar"
305 of an account translates to
306 \fI$HOME\fR
307 being set to
308 ~/Areas/foobar
309 on login\&.
310 .sp
311 If this option is used, the default user to transition to changes from root to the calling user\*(Aqs (but
312 \fB\-\-user=\fR
313 takes precedence, see above)\&. Or in other words, just specifying an area without a user is a mechanism to create a new session of the calling user, just with a different area\&.
314 .sp
315 This ultimately controls the
316 \fI$XDG_AREA\fR
317 environment variable
318 \fBpam_systemd\fR(8)
319 respects\&.
320 .sp
321 For details on the area concept see
322 \fBpam_systemd_home\fR(8)\&.
323 .sp
324 Added in version 258\&.
325 .RE
326 .PP
327 \fB\-\-empower\fR
328 .RS 4
329 If specified, run0 will elevate the privileges of the selected user (using
330 \fB\-\-user=\fR) or the current user if no user is explicitly selected\&. Currently this means we give the invoked process all available capabilities and add the
331 "empower"
332 group as a supplemental group (for which all polkit actions are allowed by default), but other privileges may be granted in the future as well when using this option\&.
333 .sp
334 Note that other (unprivileged) processes of the selected user will have privileges over the invoked process\&. Consider not using this option in an environment where there might be malicious processes running as the selected user\&.
335 .sp
336 Added in version 259\&.
337 .RE
338 .PP
339 \fB\-\-same\-root\-dir\fR
340 .RS 4
341 Execute the
342 \fBrun0\fR
343 session in the same root directory that the
344 \fBrun0\fR
345 command is executed in\&.
346 .sp
347 Added in version 259\&.
348 .RE
349 .PP
350 \fB\-\-machine=\fR
351 .RS 4
352 Execute operation in a local container\&. Specify a container name to connect to\&.
353 .sp
354 Added in version 256\&.
355 .RE
356 .PP
357 \fB\-\-no\-ask\-password\fR
358 .RS 4
359 Do not query the user for authentication for privileged operations\&.
360 .RE
361 .PP
362 \fB\-h\fR, \fB\-\-help\fR
363 .RS 4
364 Print a short help text and exit\&.
365 .RE
366 .PP
367 \fB\-\-version\fR
368 .RS 4
369 Print a short version string and exit\&.
370 .RE
371 .PP
372 All command line arguments after the first non\-option argument become part of the command line of the launched process\&. If no command line is specified an interactive shell is invoked\&. The shell to invoke may be controlled through
373 \fB\-\-via\-shell\fR
374 \- when specified the target user\*(Aqs shell is used \- or
375 \fB\-\-setenv=SHELL=\&...\fR\&. By default, the
376 \fIoriginating user\*(Aqs\fR
377 shell is executed if operating locally, or
378 /bin/sh
379 when operating with
380 \fB\-\-machine=\fR\&.
381 .PP
382 Note that unlike
383 \fBsudo\fR,
384 \fBrun0\fR
385 always spawns shells with login shell semantics, regardless of
386 \fB\-i\fR\&.
387 .SH "EXIT STATUS"
388 .PP
389 On success, 0 is returned\&. If
390 \fBrun0\fR
391 failed to start the session or the specified command fails, a non\-zero return value will be returned\&.
392 .SH "ENVIRONMENT VARIABLES"
393 .PP
394 As with
395 \fBsystemd\-run\fR, the session will inherit the system environment from the service manager\&. In addition, the following environment variables will be set:
396 .PP
397 \fI$TERM\fR
398 .RS 4
399 Copied from the
400 \fI$TERM\fR
401 of the caller\&. Can be overridden with
402 \fB\-\-setenv=\fR
403 .sp
404 Added in version 256\&.
405 .RE
406 .PP
407 \fI$SUDO_USER\fR
408 .RS 4
409 Set to the username of the originating user\&.
410 .sp
411 Added in version 256\&.
412 .RE
413 .PP
414 \fI$SUDO_UID\fR
415 .RS 4
416 Set to the numeric UNIX user id of the originating user\&.
417 .sp
418 Added in version 256\&.
419 .RE
420 .PP
421 \fI$SUDO_GID\fR
422 .RS 4
423 Set to the primary numeric UNIX group id of the originating session\&.
424 .sp
425 Added in version 256\&.
426 .RE
427 .PP
428 \fI$SHELL_PROMPT_PREFIX\fR
429 .RS 4
430 By default, set to the superhero emoji (if supported), but may be overridden with the
431 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
432 environment variable (see below), or the
433 \fB\-\-shell\-prompt\-prefix=\fR
434 switch (see above)\&.
435 .sp
436 Added in version 257\&.
437 .RE
438 .PP
439 The following variables may be passed to
440 \fBrun0\fR:
441 .PP
442 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
443 .RS 4
444 If set, overrides the default shell prompt prefix that
445 \fBrun0\fR
446 sets for the invoked shell (the superhero emoji)\&. Set to an empty string to disable shell prompt prefixing\&.
447 .sp
448 Added in version 257\&.
449 .RE
450 .SH "SEE ALSO"
451 .PP
452 \fBsystemd\fR(1), \fBsystemd-run\fR(1), \fBsudo\fR(8), \fBmachinectl\fR(1), \fBpam_systemd\fR(8)
453 .SH "NOTES"
454 .IP " 1." 4
455 polkit
456 .RS 4
457 \%https://www.freedesktop.org/wiki/Software/polkit
458 .RE
459 .IP " 2." 4
460 ANSI Escape Code (Wikipedia)
461 .RS 4
462 \%https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
463 .RE