Debian Codegraph @

upstream/mageia-cauldron/man1/run0.1

raw
1 '\" t
2 .TH "RUN0" "1" "" "systemd 258.7" "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 is used (see below), in which case this defaults to the invoking user\&.
174 .sp
175 Added in version 256\&.
176 .RE
177 .PP
178 \fB\-\-nice=\fR
179 .RS 4
180 Runs the invoked session with the specified nice level\&.
181 .sp
182 Added in version 256\&.
183 .RE
184 .PP
185 \fB\-\-chdir=\fR, \fB\-D\fR
186 .RS 4
187 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\&.
188 .sp
189 Added in version 256\&.
190 .RE
191 .PP
192 \fB\-\-via\-shell\fR
193 .RS 4
194 Invokes the target user\*(Aqs login shell and runs the specified command (if any) via it\&.
195 .sp
196 Added in version 258\&.
197 .RE
198 .PP
199 \fB\-i\fR
200 .RS 4
201 Shortcut for
202 \fB\-\-via\-shell \-\-chdir=\*(Aq~\*(Aq\fR\&.
203 .sp
204 Added in version 258\&.
205 .RE
206 .PP
207 \fB\-\-setenv=\fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR
208 .RS 4
209 Runs the invoked session with the specified environment variable set\&. This parameter may be used more than once to set multiple variables\&. When
210 "="
211 and
212 \fIVALUE\fR
213 are omitted, the value of the variable with the same name in the invoking environment will be used\&.
214 .sp
215 Added in version 256\&.
216 .RE
217 .PP
218 \fB\-\-background=\fR\fB\fICOLOR\fR\fR
219 .RS 4
220 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
221 "40",
222 "41", \&...,
223 "47",
224 "48;2;\&...",
225 "48;5;\&..."\&. See
226 \m[blue]\fBANSI Escape Code (Wikipedia)\fR\m[]\&\s-2\u[2]\d\s+2
227 for details\&. Set to an empty string to disable\&.
228 .sp
229 Example:
230 "\-\-background=44"
231 for a blue background\&.
232 .sp
233 Added in version 256\&.
234 .RE
235 .PP
236 \fB\-\-pty\fR, \fB\-\-pty\-late\fR, \fB\-\-pipe\fR
237 .RS 4
238 Request allocation of a pseudo TTY for the
239 \fBrun0\fR
240 session (in case of
241 \fB\-\-pty\fR
242 or
243 \fB\-\-pty\-late\fR), or request passing the caller\*(Aqs STDIO file descriptors directly through (in case of
244 \fB\-\-pipe\fR)\&.
245 \fB\-\-pty\-late\fR
246 is very similar to
247 \fB\-\-pty\fR
248 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
249 \fB\-\-pipe\fR
250 and one of
251 \fB\-\-pty\fR/\fB\-\-pty\-late\fR
252 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
253 \fB\-\-pty\-late\fR
254 mode unless
255 \fB\-\-no\-ask\-password\fR
256 is specified in which case
257 \fB\-\-pty\fR
258 is selected), otherwise the relevant file descriptors are passed through directly\&.
259 .sp
260 \fB\-\-pty\fR
261 and
262 \fB\-\-pipe\fR
263 were added in v257\&.
264 .sp
265 \fB\-\-pty\-late\fR
266 was added in v258\&.
267 .RE
268 .PP
269 \fB\-\-shell\-prompt\-prefix=\fR\fB\fISTRING\fR\fR
270 .RS 4
271 Set a shell prompt prefix string\&. This ultimately controls the
272 \fI$SHELL_PROMPT_PREFIX\fR
273 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
274 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
275 environment variable to
276 \fIrun0\fR, see below\&. Set to an empty string to disable shell prompt prefixing\&.
277 .sp
278 Added in version 257\&.
279 .RE
280 .PP
281 \fB\-\-lightweight=\fR\fB\fIBOOLEAN\fR\fR
282 .RS 4
283 Controls whether to activate the per\-user service manager for the target user\&. By default if the target user is
284 "root"
285 or a system user the per\-user service manager is not activated as effect of the
286 \fBrun0\fR
287 invocation, otherwise it is\&.
288 .sp
289 This ultimately controls the
290 \fI$XDG_SESSION_CLASS\fR
291 environment variable
292 \fBpam_systemd\fR(8)
293 respects\&.
294 .sp
295 Added in version 258\&.
296 .RE
297 .PP
298 \fB\-\-area=\fR\fB\fIAREA\fR\fR
299 .RS 4
300 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
301 "foobar"
302 of an account translates to
303 \fI$HOME\fR
304 being set to
305 ~/Areas/foobar
306 on login\&.
307 .sp
308 If this option is used, the default user to transition to changes from root to the calling user\*(Aqs (but
309 \fB\-\-user=\fR
310 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\&.
311 .sp
312 This ultimately controls the
313 \fI$XDG_AREA\fR
314 environment variable
315 \fBpam_systemd\fR(8)
316 respects\&.
317 .sp
318 For details on the area concept see
319 \fBpam_systemd_home\fR(8)\&.
320 .sp
321 Added in version 258\&.
322 .RE
323 .PP
324 \fB\-\-machine=\fR
325 .RS 4
326 Execute operation in a local container\&. Specify a container name to connect to\&.
327 .sp
328 Added in version 256\&.
329 .RE
330 .PP
331 \fB\-\-no\-ask\-password\fR
332 .RS 4
333 Do not query the user for authentication for privileged operations\&.
334 .RE
335 .PP
336 \fB\-h\fR, \fB\-\-help\fR
337 .RS 4
338 Print a short help text and exit\&.
339 .RE
340 .PP
341 \fB\-\-version\fR
342 .RS 4
343 Print a short version string and exit\&.
344 .RE
345 .PP
346 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
347 \fB\-\-via\-shell\fR
348 \- when specified the target user\*(Aqs shell is used \- or
349 \fB\-\-setenv=SHELL=\&...\fR\&. By default, the
350 \fIoriginating user\*(Aqs\fR
351 shell is executed if operating locally, or
352 /bin/sh
353 when operating with
354 \fB\-\-machine=\fR\&.
355 .PP
356 Note that unlike
357 \fBsudo\fR,
358 \fBrun0\fR
359 always spawns shells with login shell semantics, regardless of
360 \fB\-i\fR\&.
361 .SH "EXIT STATUS"
362 .PP
363 On success, 0 is returned\&. If
364 \fBrun0\fR
365 failed to start the session or the specified command fails, a non\-zero return value will be returned\&.
366 .SH "ENVIRONMENT VARIABLES"
367 .PP
368 As with
369 \fBsystemd\-run\fR, the session will inherit the system environment from the service manager\&. In addition, the following environment variables will be set:
370 .PP
371 \fI$TERM\fR
372 .RS 4
373 Copied from the
374 \fI$TERM\fR
375 of the caller\&. Can be overridden with
376 \fB\-\-setenv=\fR
377 .sp
378 Added in version 256\&.
379 .RE
380 .PP
381 \fI$SUDO_USER\fR
382 .RS 4
383 Set to the username of the originating user\&.
384 .sp
385 Added in version 256\&.
386 .RE
387 .PP
388 \fI$SUDO_UID\fR
389 .RS 4
390 Set to the numeric UNIX user id of the originating user\&.
391 .sp
392 Added in version 256\&.
393 .RE
394 .PP
395 \fI$SUDO_GID\fR
396 .RS 4
397 Set to the primary numeric UNIX group id of the originating session\&.
398 .sp
399 Added in version 256\&.
400 .RE
401 .PP
402 \fI$SHELL_PROMPT_PREFIX\fR
403 .RS 4
404 By default, set to the superhero emoji (if supported), but may be overridden with the
405 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
406 environment variable (see below), or the
407 \fB\-\-shell\-prompt\-prefix=\fR
408 switch (see above)\&.
409 .sp
410 Added in version 257\&.
411 .RE
412 .PP
413 The following variables may be passed to
414 \fBrun0\fR:
415 .PP
416 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
417 .RS 4
418 If set, overrides the default shell prompt prefix that
419 \fBrun0\fR
420 sets for the invoked shell (the superhero emoji)\&. Set to an empty string to disable shell prompt prefixing\&.
421 .sp
422 Added in version 257\&.
423 .RE
424 .SH "SEE ALSO"
425 .PP
426 \fBsystemd\fR(1), \fBsystemd-run\fR(1), \fBsudo\fR(8), \fBmachinectl\fR(1), \fBpam_systemd\fR(8)
427 .SH "NOTES"
428 .IP " 1." 4
429 polkit
430 .RS 4
431 \%https://www.freedesktop.org/wiki/Software/polkit
432 .RE
433 .IP " 2." 4
434 ANSI Escape Code (Wikipedia)
435 .RS 4
436 \%https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
437 .RE