Debian Codegraph @

upstream/debian-trixie/man1/run0.1

raw
1 '\" t
2 .TH "RUN0" "1" "" "systemd 257.13" "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 instead of root\&.
171 .sp
172 Added in version 256\&.
173 .RE
174 .PP
175 \fB\-\-nice=\fR
176 .RS 4
177 Runs the invoked session with the specified nice level\&.
178 .sp
179 Added in version 256\&.
180 .RE
181 .PP
182 \fB\-\-chdir=\fR, \fB\-D\fR
183 .RS 4
184 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\&.
185 .sp
186 Added in version 256\&.
187 .RE
188 .PP
189 \fB\-\-setenv=\fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR
190 .RS 4
191 Runs the invoked session with the specified environment variable set\&. This parameter may be used more than once to set multiple variables\&. When
192 "="
193 and
194 \fIVALUE\fR
195 are omitted, the value of the variable with the same name in the invoking environment will be used\&.
196 .sp
197 Added in version 256\&.
198 .RE
199 .PP
200 \fB\-\-background=\fR\fB\fICOLOR\fR\fR
201 .RS 4
202 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
203 "40",
204 "41", \&...,
205 "47",
206 "48;2;\&...",
207 "48;5;\&..."\&. See
208 \m[blue]\fBANSI Escape Code (Wikipedia)\fR\m[]\&\s-2\u[2]\d\s+2
209 for details\&. Set to an empty string to disable\&.
210 .sp
211 Example:
212 "\-\-background=44"
213 for a blue background\&.
214 .sp
215 Added in version 256\&.
216 .RE
217 .PP
218 \fB\-\-pty\fR, \fB\-\-pipe\fR
219 .RS 4
220 Request allocation of a pseudo TTY for the
221 \fBrun0\fR
222 session (in case of
223 \fB\-\-pty\fR), or request passing the caller\*(Aqs STDIO file descriptors directly through (in case of
224 \fB\-\-pipe\fR)\&. If neither switch is specified, or if both switches 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, otherwise the relevant file descriptors are passed through directly\&.
225 .sp
226 Added in version 257\&.
227 .RE
228 .PP
229 \fB\-\-shell\-prompt\-prefix=\fR\fB\fISTRING\fR\fR
230 .RS 4
231 Set a shell prompt prefix string\&. This ultimately controls the
232 \fI$SHELL_PROMPT_PREFIX\fR
233 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
234 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
235 environment variable to
236 \fIrun0\fR, see below\&. Set to an empty string to disable shell prompt prefixing\&.
237 .sp
238 Added in version 257\&.
239 .RE
240 .PP
241 \fB\-\-machine=\fR
242 .RS 4
243 Execute operation in a local container\&. Specify a container name to connect to\&.
244 .sp
245 Added in version 256\&.
246 .RE
247 .PP
248 \fB\-\-no\-ask\-password\fR
249 .RS 4
250 Do not query the user for authentication for privileged operations\&.
251 .RE
252 .PP
253 \fB\-h\fR, \fB\-\-help\fR
254 .RS 4
255 Print a short help text and exit\&.
256 .RE
257 .PP
258 \fB\-\-version\fR
259 .RS 4
260 Print a short version string and exit\&.
261 .RE
262 .PP
263 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 via
264 \fB\-\-setenv=SHELL=\&...\fR
265 and currently defaults to the
266 \fIoriginating user\*(Aqs\fR
267 shell (i\&.e\&. not the target user\*(Aqs!) if operating locally, or
268 /bin/sh
269 when operating with
270 \fB\-\-machine=\fR\&.
271 .SH "EXIT STATUS"
272 .PP
273 On success, 0 is returned\&. If
274 \fBrun0\fR
275 failed to start the session or the specified command fails, a non\-zero return value will be returned\&.
276 .SH "ENVIRONMENT VARIABLES"
277 .PP
278 As with
279 \fBsystemd\-run\fR, the session will inherit the system environment from the service manager\&. In addition, the following environment variables will be set:
280 .PP
281 \fI$TERM\fR
282 .RS 4
283 Copied from the
284 \fI$TERM\fR
285 of the caller\&. Can be overridden with
286 \fB\-\-setenv=\fR
287 .sp
288 Added in version 256\&.
289 .RE
290 .PP
291 \fI$SUDO_USER\fR
292 .RS 4
293 Set to the username of the originating user\&.
294 .sp
295 Added in version 256\&.
296 .RE
297 .PP
298 \fI$SUDO_UID\fR
299 .RS 4
300 Set to the numeric UNIX user id of the originating user\&.
301 .sp
302 Added in version 256\&.
303 .RE
304 .PP
305 \fI$SUDO_GID\fR
306 .RS 4
307 Set to the primary numeric UNIX group id of the originating session\&.
308 .sp
309 Added in version 256\&.
310 .RE
311 .PP
312 \fI$SHELL_PROMPT_PREFIX\fR
313 .RS 4
314 By default, set to the superhero emoji (if supported), but may be overridden with the
315 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
316 environment variable (see below), or the
317 \fB\-\-shell\-prompt\-prefix=\fR
318 switch (see above)\&.
319 .sp
320 Added in version 257\&.
321 .RE
322 .PP
323 The following variables may be passed to
324 \fBrun0\fR:
325 .PP
326 \fI$SYSTEMD_RUN_SHELL_PROMPT_PREFIX\fR
327 .RS 4
328 If set, overrides the default shell prompt prefix that
329 \fBrun0\fR
330 sets for the invoked shell (the superhero emoji)\&. Set to an empty string to disable shell prompt prefixing\&.
331 .sp
332 Added in version 257\&.
333 .RE
334 .SH "SEE ALSO"
335 .PP
336 \fBsystemd\fR(1), \fBsystemd-run\fR(1), \fBsudo\fR(8), \fBmachinectl\fR(1)
337 .SH "NOTES"
338 .IP " 1." 4
339 polkit
340 .RS 4
341 \%https://www.freedesktop.org/wiki/Software/polkit
342 .RE
343 .IP " 2." 4
344 ANSI Escape Code (Wikipedia)
345 .RS 4
346 \%https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
347 .RE