Debian Codegraph @

upstream/debian-trixie/man8/systemd-import-generator.8

raw
1 '\" t
2 .TH "SYSTEMD\-IMPORT\-GENERATOR" "8" "" "systemd 257.13" "systemd-import-generator"
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 systemd-import-generator \- Generator for automatically downloading disk images at boot
24 .SH "SYNOPSIS"
25 .PP
26 /usr/lib/systemd/system\-generators/systemd\-import\-generator
27 .SH "DESCRIPTION"
28 .PP
29 \fBsystemd\-import\-generator\fR
30 may be used to automatically download disk images (tarballs or DDIs) via
31 \fBsystemd-importd.service\fR(8)
32 at boot, based on parameters on the kernel command line or via system credentials\&. This is useful for automatically deploying an
33 \fBsystemd-confext\fR(8),
34 \fBsystemd-sysext\fR(8),
35 \fBsystemd-nspawn\fR(1)/
36 \fBsystemd-vmspawn\fR(1)
37 or
38 \fBsystemd-portabled.service\fR(8)
39 image at boot\&. This provides functionality equivalent to
40 \fBimportctl\fR(1), but accessible via the kernel command line and system credentials\&.
41 .PP
42 systemd\-import\-generator
43 implements
44 \fBsystemd.generator\fR(7)\&.
45 .SH "KERNEL COMMAND LINE"
46 .PP
47 systemd\-import\-generator
48 understands the following
49 \fBkernel-command-line\fR(7)
50 parameters:
51 .PP
52 \fIsystemd\&.pull=\fR
53 .RS 4
54 This option takes a colon separate triplet of option string, local target image name and remote URL\&. The local target image name can be specified as an empty string, in which case the name is derived from the specified remote URL\&. The remote URL must using the
55 "http://",
56 "https://",
57 "file://"
58 schemes\&. The option string itself is a comma separated list of options:
59 .PP
60 rw, ro
61 .RS 4
62 Controls whether to mark the local image as read\-only\&. If not specified read\-only defaults to off\&.
63 .sp
64 Added in version 257\&.
65 .RE
66 .PP
67 verify=
68 .RS 4
69 Controls whether to cryptographically validate the download before installing it in place\&. Takes one of
70 "no",
71 "checksum", or
72 "signature"
73 (the default if not specified)\&. For details see the
74 \fB\-\-verify=\fR
75 of
76 \fBimportctl\fR(1)\&.
77 .sp
78 Added in version 257\&.
79 .RE
80 .PP
81 sysext, confext, machine, portable
82 .RS 4
83 Controls the image class to download, and thus ultimately the target directory for the image, depending on this choice the target directory
84 /var/lib/extensions/,
85 /var/lib/confexts/,
86 /var/lib/machines/
87 or
88 /var/lib/portables/
89 is selected\&.
90 .sp
91 Specification of exactly one of these options is mandatory\&.
92 .sp
93 Added in version 257\&.
94 .RE
95 .PP
96 tar, raw
97 .RS 4
98 Controls the type of resource to download, i\&.e\&. a (possibly compressed) tarball that needs to be unpacked into a file system tree, or (possibly compressed) raw disk image (DDI)\&.
99 .sp
100 Specification of exactly one of these options is mandatory\&.
101 .sp
102 Added in version 257\&.
103 .RE
104 .sp
105 Added in version 257\&.
106 .RE
107 .PP
108 \fIsystemd\&.pull\&.success_action=\fR, \fIsystemd\&.pull\&.failure_action=\fR
109 .RS 4
110 Controls whether to execute an action such as reboot, power\-off and similar after completing the download successfully, or unsuccessfully\&. See
111 \fISuccessAction=\fR/\fIFailureAction=\fR
112 on
113 \fBsystemd.unit\fR(5)
114 for details about the available actions\&. If not specified, no action is taken, and the system will continue to boot normally\&.
115 .sp
116 Added in version 257\&.
117 .RE
118 .SH "CREDENTIALS"
119 .PP
120 \fBsystemd\-import\-generator\fR
121 supports the system credentials logic\&. The following credentials are used when passed in:
122 .PP
123 \fIimport\&.pull\fR
124 .RS 4
125 This credential should be a text file, with each line referencing one download operation\&. Each line should follow the same format as the value of the
126 \fIsystemd\&.pull=\fR
127 kernel command line option described above\&.
128 .sp
129 Added in version 257\&.
130 .RE
131 .SH "EXAMPLES"
132 .PP
133 \fBExample\ \&1.\ \&Download Configuration Extension\fR
134 .sp
135 .if n \{\
136 .RS 4
137 .\}
138 .nf
139 systemd\&.pull=raw,confext::https://example\&.com/myconfext\&.raw\&.gz
140 .fi
141 .if n \{\
142 .RE
143 .\}
144 .PP
145 With a kernel command line option like the above a configuration extension DDI is downloaded automatically at boot from the specified URL, validated cryptographically, uncompressed and installed\&.
146 .PP
147 \fBExample\ \&2.\ \&Download System Extension (Without Validation)\fR
148 .sp
149 .if n \{\
150 .RS 4
151 .\}
152 .nf
153 systemd\&.pull=tar,sysext,verify=no::https://example\&.com/mysysext\&.tar\&.gz
154 .fi
155 .if n \{\
156 .RE
157 .\}
158 .PP
159 With a kernel command line option like the above a system extension tarball is downloaded automatically at boot from the specified URL, uncompressed and installed \(en without any cryptographic validation\&. This is useful for development purposes in virtual machines and containers\&. Warning: do not deploy a system with validation disabled like this!
160 .SH "SEE ALSO"
161 .PP
162 \fBsystemd\fR(1), \fBsystemd-importd.service\fR(8), \fBkernel-command-line\fR(7), \fBsystemd.system-credentials\fR(7), \fBimportctl\fR(1)