Debian Codegraph @

upstream/debian-unstable/man1/importctl.1

raw
1 '\" t
2 .TH "IMPORTCTL" "1" "" "systemd 261~rc3" "importctl"
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 importctl \- Download, import or export disk images
24 .SH "SYNOPSIS"
25 .HP \w'\fBimportctl\fR\ 'u
26 \fBimportctl\fR [OPTIONS...] {COMMAND} [NAME...]
27 .SH "DESCRIPTION"
28 .PP
29 \fBimportctl\fR
30 may be used to download, import, and export disk images via
31 \fBsystemd-importd.service\fR(8)\&.
32 .PP
33 \fBimportctl\fR
34 operates both on block\-level disk images (such as DDIs), file\-system\-level images (tarballs), as well as OCI images\&. It supports disk images in one of the four following classes:
35 .sp
36 .RS 4
37 .ie n \{\
38 \h'-04'\(bu\h'+03'\c
39 .\}
40 .el \{\
41 .sp -1
42 .IP \(bu 2.3
43 .\}
44 VM images or full OS container images, that may be run via
45 \fBsystemd-vmspawn\fR(1)
46 or
47 \fBsystemd-nspawn\fR(1), and managed via
48 \fBmachinectl\fR(1)\&.
49 .RE
50 .sp
51 .RS 4
52 .ie n \{\
53 \h'-04'\(bu\h'+03'\c
54 .\}
55 .el \{\
56 .sp -1
57 .IP \(bu 2.3
58 .\}
59 Portable service images, that may be attached and managed via
60 \fBportablectl\fR(1)\&.
61 .RE
62 .sp
63 .RS 4
64 .ie n \{\
65 \h'-04'\(bu\h'+03'\c
66 .\}
67 .el \{\
68 .sp -1
69 .IP \(bu 2.3
70 .\}
71 System extension (sysext) images, that may be activated via
72 \fBsystemd-sysext\fR(8)\&.
73 .RE
74 .sp
75 .RS 4
76 .ie n \{\
77 \h'-04'\(bu\h'+03'\c
78 .\}
79 .el \{\
80 .sp -1
81 .IP \(bu 2.3
82 .\}
83 Configuration extension (confext) images, that may be activated via
84 \fBsystemd-confext\fR(8)\&.
85 .RE
86 .PP
87 When images are downloaded or imported they are placed in the following directories, depending on the
88 \fB\-\-class=\fR
89 parameter:
90 .sp
91 .it 1 an-trap
92 .nr an-no-space-flag 1
93 .nr an-break-flag 1
94 .br
95 .B Table\ \&1.\ \&Classes and Directories
96 .TS
97 allbox tab(:);
98 lB lB.
99 T{
100 Class
101 T}:T{
102 Directory
103 T}
104 .T&
105 l l
106 l l
107 l l
108 l l.
109 T{
110 "machine"
111 T}:T{
112 /var/lib/machines/
113 T}
114 T{
115 "portable"
116 T}:T{
117 /var/lib/portables/
118 T}
119 T{
120 "sysext"
121 T}:T{
122 /var/lib/extensions/
123 T}
124 T{
125 "confext"
126 T}:T{
127 /var/lib/confexts/
128 T}
129 .TE
130 .sp 1
131 .SH "COMMANDS"
132 .PP
133 The following commands are understood:
134 .PP
135 \fBpull\-tar\fR \fIURL\fR [\fINAME\fR]
136 .RS 4
137 Downloads a
138 \&.tar
139 image from the specified URL, and makes it available under the specified local name in the image directory for the selected
140 \fB\-\-class=\fR\&. The URL must be of type
141 "http://"
142 or
143 "https://", and must refer to a
144 \&.tar,
145 \&.tar\&.gz,
146 \&.tar\&.xz
147 or
148 \&.tar\&.bz2
149 archive file\&. If the local image name is omitted, it is automatically derived from the last component of the URL, with its suffix removed\&.
150 .sp
151 The image is verified before it is made available, unless
152 \fB\-\-verify=no\fR
153 is specified\&. Verification is done either via a file with the name of the image and the suffix
154 \&.sha256
155 and a detached
156 \&.sha256\&.asc
157 or
158 \&.sha256\&.gpg
159 signature or via separate
160 SHA256SUMS
161 and
162 SHA256SUMS\&.asc
163 or
164 SHA256SUMS\&.gpg
165 files\&. The signature files need to be made available on the same web server, under the same URL as the
166 \&.tar
167 file\&. With
168 \fB\-\-verify=checksum\fR, only the SHA256 checksum for the file is verified, based on the
169 \&.sha256
170 suffixed file or the
171 SHA256SUMS
172 file\&. With
173 \fB\-\-verify=signature\fR, the sha checksum file is first verified with the detached GPG signature of
174 \&.sha256
175 or
176 SHA256SUMS\&. The public key for this verification step needs to be available in
177 /usr/lib/systemd/import\-pubring\&.pgp
178 or
179 /etc/systemd/import\-pubring\&.pgp\&.
180 .sp
181 If
182 \fB\-keep\-download=yes\fR
183 is specified the image will be downloaded and stored in a read\-only subvolume/directory in the image directory that is named after the specified URL and its HTTP etag (see
184 \m[blue]\fBHTTP ETag\fR\m[]\&\s-2\u[1]\d\s+2
185 for more information)\&. A writable snapshot is then taken from this subvolume, and named after the specified local name\&. This behavior ensures that creating multiple instances of the same URL is efficient, as multiple downloads are not necessary\&. In order to create only the read\-only image, and avoid creating its writable snapshot, specify
186 "\-"
187 as local name\&.
188 .sp
189 Note that pressing Control\-c during execution of this command will not abort the download\&. Use
190 \fBcancel\-transfer\fR, described below\&.
191 .sp
192 Added in version 256\&.
193 .RE
194 .PP
195 \fBpull\-raw\fR \fIURL\fR [\fINAME\fR]
196 .RS 4
197 Downloads a
198 \&.raw
199 disk image from the specified URL, and makes it available under the specified local name in the image directory for the selected
200 \fB\-\-class=\fR\&. The URL must be of type
201 "http://"
202 or
203 "https://"\&. The image must either be a qcow2 or raw disk image, optionally compressed as
204 \&.gz,
205 \&.xz, or
206 \&.bz2\&. If the local name is omitted, it is automatically derived from the last component of the URL, with its suffix removed\&.
207 .sp
208 Image verification is identical for raw and tar images (see above)\&.
209 .sp
210 If the downloaded image is in qcow2 format it is converted into a raw image file before it is made available\&.
211 .sp
212 If
213 \fB\-keep\-download=yes\fR
214 is specified the image will be downloaded and stored in a read\-only file in the image directory that is named after the specified URL and its HTTP etag\&. A writable copy is then made from this file, and named after the specified local name\&. This behavior ensures that creating multiple instances of the same URL is efficient, as multiple downloads are not necessary\&. In order to create only the read\-only image, and avoid creating its writable copy, specify
215 "\-"
216 as local name\&.
217 .sp
218 Note that pressing Control\-c during execution of this command will not abort the download\&. Use
219 \fBcancel\-transfer\fR, described below\&.
220 .sp
221 Added in version 256\&.
222 .RE
223 .PP
224 \fBpull\-oci\fR \fIREF\fR [\fINAME\fR]
225 .RS 4
226 Downloads the specified OCI container image, and makes it available under the specified local name in the image directory for the selected
227 \fB\-\-class=\fR\&. The first argument must be an OCI container reference, such as
228 "library/nginx"
229 If the local name is omitted, it is automatically derived from the last component of the URL, with its suffix removed\&.
230 .sp
231 When downloading images of this type no image verification is done beyond the usual authentication of the HTTPS certificates\&.
232 .sp
233 Note that pressing Control\-c during execution of this command will not abort the download\&. Use
234 \fBcancel\-transfer\fR, described below\&.
235 .sp
236 Added in version 260\&.
237 .RE
238 .PP
239 \fBimport\-tar\fR \fIFILE\fR [\fINAME\fR], \fBimport\-raw\fR \fIFILE\fR [\fINAME\fR]
240 .RS 4
241 Imports a TAR or RAW image, and places it under the specified name in the image directory for the image class selected via
242 \fB\-\-class=\fR\&. When
243 \fBimport\-tar\fR
244 is used, the file specified as the first argument should be a
245 \fBtar\fR(1)
246 archive, possibly compressed with
247 \fBxz\fR(1),
248 \fBgzip\fR(1),
249 \fBzstd\fR(1), or
250 \fBbzip2\fR(1)\&. It will then be unpacked into its own subvolume/directory\&. When
251 \fBimport\-raw\fR
252 is used, the file should be a qcow2 or raw disk image, possibly compressed with xz, gzip, zstd or bzip2\&. If the second argument (the resulting image name) is not specified, it is automatically derived from the file name\&. If the filename is passed as
253 "\-", the image is read from standard input, in which case the second argument is mandatory\&.
254 .sp
255 No cryptographic validation is done when importing the images\&.
256 .sp
257 Much like image downloads, ongoing imports may be listed with
258 \fBlist\fR
259 and aborted with
260 \fBcancel\-transfer\fR\&.
261 .sp
262 Added in version 256\&.
263 .RE
264 .PP
265 \fBimport\-fs\fR \fIDIRECTORY\fR [\fINAME\fR]
266 .RS 4
267 Imports an image stored in a local directory into the image directory for the image class selected via
268 \fB\-\-class=\fR
269 and operates similarly to
270 \fBimport\-tar\fR
271 or
272 \fBimport\-raw\fR, but the first argument is the source directory\&. If supported, this command will create a
273 \fBbtrfs\fR(8)
274 snapshot or subvolume for the new image\&.
275 .sp
276 Added in version 256\&.
277 .RE
278 .PP
279 \fBexport\-tar\fR \fINAME\fR [\fIFILE\fR], \fBexport\-raw\fR \fINAME\fR [\fIFILE\fR]
280 .RS 4
281 Exports a TAR or RAW image and stores it in the specified file\&. The first parameter should be an image name\&. The second parameter should be a file path the TAR or RAW image is written to\&. If the path ends in
282 "\&.gz", the file is compressed with
283 \fBgzip\fR(1), if it ends in
284 "\&.xz", with
285 \fBxz\fR(1), if it ends in
286 "\&.zst", with
287 \fBzstd\fR(1), and if it ends in
288 "\&.bz2", with
289 \fBbzip2\fR(1)\&. If the path ends in neither, the file is left uncompressed\&. If the second argument is missing, the image is written to standard output\&. The compression may also be explicitly selected with the
290 \fB\-\-format=\fR
291 switch\&. This is in particular useful if the second parameter is left unspecified\&.
292 .sp
293 Much like image downloads and imports, ongoing exports may be listed with
294 \fBlist\fR
295 and aborted with
296 \fBcancel\-transfer\fR\&.
297 .sp
298 Note that, currently, only directory and subvolume images may be exported as TAR images, and only raw disk images as RAW images\&.
299 .sp
300 Added in version 256\&.
301 .RE
302 .PP
303 \fBlist\-transfer\fR
304 .RS 4
305 Shows a list of image downloads, imports and exports that are currently in progress\&.
306 .sp
307 Added in version 256\&.
308 .RE
309 .PP
310 \fBcancel\-transfer\fR \fIID\fR\&...
311 .RS 4
312 Aborts a download, import or export of the image with the specified ID\&. To list ongoing transfers and their IDs, use
313 \fBlist\fR\&.
314 .sp
315 Added in version 256\&.
316 .RE
317 .PP
318 \fBlist\-images\fR
319 .RS 4
320 Shows a list of already downloaded/imported images\&.
321 .sp
322 Added in version 256\&.
323 .RE
324 .SH "OPTIONS"
325 .PP
326 The following options are understood:
327 .PP
328 \fB\-\-read\-only\fR
329 .RS 4
330 When used with
331 \fBpull\-raw\fR,
332 \fBpull\-tar\fR,
333 \fBimport\-raw\fR,
334 \fBimport\-tar\fR
335 or
336 \fBimport\-fs\fR
337 a read\-only image is created\&.
338 .sp
339 Added in version 256\&.
340 .RE
341 .PP
342 \fB\-\-verify=\fR
343 .RS 4
344 When downloading an image, specify whether the image shall be verified before it is made available\&. Takes one of
345 "no",
346 "checksum"
347 and
348 "signature"\&. If
349 "no", no verification is done\&. If
350 "checksum"
351 is specified, the download is checked for integrity after the transfer is complete, but no signatures are verified\&. If
352 "signature"
353 is specified, the checksum is verified and the image\*(Aqs signature is checked against a local keyring of trustable vendors\&. It is strongly recommended to set this option to
354 "signature"
355 if the server and protocol support this\&. Defaults to
356 "signature"\&.
357 .sp
358 Added in version 256\&.
359 .RE
360 .PP
361 \fB\-\-force\fR
362 .RS 4
363 When downloading an image, and a local copy by the specified local name already exists, delete it first and replace it by the newly downloaded image\&.
364 .sp
365 Added in version 256\&.
366 .RE
367 .PP
368 \fB\-\-format=\fR
369 .RS 4
370 When used with the
371 \fBexport\-tar\fR
372 or
373 \fBexport\-raw\fR
374 commands, specifies the compression format to use for the resulting file\&. Takes one of
375 "uncompressed",
376 "xz",
377 "gzip",
378 "zst",
379 "bzip2"\&. By default, the format is determined automatically from the output image file name passed\&.
380 .sp
381 Added in version 256\&.
382 .RE
383 .PP
384 \fB\-q\fR, \fB\-\-quiet\fR
385 .RS 4
386 Suppresses additional informational output while running\&.
387 .sp
388 Added in version 256\&.
389 .RE
390 .PP
391 \fB\-H\fR, \fB\-\-host=\fR
392 .RS 4
393 Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
394 "@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
395 ":", and then a container name, separated by
396 "/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
397 \fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
398 .RE
399 .PP
400 \fB\-M\fR, \fB\-\-machine=\fR
401 .RS 4
402 Connect to
403 \fBsystemd-importd.service\fR(8)
404 running in a local container, to perform the specified operation within the container\&.
405 .sp
406 Added in version 256\&.
407 .RE
408 .PP
409 \fB\-\-class=\fR, \fB\-m\fR, \fB\-P\fR, \fB\-S\fR, \fB\-C\fR
410 .RS 4
411 Selects the image class for the downloaded images\&. This primarily selects the directory to download into\&. The
412 \fB\-\-class=\fR
413 switch takes
414 "machine",
415 "portable",
416 "sysext"
417 or
418 "confext"
419 as argument\&. The short options
420 \fB\-m\fR,
421 \fB\-P\fR,
422 \fB\-S\fR,
423 \fB\-C\fR
424 are shortcuts for
425 \fB\-\-class=machine\fR,
426 \fB\-\-class=portable\fR,
427 \fB\-\-class=sysext\fR,
428 \fB\-\-class=confext\fR\&.
429 .sp
430 Note that
431 \fB\-\-keep\-download=\fR
432 defaults to true for
433 \fB\-\-class=machine\fR
434 and false otherwise, see below\&.
435 .sp
436 Added in version 256\&.
437 .RE
438 .PP
439 \fB\-\-keep\-download=\fR, \fB\-N\fR
440 .RS 4
441 Takes a boolean argument\&. When specified with
442 \fBpull\-raw\fR
443 or
444 \fBpull\-tar\fR, selects whether to download directly into the specified local image name, or whether to download into a read\-only copy first of which to make a writable copy after the download is completed\&. Defaults to true for
445 \fB\-\-class=machine\fR, false otherwise\&.
446 .sp
447 The
448 \fB\-N\fR
449 switch is a shortcut for
450 \fB\-\-keep\-download=no\fR\&.
451 .sp
452 Added in version 256\&.
453 .RE
454 .PP
455 \fB\-\-json=\fR\fB\fIMODE\fR\fR
456 .RS 4
457 Shows output formatted as JSON\&. Expects one of
458 "short"
459 (for the shortest possible output without any redundant whitespace or line breaks),
460 "pretty"
461 (for a pretty version of the same, with indentation and line breaks) or
462 "off"
463 (to turn off JSON output, the default)\&.
464 .RE
465 .PP
466 \fB\-j\fR
467 .RS 4
468 Equivalent to
469 \fB\-\-json=pretty\fR
470 if running on a terminal, and
471 \fB\-\-json=short\fR
472 otherwise\&.
473 .RE
474 .PP
475 \fB\-\-no\-pager\fR
476 .RS 4
477 Do not pipe output into a pager\&.
478 .RE
479 .PP
480 \fB\-\-no\-legend\fR
481 .RS 4
482 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
483 .RE
484 .PP
485 \fB\-\-no\-ask\-password\fR
486 .RS 4
487 Do not query the user for authentication for privileged operations\&.
488 .RE
489 .PP
490 \fB\-h\fR, \fB\-\-help\fR
491 .RS 4
492 Print a short help text and exit\&.
493 .RE
494 .PP
495 \fB\-\-version\fR
496 .RS 4
497 Print a short version string and exit\&.
498 .RE
499 .SH "EXAMPLES"
500 .PP
501 \fBExample\ \&1.\ \&Download an Ubuntu TAR image and open a shell in it\fR
502 .sp
503 .if n \{\
504 .RS 4
505 .\}
506 .nf
507 # importctl pull\-tar \-mN https://cloud\-images\&.ubuntu\&.com/jammy/current/jammy\-server\-cloudimg\-amd64\-root\&.tar\&.xz
508 # systemd\-nspawn \-M jammy\-server\-cloudimg\-amd64\-root
509 .fi
510 .if n \{\
511 .RE
512 .\}
513 .PP
514 This downloads and verifies the specified
515 \&.tar
516 image, and then uses
517 \fBsystemd-nspawn\fR(1)
518 to open a shell in it\&.
519 .PP
520 \fBExample\ \&2.\ \&Download an Ubuntu RAW image, set a root password in it, start it as a service\fR
521 .sp
522 .if n \{\
523 .RS 4
524 .\}
525 .nf
526 # importctl pull\-raw \-mN \e
527 https://cloud\-images\&.ubuntu\&.com/jammy/current/jammy\-server\-cloudimg\-amd64\-disk\-kvm\&.img \e
528 jammy
529 # systemd\-firstboot \-\-image=/var/lib/machines/jammy\&.raw \-\-prompt\-root\-password \-\-force
530 # machinectl start jammy
531 # machinectl login jammy
532 .fi
533 .if n \{\
534 .RE
535 .\}
536 .PP
537 This downloads the specified
538 \&.raw
539 image and makes it available under the local name
540 "jammy"\&. Then, a root password is set with
541 \fBsystemd-firstboot\fR(1)\&. Afterwards the machine is started as system service\&. With the last command a login prompt into the container is requested\&.
542 .PP
543 \fBExample\ \&3.\ \&Exports a container image as tar file\fR
544 .sp
545 .if n \{\
546 .RS 4
547 .\}
548 .nf
549 # importctl export\-tar \-m fedora myfedora\&.tar\&.xz
550 .fi
551 .if n \{\
552 .RE
553 .\}
554 .PP
555 Exports the container
556 "fedora"
557 as an xz\-compressed tar file
558 myfedora\&.tar\&.xz
559 into the current directory\&.
560 .SH "EXIT STATUS"
561 .PP
562 On success, 0 is returned, a non\-zero failure code otherwise\&.
563 .SH "ENVIRONMENT"
564 .PP
565 \fI$SYSTEMD_LOG_LEVEL\fR
566 .RS 4
567 The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Takes a comma\-separated list of values\&. A value may be either one of (in order of decreasing importance)
568 \fBemerg\fR,
569 \fBalert\fR,
570 \fBcrit\fR,
571 \fBerr\fR,
572 \fBwarning\fR,
573 \fBnotice\fR,
574 \fBinfo\fR,
575 \fBdebug\fR, or an integer in the range 0\&...7\&. See
576 \fBsyslog\fR(3)
577 for more information\&. Each value may optionally be prefixed with one of
578 \fBconsole\fR,
579 \fBsyslog\fR,
580 \fBkmsg\fR
581 or
582 \fBjournal\fR
583 followed by a colon to set the maximum log level for that specific log target (e\&.g\&.
584 \fBSYSTEMD_LOG_LEVEL=debug,console:info\fR
585 specifies to log at debug level except when logging to the console which should be at info level)\&. Note that the global maximum log level takes priority over any per target maximum log levels\&.
586 .RE
587 .PP
588 \fI$SYSTEMD_LOG_COLOR\fR
589 .RS 4
590 A boolean\&. If true, messages written to the tty will be colored according to priority\&.
591 .sp
592 This setting is only useful when messages are written directly to the terminal, because
593 \fBjournalctl\fR(1)
594 and other tools that display logs will color messages based on the log level on their own\&.
595 .RE
596 .PP
597 \fI$SYSTEMD_LOG_TIME\fR
598 .RS 4
599 A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
600 .sp
601 This setting is only useful when messages are written directly to the terminal or a file, because
602 \fBjournalctl\fR(1)
603 and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
604 .RE
605 .PP
606 \fI$SYSTEMD_LOG_LOCATION\fR
607 .RS 4
608 A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
609 .sp
610 Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
611 .RE
612 .PP
613 \fI$SYSTEMD_LOG_TID\fR
614 .RS 4
615 A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
616 .sp
617 Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
618 .RE
619 .PP
620 \fI$SYSTEMD_LOG_TARGET\fR
621 .RS 4
622 The destination for log messages\&. One of
623 \fBconsole\fR
624 (log to the attached tty),
625 \fBconsole\-prefixed\fR
626 (log to the attached tty but with prefixes encoding the log level and "facility", see
627 \fBsyslog\fR(3),
628 \fBkmsg\fR
629 (log to the kernel circular log buffer),
630 \fBjournal\fR
631 (log to the journal),
632 \fBjournal\-or\-kmsg\fR
633 (log to the journal if available, and to kmsg otherwise),
634 \fBauto\fR
635 (determine the appropriate log target automatically, the default),
636 \fBnull\fR
637 (disable log output)\&.
638 .RE
639 .PP
640 \fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
641 .RS 4
642 Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
643 "true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
644 .RE
645 .PP
646 \fI$SYSTEMD_PAGER\fR, \fI$PAGER\fR
647 .RS 4
648 Pager to use when
649 \fB\-\-no\-pager\fR
650 is not given\&.
651 \fI$SYSTEMD_PAGER\fR
652 is used if set; otherwise
653 \fI$PAGER\fR
654 is used\&. If neither
655 \fI$SYSTEMD_PAGER\fR
656 nor
657 \fI$PAGER\fR
658 are set, a set of well\-known pager implementations is tried in turn, including
659 \fBless\fR(1)
660 and
661 \fBmore\fR(1), until one is found\&. If no pager implementation is discovered, no pager is invoked\&. Setting those environment variables to an empty string or the value
662 "cat"
663 is equivalent to passing
664 \fB\-\-no\-pager\fR\&.
665 .sp
666 Note: if
667 \fI$SYSTEMD_PAGERSECURE\fR
668 is not set,
669 \fI$SYSTEMD_PAGER\fR
670 and
671 \fI$PAGER\fR
672 can only be used to disable the pager (with
673 "cat"
674 or
675 ""), and are otherwise ignored\&.
676 .RE
677 .PP
678 \fI$SYSTEMD_LESS\fR
679 .RS 4
680 Override the options passed to
681 \fBless\fR
682 (by default
683 "FRSXMK")\&.
684 .sp
685 Users might want to change two options in particular:
686 .PP
687 \fBK\fR
688 .RS 4
689 This option instructs the pager to exit immediately when
690 Ctrl+C
691 is pressed\&. To allow
692 \fBless\fR
693 to handle
694 Ctrl+C
695 itself to switch back to the pager command prompt, unset this option\&.
696 .sp
697 If the value of
698 \fI$SYSTEMD_LESS\fR
699 does not include
700 "K", and the pager that is invoked is
701 \fBless\fR,
702 Ctrl+C
703 will be ignored by the executable, and needs to be handled by the pager\&.
704 .RE
705 .PP
706 \fBX\fR
707 .RS 4
708 This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
709 .RE
710 .sp
711 Note that setting the regular
712 \fI$LESS\fR
713 environment variable has no effect for
714 \fBless\fR
715 invocations by systemd tools\&.
716 .sp
717 See
718 \fBless\fR(1)
719 for more discussion\&.
720 .RE
721 .PP
722 \fI$SYSTEMD_LESSCHARSET\fR
723 .RS 4
724 Override the charset passed to
725 \fBless\fR
726 (by default
727 "utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
728 .sp
729 Note that setting the regular
730 \fI$LESSCHARSET\fR
731 environment variable has no effect for
732 \fBless\fR
733 invocations by systemd tools\&.
734 .RE
735 .PP
736 \fI$SYSTEMD_PAGERSECURE\fR
737 .RS 4
738 Common pager commands like
739 \fBless\fR(1), in addition to "paging", i\&.e\&. scrolling through the output, support opening of or writing to other files and running arbitrary shell commands\&. When commands are invoked with elevated privileges, for example under
740 \fBsudo\fR(8)
741 or
742 \fBpkexec\fR(1), the pager becomes a security boundary\&. Care must be taken that only programs with strictly limited functionality are used as pagers, and unintended interactive features like opening or creation of new files or starting of subprocesses are not allowed\&. "Secure mode" for the pager may be enabled as described below,
743 \fIif the pager supports that\fR
744 (most pagers are not written in a way that takes this into consideration)\&. It is recommended to either explicitly enable "secure mode" or to completely disable the pager using
745 \fB\-\-no\-pager\fR
746 or
747 \fIPAGER=cat\fR
748 when allowing untrusted users to execute commands with elevated privileges\&.
749 .sp
750 This option takes a boolean argument\&. When set to true, the "secure mode" of the pager is enabled\&. In "secure mode",
751 \fBLESSSECURE=1\fR
752 will be set when invoking the pager, which instructs the pager to disable commands that open or create new files or start new subprocesses\&. Currently only
753 \fBless\fR(1)
754 is known to understand this variable and implement "secure mode"\&.
755 .sp
756 When set to false, no limitation is placed on the pager\&. Setting
757 \fISYSTEMD_PAGERSECURE=0\fR
758 or not removing it from the inherited environment may allow the user to invoke arbitrary commands\&.
759 .sp
760 When
761 \fI$SYSTEMD_PAGERSECURE\fR
762 is not set, systemd tools attempt to automatically figure out if "secure mode" should be enabled and whether the pager supports it\&. "Secure mode" is enabled if the effective UID is not the same as the owner of the login session, see
763 \fBgeteuid\fR(2)
764 and
765 \fBsd_pid_get_owner_uid\fR(3), or when running under
766 \fBsudo\fR(8)
767 or similar tools (\fI$SUDO_UID\fR
768 is set
769 \&\s-2\u[2]\d\s+2)\&. In those cases,
770 \fISYSTEMD_PAGERSECURE=1\fR
771 will be set and pagers which are not known to implement "secure mode" will not be used at all\&. Note that this autodetection only covers the most common mechanisms to elevate privileges and is intended as convenience\&. It is recommended to explicitly set
772 \fI$SYSTEMD_PAGERSECURE\fR
773 or disable the pager\&.
774 .sp
775 Note that if the
776 \fI$SYSTEMD_PAGER\fR
777 or
778 \fI$PAGER\fR
779 variables are to be honoured, other than to disable the pager,
780 \fI$SYSTEMD_PAGERSECURE\fR
781 must be set too\&.
782 .RE
783 .PP
784 \fI$SYSTEMD_COLORS\fR
785 .RS 4
786 Takes a boolean argument, or a special value\&. By default (unset),
787 \fBsystemd\fR
788 and related utilities will use colors in their output if possible\&. If
789 \fI$COLORTERM\fR
790 is set to
791 "truecolor"
792 or
793 "24bit", 24\-bit colors will be enabled, 256 colors otherwise, unless
794 \fI$NO_COLOR\fR
795 or
796 \fI$TERM\fR
797 indicates colors are disabled\&.
798 .PP
799 \fBtrue\fR
800 .RS 4
801 Same as unset, except that
802 \fI$NO_COLOR\fR
803 is ignored\&.
804 .RE
805 .PP
806 \fBfalse\fR
807 .RS 4
808 The output will be monochrome\&.
809 .RE
810 .PP
811 "16", "256", "24bit"
812 .RS 4
813 Always use the base 16 ANSI colors, 256 colors, or 24 bit color, respectively\&.
814 .RE
815 .PP
816 "auto\-16", "auto\-256", "auto\-24bit"
817 .RS 4
818 Use the given quantity of colours, subject to
819 \fI$TERM\fR, and what the console is connected to\&.
820 .RE
821 .RE
822 .PP
823 \fI$SYSTEMD_URLIFY\fR
824 .RS 4
825 The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
826 \fBsystemd\fR
827 makes based on
828 \fI$TERM\fR
829 and other conditions\&.
830 .RE
831 .SH "SEE ALSO"
832 .PP
833 \fBsystemd\fR(1), \fBsystemd-importd.service\fR(8), \fBsystemd-nspawn\fR(1), \fBsystemd-vmspawn\fR(1), \fBmachinectl\fR(1), \fBportablectl\fR(1), \fBsystemd-sysext\fR(8), \fBsystemd-confext\fR(8), \fBtar\fR(1), \fBxz\fR(1), \fBgzip\fR(1), \fBzstd\fR(1), \fBbzip2\fR(1)
834 .SH "NOTES"
835 .IP " 1." 4
836 HTTP ETag
837 .RS 4
838 \%https://en.wikipedia.org/wiki/HTTP_ETag
839 .RE
840 .IP " 2." 4
841 It is recommended for other tools to set and check
842 \fI$SUDO_UID\fR
843 as appropriate, treating it is a common interface.
844