Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-IMPORT\-GENERATOR" "8" "" "systemd 261~rc3" "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 .PP
105 blockdev
106 .RS 4
107 If this option is specified the downloaded image is attached to a loopback block device (via
108 systemd\-loop@\&.service) after completion\&. This permits booting from downloaded disk images\&. This is only supported for
109 "raw"
110 disk images\&.
111 .sp
112 Note when this option is used with the purpose of mounting a disk image conforming to the
113 \m[blue]\fBUAPI\&.3 Discoverable Disk Image Specification\fR\m[]\&\s-2\u[1]\d\s+2
114 as root file system, and the automatic GPT partition discovery logic as implemented by
115 \fBsystemd-gpt-auto-generator\fR(8)
116 shall process it, it\*(Aqs essential to specify
117 "rootdisk"
118 as the local name for the import\&. Moreover,
119 "root=gpt\-auto"
120 must be specified on the kernel command line explicitly\&. Also, prefix the
121 "systemd\&.pull="
122 command line option with
123 "rd\&."
124 to ensure it is executed in the initial RAM disk (initrd) already, also see below\&.
125 .sp
126 Added in version 258\&.
127 .RE
128 .PP
129 bootorigin
130 .RS 4
131 If this option is specified, in place of the URL a simple filename may be specified\&. If the system is booted via UEFI HTTP network booting the last component of the network boot origin URL is replaced by this filename and used as download source\&. This hence allows one to automatically derive the URLs for disk images from the original boot URL used to invoke the kernel or boot loader\&.
132 .sp
133 If this option is used and the system is not actually booted via UEFI HTTP network booting, the download is gracefully skipped\&. Or in other words without other modifications it is possible to put together an initrd image that will boot from a local disk if available, or from downloaded disk image if used via network booting\&.
134 .sp
135 Added in version 258\&.
136 .RE
137 .PP
138 runtime=
139 .RS 4
140 Takes a boolean argument\&. If set to true, the image is downloaded below the
141 /run/
142 hierarchy, if set to false below the
143 /var/lib/
144 hierarchy\&. If not specified defaults to true in the initial RAM disk (initrd) and to false on the host system\&.
145 .sp
146 Added in version 258\&.
147 .RE
148 .sp
149 Added in version 257\&.
150 .RE
151 .PP
152 \fIsystemd\&.pull\&.success_action=\fR, \fIsystemd\&.pull\&.failure_action=\fR
153 .RS 4
154 Controls whether to execute an action such as reboot, power\-off and similar after completing the download successfully, or unsuccessfully\&. See
155 \fISuccessAction=\fR/\fIFailureAction=\fR
156 on
157 \fBsystemd.unit\fR(5)
158 for details about the available actions\&. If not specified, no action is taken, and the system will continue to boot normally\&.
159 .sp
160 Added in version 257\&.
161 .RE
162 .PP
163 These kernel command line options are interpreted by the host system only\&. If these options are prefixed with
164 "rd\&."
165 they are interpreted by the initial RAM disk (initrd) instead\&.
166 .SH "CREDENTIALS"
167 .PP
168 \fBsystemd\-import\-generator\fR
169 supports the system credentials logic\&. The following credentials are used when passed in:
170 .PP
171 \fIimport\&.pull\fR
172 .RS 4
173 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
174 \fIsystemd\&.pull=\fR
175 kernel command line option described above\&.
176 .sp
177 Added in version 257\&.
178 .RE
179 .SH "EXAMPLES"
180 .PP
181 \fBExample\ \&1.\ \&Download Configuration Extension\fR
182 .sp
183 .if n \{\
184 .RS 4
185 .\}
186 .nf
187 systemd\&.pull=raw,confext::https://example\&.com/myconfext\&.raw\&.gz
188 .fi
189 .if n \{\
190 .RE
191 .\}
192 .PP
193 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\&.
194 .PP
195 \fBExample\ \&2.\ \&Download System Extension (Without Validation)\fR
196 .sp
197 .if n \{\
198 .RS 4
199 .\}
200 .nf
201 systemd\&.pull=tar,sysext,verify=no::https://example\&.com/mysysext\&.tar\&.gz
202 .fi
203 .if n \{\
204 .RE
205 .\}
206 .PP
207 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!
208 .PP
209 \fBExample\ \&3.\ \&Download root disk image (raw) into memory, for booting into it\fR
210 .sp
211 .if n \{\
212 .RS 4
213 .\}
214 .nf
215 rd\&.systemd\&.pull=raw,machine,verify=no,blockdev:image:https://example\&.com/image\&.raw\&.xz root=/dev/disk/by\-loop\-ref/image\&.raw\-part2
216 .fi
217 .if n \{\
218 .RE
219 .\}
220 .PP
221 This downloads the specified disk image, saving it locally under the name
222 "image", and attaches it to a loopback block device on completion\&. It then boots from the 2nd partition in the image\&.
223 .PP
224 \fBExample\ \&4.\ \&Boot into disk image (raw), with URL derived from UEFI HTTP network booting\fR
225 .sp
226 .if n \{\
227 .RS 4
228 .\}
229 .nf
230 rd\&.systemd\&.pull=raw,machine,verify=no,blockdev,bootorigin:rootdisk:image\&.raw\&.xz root=gpt\-auto
231 .fi
232 .if n \{\
233 .RE
234 .\}
235 .PP
236 This is similar to the previous example, but this time the source URL is automatically derived from the UEFI HTTP network boot URL\&. For example, if an UKI is booted from an URL
237 "http://example\&.com/image\&.efi"
238 this would result in a root disk being downloaded from
239 "http://example\&.com/image\&.raw\&.xz"\&. Moreover this uses the
240 \fBsystemd-gpt-auto-generator\fR(8)
241 logic to mount the root file system from the disk image\&.
242 .PP
243 \fBExample\ \&5.\ \&Boot into disk image (tar), with URL derived from UEFI HTTP network booting\fR
244 .sp
245 .if n \{\
246 .RS 4
247 .\}
248 .nf
249 rd\&.systemd\&.pull=tar,machine,verify=no,bootorigin:root:image\&.tar\&.xz root=bind:/run/machines/root
250 .fi
251 .if n \{\
252 .RE
253 .\}
254 .PP
255 This is similar to the previous example, but instead of a raw (i\&.e\&. block device based) disk image the system boots into a tarball that is downloaded from the originating UEFI network server\&.
256 .SH "SEE ALSO"
257 .PP
258 \fBsystemd\fR(1), \fBsystemd-importd.service\fR(8), \fBkernel-command-line\fR(7), \fBsystemd.system-credentials\fR(7), \fBimportctl\fR(1), \[email protected]\fR(8), \fBsystemd-gpt-auto-generator\fR(8)
259 .SH "NOTES"
260 .IP " 1." 4
261 UAPI.3 Discoverable Disk Image Specification
262 .RS 4
263 \%https://uapi-group.org/specifications/specs/discoverable_disk_image/
264 .RE