Debian Codegraph @

upstream/fedora-44/man1/run0.1

raw
1 '\" t
2 .TH "RUN0" "1" "" "systemd 259.5" "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 if the target user is
286 "root"
287 or a system user the per\-user service manager is not activated as effect of the
288 \fBrun0\fR
289 invocation, otherwise it is\&.
290 .sp
291 This ultimately controls the
292 \fI$XDG_SESSION_CLASS\fR
293 environment variable
294 \fBpam_systemd\fR(8)
295 respects\&.
296 .sp
297 Added in version 258\&.
298 .RE
299 .PP
300 \fB\-\-area=\fR\fB\fIAREA\fR\fR
301 .RS 4
302 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
303 "foobar"
304 of an account translates to
305 \fI$HOME\fR
306 being set to
307 ~/Areas/foobar
308 on login\&.
309 .sp
310 If this option is used, the default user to transition to changes from root to the calling user\*(Aqs (but
311 \fB\-\-user=\fR
312 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\&.
313 .sp
314 This ultimately controls the
315 \fI$XDG_AREA\fR
316 environment variable
317 \fBpam_systemd\fR(8)
318 respects\&.
319 .sp
320 For details on the area concept see
321 \fBpam_systemd_home\fR(8)\&.
322 .sp
323 Added in version 258\&.
324 .RE
325 .PP
326 \fB\-\-empower\fR
327 .RS 4
328 If specified, run0 will elevate the privileges of the selected user (using
329 \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
330 "empower"
331 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\&.
332 .sp
333 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\&.
334 .sp
335 Added in version 259\&.
336 .RE
337 .PP
338 \fB\-\-same\-root\-dir\fR
339 .RS 4
340 Execute the
341 \fBrun0\fR
342 session in the same root directory that the
343 \fBrun0\fR
344 command is executed in\&.
345 .sp
346 Added in version 259\&.
347 .RE
348 .PP
349 \fB\-\-machine=\fR
350 .RS 4
351 Execute operation in a local container\&. Specify a container name to connect to\&.
352 .sp
353 Added in version 256\&.
354 .RE
355 .PP
356 \fB\-\-no\-ask\-password\fR
357 .RS 4
358 Do not query the user for authentication for privileged operations\&.
359 .RE
360 .PP
361 \fB\-h\fR, \fB\-\-help\fR
362 .RS 4
363 Print a short help text and exit\&.
364 .RE
365 .PP
366 \fB\-\-version\fR
367 .RS 4
368 Print a short version string and exit\&.
369 .RE
370 .PP
371 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
372 \fB\-\-via\-shell\fR
373 \- when specified the target user\*(Aqs shell is used \- or
374 \fB\-\-setenv=SHELL=\&...\fR\&. By default, the
375 \fIoriginating user\*(Aqs\fR
376 shell is executed if operating locally, or
377 /bin/sh
378 when operating with
379 \fB\-\-machine=\fR\&.
380 .PP
381 Note that unlike
382 \fBsudo\fR,
383 \fBrun0\fR
384 always spawns shells with login shell semantics, regardless of
385 \fB\-i\fR\&.
386 .SH "EXIT STATUS"
387 .PP
388 On success, 0 is returned\&. If
389 \fBrun0\fR
390 failed to start the session or the specified command fails, a non\-zero return value will be returned\&.
391 .SH "ENVIRONMENT VARIABLES"
392 .PP
393 As with
394 \fBsystemd\-run\fR, the session will inherit the system environment from the service manager\&. In addition, the following environment variables will be set:
395 .PP
396 \fI$TERM\fR
397 .RS 4
398 Copied from the
399 \fI$TERM\fR
400 of the caller\&. Can be overridden with
401 \fB\-\-setenv=\fR
402 .sp
403 Added in version 256\&.
404 .RE
405 .PP
406 \fI$SUDO_USER\fR
407 .RS 4
408 Set to the username of the originating user\&.
409 .sp
410 Added in version 256\&.
411 .RE
412 .PP
413 \fI$SUDO_UID\fR
414 .RS 4
415 Set to the numeric UNIX user id of the originating user\&.
416 .sp
417 Added in version 256\&.
418 .RE
419 .PP
420 \fI$SUDO_GID\fR
421 .RS 4
422 Set to the primary numeric UNIX group id of the originating session\&.
423 .sp
424 Added in version 256\&.
425 .RE
426 .PP
427 \fI$SHELL_PROMPT_PREFIX\fR
428 .RS 4
429 By default, set to the superhero emoji (if supported), but may be overridden with the
430 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
431 environment variable (see below), or the
432 \fB\-\-shell\-prompt\-prefix=\fR
433 switch (see above)\&.
434 .sp
435 Added in version 257\&.
436 .RE
437 .PP
438 The following variables may be passed to
439 \fBrun0\fR:
440 .PP
441 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
442 .RS 4
443 If set, overrides the default shell prompt prefix that
444 \fBrun0\fR
445 sets for the invoked shell (the superhero emoji)\&. Set to an empty string to disable shell prompt prefixing\&.
446 .sp
447 Added in version 257\&.
448 .RE
449 .SH "SEE ALSO"
450 .PP
451 \fBsystemd\fR(1), \fBsystemd-run\fR(1), \fBsudo\fR(8), \fBmachinectl\fR(1), \fBpam_systemd\fR(8)
452 .SH "NOTES"
453 .IP " 1." 4
454 polkit
455 .RS 4
456 \%https://www.freedesktop.org/wiki/Software/polkit
457 .RE
458 .IP " 2." 4
459 ANSI Escape Code (Wikipedia)
460 .RS 4
461 \%https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
462 .RE