]>
Commit | Line | Data |
---|---|---|
436aa3b1 LP |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> | |
5 | ||
6 | <refentry id="sysupdate.d" conditional='ENABLE_SYSUPDATE' | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | ||
9 | <refentryinfo> | |
10 | <title>sysupdate.d</title> | |
11 | <productname>systemd</productname> | |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>sysupdate.d</refentrytitle> | |
16 | <manvolnum>5</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>sysupdate.d</refname> | |
21 | <refpurpose>Transfer Definition Files for Automatic Updates</refpurpose> | |
22 | </refnamediv> | |
23 | ||
24 | <refsynopsisdiv> | |
73e97bb0 ZJS |
25 | <para><simplelist> |
26 | <member><filename>/etc/sysupdate.d/*.conf</filename></member> | |
27 | <member><filename>/run/sysupdate.d/*.conf</filename></member> | |
28 | <member><filename>/usr/lib/sysupdate.d/*.conf</filename></member> | |
29 | </simplelist></para> | |
436aa3b1 LP |
30 | </refsynopsisdiv> |
31 | ||
32 | <refsect1> | |
33 | <title>Description</title> | |
34 | ||
35 | <para><filename>sysupdate.d/*.conf</filename> files describe how specific resources on the local system | |
36 | shall be updated from a remote source. Each such file defines one such transfer: typically a remote | |
37 | HTTP/HTTPS resource as source; and a local file, directory or partition as target. This may be used as a | |
38 | simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system | |
39 | extension images — but in fact may be used to update any kind of file from a remote source.</para> | |
40 | ||
41 | <para>The | |
42 | <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
43 | command reads these files and uses them to determine which local resources should be updated, and then | |
44 | executes the update.</para> | |
45 | ||
46 | <para>Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent | |
47 | versions, in order to implement flexible update schemes, e.g. A/B updating (or a superset thereof, | |
48 | e.g. A/B/C, A/B/C/D, …).</para> | |
49 | ||
50 | <para>Each <filename>*.conf</filename> file defines one transfer, i.e. describes one resource to | |
51 | update. Typically, multiple of these files (i.e. multiple of such transfers) are defined together, and | |
52 | are bound together by a common version identifier in order to update multiple resources at once on each | |
53 | update operation, for example to update a kernel, a root file system and a Verity partition in a single, | |
54 | combined, synchronized operation, so that only a combined update of all three together constitutes a | |
55 | complete update.</para> | |
56 | ||
57 | <para>Each <filename>*.conf</filename> file contains three sections: [Transfer], [Source] and [Target].</para> | |
58 | </refsect1> | |
59 | ||
60 | <refsect1> | |
61 | <title>Basic Mode of Operation</title> | |
62 | ||
63 | <para>Disk-image based OS updates typically consist of multiple different resources that need to be | |
64 | updated together, for example a secure OS update might consist of a root file system image to drop into a | |
65 | partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the | |
66 | combination of the two partitions. The first two resources are files that are downloaded and placed in a | |
67 | disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file | |
68 | system (e.g. EFI system partition). Hence, during an update of a hypothetical operating system "foobarOS" | |
69 | to a hypothetical version 47 the following operations should take place:</para> | |
70 | ||
71 | <orderedlist> | |
72 | <listitem><para>A file <literal>https://download.example.com/foobarOS_47.root.xz</literal> should be | |
73 | downloaded, decompressed and written to a previously unused partition with GPT partition type UUID | |
74 | 4f68bce3-e8cd-4db1-96e7-fbcaf984b709 for x86-64, as per <ulink | |
db811444 | 75 | url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions |
436aa3b1 LP |
76 | Specification</ulink>.</para></listitem> |
77 | ||
78 | <listitem><para>Similarly, a file <literal>https://download.example.com/foobarOS_47.verity.xz</literal> | |
79 | should be downloaded, decompressed and written to a previously empty partition with GPT partition type | |
6a1d8f11 | 80 | UUID of 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5 (i.e. the partition type for Verity integrity information |
436aa3b1 LP |
81 | for x86-64 root file systems).</para></listitem> |
82 | ||
83 | <listitem><para>Finally, a file <literal>https://download.example.com/foobarOS_47.efi.xz</literal> (a | |
db811444 | 84 | unified kernel, as per <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader |
0470f919 AV |
85 | Specification</ulink> Type #2) should be downloaded, decompressed and written to the $BOOT file system, |
86 | i.e. to <filename>EFI/Linux/foobarOS_47.efi</filename> in the ESP or XBOOTLDR partition.</para></listitem> | |
436aa3b1 LP |
87 | </orderedlist> |
88 | ||
89 | <para>The version-independent generalization of this would be (using the special marker | |
90 | <literal>@v</literal> as wildcard for the version identifier):</para> | |
91 | ||
92 | <orderedlist> | |
93 | <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.root.xz</literal> | |
94 | → a local, previously empty GPT partition of type 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, with the label to | |
95 | be set to <literal>foobarOS_@v</literal>.</para></listitem> | |
96 | ||
97 | <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.verity.xz</literal> | |
98 | → a local, previously empty GPT partition of type 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5, with the label to be | |
99 | set to <literal>foobarOS_@v_verity</literal>.</para></listitem> | |
100 | ||
101 | <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.efi.xz</literal> | |
0470f919 | 102 | → a local file <filename>$BOOT/EFI/Linux/foobarOS_@v.efi</filename>.</para></listitem> |
436aa3b1 LP |
103 | </orderedlist> |
104 | ||
105 | <para>An update can only complete if the relevant URLs provide their resources for the same version, | |
106 | i.e. for the same value of <literal>@v</literal>.</para> | |
107 | ||
108 | <para>The above may be translated into three <filename>*.conf</filename> files in | |
109 | <filename>sysupdate.d/</filename>, one for each resource to transfer. The <filename>*.conf</filename> | |
110 | files configure the type of download, and what place to write the download to (i.e. whether to a | |
111 | partition or a file in the file system). Most importantly these files contain the URL, partition name and | |
112 | filename patterns shown above that describe how these resources are called on the source and how they | |
113 | shall be called on the target.</para> | |
114 | ||
115 | <para>In order to enumerate available versions and figuring out candidates to update to, a mechanism is | |
116 | necessary to list suitable files:</para> | |
117 | ||
118 | <itemizedlist> | |
119 | <listitem><para>For partitions: the surrounding GPT partition table contains a list of defined | |
120 | partitions, including a partition type UUID and a partition label (in this scheme the partition label | |
6a1d8f11 | 121 | plays a role for the partition similar to the filename for a regular file).</para></listitem> |
436aa3b1 LP |
122 | |
123 | <listitem><para>For regular files: the directory listing of the directory the files are contained in | |
124 | provides a list of existing files in a straightforward way.</para></listitem> | |
125 | ||
126 | <listitem><para>For HTTP/HTTPS sources a simple scheme is used: a manifest file | |
127 | <filename>SHA256SUMS</filename>, following the format defined by <citerefentry | |
128 | project='man-pages'><refentrytitle>sha256sum</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
129 | lists file names and their SHA256 hashes.</para></listitem> | |
130 | </itemizedlist> | |
131 | ||
132 | <para>Transfers are done in the alphabetical order of the <filename>.conf</filename> file names they are | |
133 | defined in. First, the resource data is downloaded directly into a target file/directory/partition. Once | |
134 | this is completed for all defined transfers, in a second step the files/directories/partitions are | |
135 | renamed to their final names as defined by the target <varname>MatchPattern=</varname>, again in the | |
136 | order the <filename>.conf</filename> transfer file names dictate. This step is not atomic, however it is | |
137 | guaranteed to be executed strictly in order with suitable disk synchronization in place. Typically, when | |
138 | updating an OS one of the transfers defines the entry point when booting. Thus it is generally a good idea | |
139 | to order the resources via the transfer configuration file names so that the entry point is written | |
140 | last, ensuring that any abnormal termination does not leave an entry point around whose backing is not | |
141 | established yet. In the example above it would hence make sense to establish the EFI kernel image last | |
142 | and thus give its transfer configuration file the alphabetically last name.</para> | |
143 | ||
144 | <para>See below for an extended, more specific example based on the above.</para> | |
145 | </refsect1> | |
146 | ||
147 | <refsect1> | |
148 | <title>Resource Types</title> | |
149 | ||
150 | <para>Each transfer file defines one source resource to transfer to one target resource. The following | |
151 | resource types are supported:</para> | |
152 | ||
153 | <orderedlist> | |
154 | ||
155 | <listitem><para>Resources of type <literal>url-file</literal> encapsulate a file on a web server, | |
156 | referenced via a HTTP or HTTPS URL. When an update takes place, the file is downloaded and decompressed | |
157 | and then written to the target file or partition. This resource type is only available for sources, not | |
158 | for targets. The list of available versions of resources of this type is encoded in | |
159 | <filename>SHA256SUMS</filename> manifest files, accompanied by | |
160 | <filename>SHA256SUMS.gpg</filename> detached signatures.</para></listitem> | |
161 | ||
162 | <listitem><para>The <literal>url-tar</literal> resource type is similar, but the file must be a | |
163 | <filename>.tar</filename> archive. When an update takes place, the file is decompressed and unpacked | |
164 | into a directory or btrfs subvolume. This resource type is only available for sources, not for | |
165 | targets. Just like <literal>url-file</literal>, <literal>url-tar</literal> version enumeration makes | |
166 | use of <filename>SHA256SUMS</filename> files, authenticated via | |
167 | <filename>SHA256SUMS.gpg</filename>.</para></listitem> | |
168 | ||
169 | <listitem><para>The <literal>regular-file</literal> resource type encapsulates a local regular file on | |
170 | disk. During updates the file is uncompressed and written to the target file or partition. This | |
171 | resource type is available both as source and as target. When updating no integrity or authentication | |
172 | verification is done for resources of this type.</para></listitem> | |
173 | ||
174 | <listitem><para>The <literal>partition</literal> resource type is similar to | |
175 | <literal>regular-file</literal>, and encapsulates a GPT partition on disk. When updating, the partition | |
176 | must exist already, and have the correct GPT partition type. A partition whose GPT partition label is | |
177 | set to <literal>_empty</literal> is considered empty, and a candidate to place a newly downloaded | |
178 | resource in. The GPT partition label is used to store version information, once a partition is | |
179 | updated. This resource type is only available for target resources.</para></listitem> | |
180 | ||
181 | <listitem><para>The <literal>tar</literal> resource type encapsulates local <filename>.tar</filename> | |
182 | archive files. When an update takes place, the files are uncompressed and unpacked into a target | |
183 | directory or btrfs subvolume. Behaviour of <literal>tar</literal> and <literal>url-tar</literal> is | |
184 | generally similar, but the latter downloads from remote sources, and does integrity and authentication | |
185 | checks while the former does not. The <literal>tar</literal> resource type is only available for source | |
186 | resources.</para></listitem> | |
187 | ||
188 | <listitem><para>The <literal>directory</literal> resource type encapsulates local directory trees. This | |
189 | type is available both for source and target resources. If an update takes place on a source resource | |
190 | of this type, a recursive copy of the directory is done.</para></listitem> | |
191 | ||
192 | <listitem><para>The <literal>subvolume</literal> resource type is identical to | |
193 | <literal>directory</literal>, except when used as the target, in which case the file tree is placed in | |
194 | a btrfs subvolume instead of a plain directory, if the backing file system supports it (i.e. is | |
195 | btrfs).</para></listitem> | |
196 | </orderedlist> | |
197 | ||
198 | <para>As already indicated, only a subset of source and target resource type combinations are | |
199 | supported:</para> | |
200 | ||
201 | <table> | |
202 | <title>Resource Types</title> | |
203 | ||
204 | <tgroup cols='3' align='left' colsep='1' rowsep='1'> | |
205 | <colspec colname="name" /> | |
206 | <colspec colname="explanation" /> | |
207 | ||
208 | <thead> | |
209 | <row> | |
210 | <entry>Identifier</entry> | |
211 | <entry>Description</entry> | |
212 | <entry>Usable as Source</entry> | |
213 | <entry>When Used as Source: Compatible Targets</entry> | |
214 | <entry>When Used as Source: Integrity + Authentication</entry> | |
215 | <entry>When Used as Source: Decompression</entry> | |
216 | <entry>Usable as Target</entry> | |
217 | <entry>When Used as Target: Compatible Sources</entry> | |
218 | </row> | |
219 | </thead> | |
220 | ||
221 | <tbody> | |
222 | <row> | |
223 | <entry><constant>url-file</constant></entry> | |
224 | <entry>HTTP/HTTPS files</entry> | |
225 | <entry>yes</entry> | |
226 | <entry><constant>regular-file</constant>, <constant>partition</constant></entry> | |
227 | <entry>yes</entry> | |
228 | <entry>yes</entry> | |
229 | <entry>no</entry> | |
230 | <entry>-</entry> | |
231 | </row> | |
232 | ||
233 | <row> | |
234 | <entry><constant>url-tar</constant></entry> | |
235 | <entry>HTTP/HTTPS <filename>.tar</filename> archives</entry> | |
236 | <entry>yes</entry> | |
237 | <entry><constant>directory</constant>, <constant>subvolume</constant></entry> | |
238 | <entry>yes</entry> | |
239 | <entry>yes</entry> | |
240 | <entry>no</entry> | |
241 | <entry>-</entry> | |
242 | </row> | |
243 | ||
244 | <row> | |
245 | <entry><constant>regular-file</constant></entry> | |
246 | <entry>Local files</entry> | |
247 | <entry>yes</entry> | |
248 | <entry><constant>regular-file</constant>, <constant>partition</constant></entry> | |
249 | <entry>no</entry> | |
250 | <entry>yes</entry> | |
251 | <entry>yes</entry> | |
252 | <entry><constant>url-file</constant>, <constant>regular-file</constant></entry> | |
253 | </row> | |
254 | ||
255 | <row> | |
256 | <entry><constant>partition</constant></entry> | |
257 | <entry>Local GPT partitions</entry> | |
258 | <entry>no</entry> | |
259 | <entry>-</entry> | |
260 | <entry>-</entry> | |
261 | <entry>-</entry> | |
262 | <entry>yes</entry> | |
263 | <entry><constant>url-file</constant>, <constant>regular-file</constant></entry> | |
264 | </row> | |
265 | ||
266 | <row> | |
267 | <entry><constant>tar</constant></entry> | |
268 | <entry>Local <filename>.tar</filename> archives</entry> | |
269 | <entry>yes</entry> | |
270 | <entry><constant>directory</constant>, <constant>subvolume</constant></entry> | |
271 | <entry>no</entry> | |
272 | <entry>yes</entry> | |
273 | <entry>no</entry> | |
274 | <entry>-</entry> | |
275 | </row> | |
276 | ||
277 | <row> | |
278 | <entry><constant>directory</constant></entry> | |
279 | <entry>Local directories</entry> | |
280 | <entry>yes</entry> | |
281 | <entry><constant>directory</constant>, <constant>subvolume</constant></entry> | |
282 | <entry>no</entry> | |
283 | <entry>no</entry> | |
284 | <entry>yes</entry> | |
285 | <entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry> | |
286 | </row> | |
287 | ||
288 | <row> | |
289 | <entry><constant>subvolume</constant></entry> | |
290 | <entry>Local btrfs subvolumes</entry> | |
291 | <entry>yes</entry> | |
292 | <entry><constant>directory</constant>, <constant>subvolume</constant></entry> | |
293 | <entry>no</entry> | |
294 | <entry>no</entry> | |
295 | <entry>yes</entry> | |
296 | <entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry> | |
297 | </row> | |
298 | ||
299 | </tbody> | |
300 | </tgroup> | |
301 | </table> | |
302 | </refsect1> | |
303 | ||
304 | <refsect1> | |
305 | <title>Match Patterns</title> | |
306 | ||
307 | <para>Both the source and target resources typically exist in multiple versions concurrently. An update | |
308 | operation is done whenever the newest of the source versions is newer than the newest of the target | |
309 | versions. To determine the newest version of the resources a directory listing, partition listing or | |
310 | manifest listing is used, a subset of qualifying entries selected from that, and the version identifier | |
311 | extracted from the file names or partition labels of these selected entries. Subset selection and | |
312 | extraction of the version identifier (plus potentially other metadata) is done via match patterns, | |
313 | configured in <varname>MatchPattern=</varname> in the [Source] and [Target] sections. These patterns are | |
314 | strings that describe how files or partitions are named, with named wildcards for specific fields such as | |
315 | the version identifier. The following wildcards are defined:</para> | |
316 | ||
317 | <table> | |
318 | <title>Match Pattern Wildcards</title> | |
319 | ||
320 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> | |
321 | <colspec colname="name" /> | |
322 | <colspec colname="explanation" /> | |
323 | ||
324 | <thead> | |
325 | <row> | |
326 | <entry>Wildcard</entry> | |
327 | <entry>Description</entry> | |
328 | <entry>Format</entry> | |
329 | <entry>Notes</entry> | |
330 | </row> | |
331 | </thead> | |
332 | ||
333 | <tbody> | |
334 | <row> | |
335 | <entry><literal>@v</literal></entry> | |
336 | <entry>Version identifier</entry> | |
337 | <entry>Valid version string</entry> | |
338 | <entry>Mandatory</entry> | |
339 | </row> | |
340 | ||
341 | <row> | |
342 | <entry><literal>@u</literal></entry> | |
343 | <entry>GPT partition UUID</entry> | |
344 | <entry>Valid 128-Bit UUID string</entry> | |
345 | <entry>Only relevant if target resource type chosen as <constant>partition</constant></entry> | |
346 | </row> | |
347 | ||
348 | <row> | |
349 | <entry><literal>@f</literal></entry> | |
350 | <entry>GPT partition flags</entry> | |
351 | <entry>Formatted hexadecimal integer</entry> | |
352 | <entry>Only relevant if target resource type chosen as <constant>partition</constant></entry> | |
353 | </row> | |
354 | ||
355 | <row> | |
356 | <entry><literal>@a</literal></entry> | |
357 | <entry>GPT partition flag NoAuto</entry> | |
358 | <entry>Either <literal>0</literal> or <literal>1</literal></entry> | |
db811444 | 359 | <entry>Controls NoAuto bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry> |
436aa3b1 LP |
360 | </row> |
361 | ||
362 | <row> | |
363 | <entry><literal>@g</literal></entry> | |
364 | <entry>GPT partition flag GrowFileSystem</entry> | |
365 | <entry>Either <literal>0</literal> or <literal>1</literal></entry> | |
db811444 | 366 | <entry>Controls GrowFileSystem bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry> |
436aa3b1 LP |
367 | </row> |
368 | ||
369 | <row> | |
370 | <entry><literal>@r</literal></entry> | |
371 | <entry>Read-only flag</entry> | |
372 | <entry>Either <literal>0</literal> or <literal>1</literal></entry> | |
db811444 | 373 | <entry>Controls ReadOnly bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink> and other output read-only flags, see <varname>ReadOnly=</varname> below</entry> |
436aa3b1 LP |
374 | </row> |
375 | ||
376 | <row> | |
377 | <entry><literal>@t</literal></entry> | |
378 | <entry>File modification time</entry> | |
e503019b | 379 | <entry>Formatted decimal integer, μs since UNIX epoch Jan 1st 1970</entry> |
436aa3b1 LP |
380 | <entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry> |
381 | </row> | |
382 | ||
383 | <row> | |
384 | <entry><literal>@m</literal></entry> | |
385 | <entry>File access mode</entry> | |
386 | <entry>Formatted octal integer, in UNIX fashion</entry> | |
387 | <entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry> | |
388 | </row> | |
389 | ||
390 | <row> | |
391 | <entry><literal>@s</literal></entry> | |
392 | <entry>File size after decompression</entry> | |
393 | <entry>Formatted decimal integer</entry> | |
394 | <entry>Useful for measuring progress and to improve partition allocation logic</entry> | |
395 | </row> | |
396 | ||
397 | <row> | |
398 | <entry><literal>@d</literal></entry> | |
399 | <entry>Tries done</entry> | |
400 | <entry>Formatted decimal integer</entry> | |
401 | <entry>Useful when operating with kernel image files, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry> | |
402 | </row> | |
403 | ||
404 | <row> | |
405 | <entry><literal>@l</literal></entry> | |
406 | <entry>Tries left</entry> | |
407 | <entry>Formatted decimal integer</entry> | |
6a1d8f11 | 408 | <entry>Useful when operating with kernel image files, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry> |
436aa3b1 LP |
409 | </row> |
410 | ||
411 | <row> | |
412 | <entry><literal>@h</literal></entry> | |
413 | <entry>SHA256 hash of compressed file</entry> | |
414 | <entry>64 hexadecimal characters</entry> | |
6a1d8f11 | 415 | <entry>The SHA256 hash of the compressed file; not useful for <constant>url-file</constant> or <constant>url-tar</constant> where the SHA256 hash is already included in the manifest file anyway</entry> |
436aa3b1 LP |
416 | </row> |
417 | </tbody> | |
418 | </tgroup> | |
419 | </table> | |
420 | ||
421 | <para>Of these wildcards only <literal>@v</literal> must be present in a valid pattern, all other | |
422 | wildcards are optional. Each wildcard may be used at most once in each pattern. A typical wildcard | |
423 | matching a file system source image could be <literal>MatchPattern=foobar_@v.raw.xz</literal>, i.e. any file | |
424 | whose name begins with <literal>foobar_</literal>, followed by a version ID and suffixed by | |
425 | <literal>.raw.xz</literal>.</para> | |
426 | ||
427 | <para>Do not confuse the <literal>@</literal> pattern matching wildcard prefix with the | |
428 | <literal>%</literal> specifier expansion prefix. The former encapsulate a variable part of a match | |
429 | pattern string, the latter are simple shortcuts that are expanded while the drop-in files are | |
430 | parsed. For details about specifiers, see below.</para> | |
431 | </refsect1> | |
432 | ||
433 | <refsect1> | |
434 | <title>[Transfer] Section Options</title> | |
435 | ||
8b9f0921 | 436 | <para>This section defines general properties of this transfer.</para> |
436aa3b1 LP |
437 | |
438 | <variablelist> | |
439 | <varlistentry> | |
440 | <term><varname>MinVersion=</varname></term> | |
441 | ||
442 | <listitem><para>Specifies the minimum version to require for this transfer to take place. If the | |
443 | source or target patterns in this transfer definition match files older than this version they will | |
ec07c3c8 AK |
444 | be considered obsolete, and never be considered for the update operation.</para> |
445 | ||
446 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
447 | </varlistentry> |
448 | ||
449 | <varlistentry> | |
450 | <term><varname>ProtectVersion=</varname></term> | |
451 | ||
452 | <listitem><para>Takes one or more version strings to mark as "protected". Protected versions are | |
453 | never removed while making room for new, updated versions. This is useful to ensure that the | |
454 | currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten | |
455 | during updates, in order to avoid runtime file system corruptions.</para> | |
456 | ||
457 | <para>Like many of the settings in these configuration files this setting supports specifier | |
458 | expansion. It's particularly useful to set this setting to one of the <literal>%A</literal>, | |
459 | <literal>%B</literal> or <literal>%w</literal> specifiers to automatically refer to the current OS | |
ec07c3c8 AK |
460 | version of the running system. See below for details on supported specifiers.</para> |
461 | ||
462 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
463 | </varlistentry> |
464 | ||
465 | <varlistentry> | |
466 | <term><varname>Verify=</varname></term> | |
467 | ||
468 | <listitem><para>Takes a boolean, defaults to yes. Controls whether to cryptographically verify | |
469 | downloaded resources (specifically: validate the GPG signatures for downloaded | |
470 | <filename>SHA256SUMS</filename> manifest files, via their detached signature files | |
471 | <filename>SHA256SUMS.gpg</filename> in combination with the system keyring | |
472 | <filename>/usr/lib/systemd/import-pubring.gpg</filename> or | |
473 | <filename>/etc/systemd/import-pubring.gpg</filename>).</para> | |
474 | ||
475 | <para>This option is essential to provide integrity guarantees for downloaded resources and thus | |
476 | should be left enabled, outside of test environments.</para> | |
477 | ||
478 | <para>Note that the downloaded payload files are unconditionally checked against the SHA256 hashes | |
479 | listed in the manifest. This option only controls whether the signatures of these manifests are | |
480 | verified.</para> | |
481 | ||
482 | <para>This option only has an effect if the source resource type is selected as | |
483 | <constant>url-file</constant> or <constant>url-tar</constant>, as integrity and authentication | |
ec07c3c8 AK |
484 | checking is only available for transfers from remote sources.</para> |
485 | ||
486 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
487 | </varlistentry> |
488 | ||
489 | </variablelist> | |
490 | </refsect1> | |
491 | ||
492 | <refsect1> | |
493 | <title>[Source] Section Options</title> | |
494 | ||
8b9f0921 | 495 | <para>This section defines properties of the transfer source.</para> |
436aa3b1 LP |
496 | |
497 | <variablelist> | |
498 | <varlistentry> | |
499 | <term><varname>Type=</varname></term> | |
500 | ||
501 | <listitem><para>Specifies the resource type of the source for the transfer. Takes one of | |
502 | <constant>url-file</constant>, <constant>url-tar</constant>, <constant>tar</constant>, | |
503 | <constant>regular-file</constant>, <constant>directory</constant> or | |
504 | <constant>subvolume</constant>. For details about the resource types, see above. This option is | |
505 | mandatory.</para> | |
506 | ||
8fb35004 | 507 | <para>Note that only certain combinations of source and target resource types are supported, see |
ec07c3c8 AK |
508 | above.</para> |
509 | ||
510 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
511 | </varlistentry> |
512 | </variablelist> | |
513 | ||
514 | <variablelist> | |
515 | <varlistentry> | |
516 | <term><varname>Path=</varname></term> | |
517 | ||
518 | <listitem><para>Specifies where to find source versions of this resource.</para> | |
519 | ||
520 | <para>If the source type is selected as <constant>url-file</constant> or | |
521 | <constant>url-tar</constant> this must be a HTTP/HTTPS URL. The URL is suffixed with | |
522 | <filename>/SHA256SUMS</filename> to acquire the manifest file, with | |
523 | <filename>/SHA256SUMS.gpg</filename> to acquire the detached signature file for it, and with the file | |
524 | names listed in the manifest file in case an update is executed and a resource shall be | |
525 | downloaded.</para> | |
526 | ||
527 | <para>For all other source resource types this must be a local path in the file system, referring to | |
ec07c3c8 AK |
528 | a local directory to find the versions of this resource in.</para> |
529 | ||
530 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
531 | </varlistentry> |
532 | ||
533 | <varlistentry> | |
534 | <term><varname>MatchPattern=</varname></term> | |
535 | ||
536 | <listitem><para>Specifies one or more file name match patterns that select the subset of files that | |
537 | are update candidates as source for this transfer. See above for details on match patterns.</para> | |
538 | ||
539 | <para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal> | |
540 | wildcard, so that a version identifier may be extracted from the filename. All other wildcards are | |
ec07c3c8 AK |
541 | optional.</para> |
542 | ||
deafbeb0 VD |
543 | <para>If the source type is <constant>regular-file</constant> or <constant>directory</constant>, the |
544 | pattern may contain slash characters. In this case it will match the file or directory in | |
545 | corresponding subdirectory. For example <literal>MatchPattern=foo_@v/bar.efi</literal> will match | |
546 | <literal>bar.efi</literal> in directory <literal>foo_1</literal>. </para> | |
547 | ||
ec07c3c8 | 548 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> |
436aa3b1 LP |
549 | </varlistentry> |
550 | </variablelist> | |
551 | </refsect1> | |
552 | ||
553 | <refsect1> | |
554 | <title>[Target] Section Options</title> | |
555 | ||
8b9f0921 | 556 | <para>This section defines properties of the transfer target.</para> |
436aa3b1 LP |
557 | |
558 | <variablelist> | |
559 | <varlistentry> | |
560 | <term><varname>Type=</varname></term> | |
561 | ||
562 | <listitem><para>Specifies the resource type of the target for the transfer. Takes one of | |
563 | <constant>partition</constant>, <constant>regular-file</constant>, <constant>directory</constant> or | |
564 | <constant>subvolume</constant>. For details about the resource types, see above. This option is | |
565 | mandatory.</para> | |
566 | ||
8b9f0921 | 567 | <para>Note that only certain combinations of source and target resource types are supported, see |
ec07c3c8 AK |
568 | above.</para> |
569 | ||
570 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
571 | </varlistentry> |
572 | ||
573 | <varlistentry> | |
574 | <term><varname>Path=</varname></term> | |
575 | ||
576 | <listitem><para>Specifies a file system path where to look for already installed versions or place | |
577 | newly downloaded versions of this configured resource. If <varname>Type=</varname> is set to | |
578 | <constant>partition</constant>, expects a path to a (whole) block device node, or the special string | |
6a1d8f11 JJ |
579 | <literal>auto</literal> in which case the block device which contains the root file system of the |
580 | currently booted system is automatically determined and used. If <varname>Type=</varname> is set to | |
436aa3b1 LP |
581 | <constant>regular-file</constant>, <constant>directory</constant> or <constant>subvolume</constant>, |
582 | must refer to a path in the local file system referencing the directory to find or place the version | |
583 | files or directories under.</para> | |
584 | ||
585 | <para>Note that this mechanism cannot be used to create or remove partitions, in case | |
586 | <varname>Type=</varname> is set to <constant>partition</constant>. Partitions must exist already, and | |
587 | a special partition label <literal>_empty</literal> is used to indicate empty partitions. To | |
588 | automatically generate suitable partitions on first boot, use a tool such as | |
ec07c3c8 AK |
589 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> |
590 | ||
591 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
592 | </varlistentry> |
593 | ||
0470f919 AV |
594 | <varlistentry> |
595 | <term><varname>PathRelativeTo=</varname></term> | |
596 | ||
597 | <listitem><para>Specifies what partition <varname>Path=</varname> should be relative to. Takes one of | |
598 | <constant>root</constant>, <constant>esp</constant>, <constant>xbootldr</constant>, or <constant>boot</constant>. | |
599 | If unspecified, defaults to <constant>root</constant>.</para> | |
600 | ||
601 | <para>If set to <constant>boot</constant>, the specified <varname>Path=</varname> will be resolved | |
602 | relative to the mount point of the $BOOT partition (i.e. the ESP or XBOOTLDR), as defined by the | |
603 | <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader | |
604 | Specification</ulink>.</para> | |
605 | ||
606 | <para>The values <constant>esp</constant>, <constant>xbootldr</constant>, and | |
607 | <constant>boot</constant> are only supported when <varname>Type=</varname> is set to | |
ec07c3c8 AK |
608 | <constant>regular-file</constant> or <constant>directory</constant>.</para> |
609 | ||
610 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
0470f919 AV |
611 | </varlistentry> |
612 | ||
436aa3b1 LP |
613 | <varlistentry> |
614 | <term><varname>MatchPattern=</varname></term> | |
615 | ||
616 | <listitem><para>Specifies one or more file name or partition label match patterns that select the | |
617 | subset of files or partitions that are update candidates as targets for this transfer. See above for | |
618 | details on match patterns.</para> | |
619 | ||
620 | <para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal> | |
621 | wildcard, so that a version identifier may be extracted from the filename. All other wildcards are | |
622 | optional.</para> | |
623 | ||
624 | <para>This pattern is both used for matching existing installed versions and for determining the name | |
625 | of new versions to install. If multiple patterns are specified, the first specified is used for | |
ec07c3c8 AK |
626 | naming newly installed versions.</para> |
627 | ||
deafbeb0 VD |
628 | <para>If the target type is <constant>regular-file</constant> or <constant>directory</constant>, the |
629 | pattern may contain slash characters. In this case it will match the file or directory in | |
630 | corresponding subdirectory. For example <literal>MatchPattern=foo_@v/bar.efi</literal> will match | |
631 | <literal>bar.efi</literal> in directory <literal>foo_1</literal>. Directories in the path will be | |
632 | created when file is installed. Empty directories will be removed when file is removed.</para> | |
633 | ||
ec07c3c8 | 634 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> |
436aa3b1 LP |
635 | </varlistentry> |
636 | ||
637 | <varlistentry> | |
638 | <term><varname>MatchPartitionType=</varname></term> | |
639 | ||
640 | <listitem><para>When the target <varname>Type=</varname> is chosen as <constant>partition</constant>, | |
641 | specifies the GPT partition type to look for. Only partitions of this type are considered, all other | |
642 | partitions are ignored. If not specified, the GPT partition type <constant>linux-generic</constant> | |
643 | is used. Accepts either a literal type UUID or a symbolic type identifier. For a list of supported | |
644 | type identifiers, see the <varname>Type=</varname> setting in | |
ec07c3c8 AK |
645 | <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> |
646 | ||
647 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
648 | </varlistentry> |
649 | ||
650 | <varlistentry> | |
651 | <term><varname>PartitionUUID=</varname></term> | |
652 | <term><varname>PartitionFlags=</varname></term> | |
653 | <term><varname>PartitionNoAuto=</varname></term> | |
654 | <term><varname>PartitionGrowFileSystem=</varname></term> | |
655 | ||
656 | <listitem><para>When the target <varname>Type=</varname> is picked as <constant>partition</constant>, | |
657 | selects the GPT partition UUID and partition flags to use for the updated partition. Expects a valid | |
658 | UUID string, a hexadecimal integer, or booleans, respectively. If not set, but the source match | |
659 | pattern includes wildcards for these fields (i.e. <literal>@u</literal>, <literal>@f</literal>, | |
660 | <literal>@a</literal>, or <literal>@g</literal>), the values from the patterns are used. If neither | |
661 | configured with wildcards or these explicit settings, the values are left untouched. If both the | |
662 | overall <varname>PartitionFlags=</varname> flags setting and the individual flag settings | |
663 | <varname>PartitionNoAuto=</varname> and <varname>PartitionGrowFileSystem=</varname> are used (or the | |
664 | wildcards for them), then the latter override the former, i.e. the individual flag bit overrides the | |
db811444 | 665 | overall flags value. See <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable |
436aa3b1 LP |
666 | Partitions Specification</ulink> for details about these flags.</para> |
667 | ||
668 | <para>Note that these settings are not used for matching, they only have effect on newly written | |
ec07c3c8 AK |
669 | partitions in case a transfer takes place.</para> |
670 | ||
671 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
672 | </varlistentry> |
673 | ||
674 | <varlistentry> | |
675 | <term><varname>ReadOnly=</varname></term> | |
676 | ||
677 | <listitem><para>Controls whether to mark the resulting file, subvolume or partition read-only. If the | |
678 | target type is <constant>partition</constant> this controls the ReadOnly partition flag, as per | |
db811444 | 679 | <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions |
436aa3b1 LP |
680 | Specification</ulink>, similar to the <varname>PartitionNoAuto=</varname> and |
681 | <varname>PartitionGrowFileSystem=</varname> flags described above. If the target type is | |
8b9f0921 | 682 | <constant>regular-file</constant>, the writable bit is removed from the access mode. If the |
436aa3b1 LP |
683 | target type is <constant>subvolume</constant>, the subvolume will be marked read-only as a |
684 | whole. Finally, if the target <varname>Type=</varname> is selected as <constant>directory</constant>, | |
685 | the "immutable" file attribute is set, see <citerefentry | |
686 | project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry> for | |
ec07c3c8 AK |
687 | details.</para> |
688 | ||
689 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
690 | </varlistentry> |
691 | ||
692 | <varlistentry> | |
693 | <term><varname>Mode=</varname></term> | |
694 | ||
695 | <listitem><para>The UNIX file access mode to use for newly created files in case the target resource | |
696 | type is picked as <constant>regular-file</constant>. Expects an octal integer, in typical UNIX | |
697 | fashion. If not set, but the source match pattern includes a wildcard for this field | |
698 | (i.e. <literal>@t</literal>), the value from the pattern is used.</para> | |
699 | ||
700 | <para>Note that this setting is not used for matching, it only has an effect on newly written | |
ec07c3c8 AK |
701 | files when a transfer takes place.</para> |
702 | ||
703 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
704 | </varlistentry> |
705 | ||
706 | <varlistentry> | |
707 | <term><varname>TriesDone=</varname></term> | |
708 | <term><varname>TriesLeft=</varname></term> | |
709 | ||
710 | <listitem><para>These options take positive, decimal integers, and control the number of attempts | |
711 | done and left for this file. These settings are useful for managing kernel images, following the | |
712 | scheme defined in <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot | |
713 | Assessment</ulink>, and only have an effect if the target pattern includes the <literal>@d</literal> | |
ec07c3c8 AK |
714 | or <literal>@l</literal> wildcards.</para> |
715 | ||
716 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
717 | </varlistentry> |
718 | ||
719 | <varlistentry> | |
720 | <term><varname>InstancesMax=</varname></term> | |
721 | ||
722 | <listitem><para>Takes a decimal integer equal to or greater than 2. This configures how many concurrent | |
723 | versions of the resource to keep. Whenever a new update is initiated it is made sure that no more | |
724 | than the number of versions specified here minus one exist in the target. Any excess versions are | |
725 | deleted (in case the target <varname>Type=</varname> of <constant>regular-file</constant>, | |
726 | <constant>directory</constant>, <constant>subvolume</constant> is used) or emptied (in case the | |
727 | target <varname>Type=</varname> of <constant>partition</constant> is used; emptying in this case | |
728 | simply means to set the partition label to the special string <literal>_empty</literal>; note that no | |
729 | partitions are actually removed). After an update is completed the number of concurrent versions of | |
730 | the target resources is equal to or below the number specified here.</para> | |
731 | ||
732 | <para>Note that this setting may be set differently for each transfer. However, it generally is | |
733 | advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of | |
734 | files or partitions will be left installed.</para> | |
735 | ||
736 | <para>If the target <varname>Type=</varname> is selected as <constant>partition</constant>, the number | |
737 | of concurrent versions to keep is additionally restricted by the number of partition slots of the | |
8b9f0921 | 738 | right type in the partition table. I.e. if there are only 2 partition slots for the selected |
436aa3b1 | 739 | partition type, setting this value larger than 2 is without effect, since no more than 2 concurrent |
ec07c3c8 AK |
740 | versions could be stored in the image anyway.</para> |
741 | ||
742 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
743 | </varlistentry> |
744 | ||
745 | <varlistentry> | |
746 | <term><varname>RemoveTemporary=</varname></term> | |
747 | ||
748 | <listitem><para>Takes a boolean argument. If this option is enabled (which is the default) before | |
749 | initiating an update, all left-over, incomplete updates from a previous attempt are removed from the | |
750 | target directory. This only has an effect if the target resource <varname>Type=</varname> is selected | |
751 | as <constant>regular-file</constant>, <constant>directory</constant> or | |
ec07c3c8 AK |
752 | <constant>subvolume</constant>.</para> |
753 | ||
754 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
755 | </varlistentry> |
756 | ||
757 | <varlistentry> | |
758 | <term><varname>CurrentSymlink=</varname></term> | |
759 | ||
760 | <listitem><para>Takes a symlink name as argument. If this option is used, as the last step of the | |
761 | update a symlink under the specified name is created/updated pointing to the completed update. This | |
762 | is useful in to provide a stable name always pointing to the newest version of the resource. This is | |
763 | only supported if the target resource <varname>Type=</varname> is selected as | |
764 | <constant>regular-file</constant>, <constant>directory</constant> or | |
ec07c3c8 AK |
765 | <constant>subvolume</constant>.</para> |
766 | ||
767 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
768 | </varlistentry> |
769 | ||
770 | </variablelist> | |
771 | </refsect1> | |
772 | ||
773 | <refsect1> | |
774 | <title>Specifiers</title> | |
775 | ||
776 | <para>Specifiers may be used in the <varname>MinVersion=</varname>, <varname>ProtectVersion=</varname>, | |
777 | <varname>Path=</varname>, <varname>MatchPattern=</varname> and <varname>CurrentSymlink=</varname> | |
778 | settings. The following expansions are understood:</para> | |
779 | <table class='specifiers'> | |
780 | <title>Specifiers available</title> | |
781 | <tgroup cols='3' align='left' colsep='1' rowsep='1'> | |
782 | <colspec colname="spec" /> | |
783 | <colspec colname="mean" /> | |
784 | <colspec colname="detail" /> | |
785 | <thead> | |
786 | <row> | |
787 | <entry>Specifier</entry> | |
788 | <entry>Meaning</entry> | |
789 | <entry>Details</entry> | |
790 | </row> | |
791 | </thead> | |
792 | <tbody> | |
793 | <xi:include href="standard-specifiers.xml" xpointer="a"/> | |
794 | <xi:include href="standard-specifiers.xml" xpointer="A"/> | |
795 | <xi:include href="standard-specifiers.xml" xpointer="b"/> | |
796 | <xi:include href="standard-specifiers.xml" xpointer="B"/> | |
797 | <xi:include href="standard-specifiers.xml" xpointer="H"/> | |
798 | <xi:include href="standard-specifiers.xml" xpointer="l"/> | |
799 | <xi:include href="standard-specifiers.xml" xpointer="m"/> | |
800 | <xi:include href="standard-specifiers.xml" xpointer="M"/> | |
801 | <xi:include href="standard-specifiers.xml" xpointer="o"/> | |
802 | <xi:include href="standard-specifiers.xml" xpointer="v"/> | |
803 | <xi:include href="standard-specifiers.xml" xpointer="w"/> | |
804 | <xi:include href="standard-specifiers.xml" xpointer="W"/> | |
805 | <xi:include href="standard-specifiers.xml" xpointer="T"/> | |
806 | <xi:include href="standard-specifiers.xml" xpointer="V"/> | |
807 | <xi:include href="standard-specifiers.xml" xpointer="percent"/> | |
808 | </tbody> | |
809 | </tgroup> | |
810 | </table> | |
811 | ||
812 | <para>Do not confuse the <literal>%</literal> specifier expansion prefix with the <literal>@</literal> | |
813 | pattern matching wildcard prefix. The former are simple shortcuts that are expanded while the drop-in | |
814 | files are parsed, the latter encapsulate a variable part of a match pattern string. For details about | |
815 | pattern matching wildcards, see above.</para> | |
816 | </refsect1> | |
817 | ||
818 | <refsect1> | |
819 | <title>Examples</title> | |
820 | ||
821 | <example> | |
822 | <title>Updates for a Verity Enabled Secure OS</title> | |
823 | ||
824 | <para>With the following three files we define a root file system partition, a matching Verity | |
825 | partition, and a unified kernel image to update as one. This example is an extension of the example | |
826 | discussed earlier in this man page.</para> | |
827 | ||
828 | <para><programlisting># /usr/lib/sysupdate.d/50-verity.conf | |
829 | [Transfer] | |
830 | ProtectVersion=%A | |
831 | ||
832 | [Source] | |
833 | Type=url-file | |
834 | Path=https://download.example.com/ | |
835 | MatchPattern=foobarOS_@v_@u.verity.xz | |
836 | ||
837 | [Target] | |
838 | Type=partition | |
839 | Path=auto | |
840 | MatchPattern=foobarOS_@v_verity | |
841 | MatchPartitionType=root-verity | |
842 | PartitionFlags=0 | |
76d2b8da | 843 | ReadOnly=1</programlisting></para> |
436aa3b1 LP |
844 | |
845 | <para>The above defines the update mechanism for the Verity partition of the root file system. Verity | |
846 | partition images are downloaded from | |
847 | <literal>https://download.example.com/foobarOS_@v_@u.verity.xz</literal> and written to a suitable | |
848 | local partition, which is marked read-only. Under the assumption this update is run from the image | |
849 | itself the current image version (i.e. the <literal>%A</literal> specifier) is marked as protected, to | |
850 | ensure it is not corrupted while booted. Note that the partition UUID for the target partition is | |
851 | encoded in the source file name. Fixating the partition UUID can be useful to ensure that | |
852 | <literal>roothash=</literal> on the kernel command line is sufficient to pinpoint both the Verity and | |
853 | root file system partition, and also encode the Verity root level hash (under the assumption the UUID | |
854 | in the file names match their top-level hash, the way | |
855 | <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
856 | suggests).</para> | |
857 | ||
858 | <para><programlisting># /usr/lib/sysupdate.d/60-root.conf | |
859 | [Transfer] | |
860 | ProtectVersion=%A | |
861 | ||
862 | [Source] | |
863 | Type=url-file | |
864 | Path=https://download.example.com/ | |
865 | MatchPattern=foobarOS_@v_@u.root.xz | |
866 | ||
867 | [Target] | |
868 | Type=partition | |
869 | Path=auto | |
870 | MatchPattern=foobarOS_@v | |
871 | MatchPartitionType=root | |
872 | PartitionFlags=0 | |
76d2b8da | 873 | ReadOnly=1</programlisting></para> |
436aa3b1 LP |
874 | |
875 | <para>The above defines a matching transfer definition for the root file system.</para> | |
876 | ||
877 | <para><programlisting># /usr/lib/sysupdate.d/70-kernel.conf | |
878 | [Transfer] | |
879 | ProtectVersion=%A | |
880 | ||
881 | [Source] | |
882 | Type=url-file | |
883 | Path=https://download.example.com/ | |
884 | MatchPattern=foobarOS_@v.efi.xz | |
885 | ||
886 | [Target] | |
0ad7b7b8 | 887 | Type=regular-file |
0470f919 AV |
888 | Path=/EFI/Linux |
889 | PathRelativeTo=boot | |
436aa3b1 LP |
890 | MatchPattern=foobarOS_@v+@l-@d.efi \ |
891 | foobarOS_@v+@l.efi \ | |
892 | foobarOS_@v.efi | |
893 | Mode=0444 | |
894 | TriesLeft=3 | |
895 | TriesDone=0 | |
896 | InstancesMax=2</programlisting></para> | |
897 | ||
0470f919 AV |
898 | <para>The above installs a unified kernel image into the $BOOT partition, as per |
899 | <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader | |
900 | Specification</ulink> Type #2. This defines three possible patterns for the names of the kernel | |
901 | images, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink>, | |
902 | and ensures when installing new kernels, they are set up with 3 tries left. No more than two parallel | |
903 | kernels are kept.</para> | |
436aa3b1 LP |
904 | |
905 | <para>With this setup the web server would serve the following files, for a hypothetical version 7 of | |
906 | the OS:</para> | |
907 | ||
908 | <itemizedlist> | |
909 | <listitem><para><filename>SHA256SUMS</filename> – The manifest file, containing available files and their SHA256 hashes</para></listitem> | |
910 | <listitem><para><filename>SHA256SUMS.gpg</filename> – The detached cryptographic signature for the manifest file</para></listitem> | |
911 | <listitem><para><filename>foobarOS_7_8b8186b1-2b4e-4eb6-ad39-8d4d18d2a8fb.verity.xz</filename> – The Verity image for version 7</para></listitem> | |
912 | <listitem><para><filename>foobarOS_7_f4d1234f-3ebf-47c4-b31d-4052982f9a2f.root.xz</filename> – The root file system image for version 7</para></listitem> | |
913 | <listitem><para><filename>foobarOS_7_efi.xz</filename> – The unified kernel image for version 7</para></listitem> | |
914 | </itemizedlist> | |
915 | ||
916 | <para>For each new OS release a new set of the latter three files would be added, each time with an | |
917 | updated version. The <filename>SHA256SUMS</filename> manifest should then be updated accordingly, | |
918 | listing all files for all versions that shall be offered for download.</para> | |
919 | </example> | |
920 | ||
921 | <example> | |
922 | <title>Updates for Plain Directory Container Image</title> | |
923 | ||
924 | <para><programlisting> | |
925 | [Source] | |
926 | Type=url-tar | |
927 | Path=https://download.example.com/ | |
928 | MatchPattern=myContainer_@v.tar.gz | |
929 | ||
930 | [Target] | |
931 | Type=subvolume | |
932 | Path=/var/lib/machines | |
933 | MatchPattern=myContainer_@v | |
934 | CurrentSymlink=myContainer</programlisting></para> | |
935 | ||
936 | <para>On updates this downloads <literal>https://download.example.com/myContainer_@v.tar.gz</literal> | |
937 | and decompresses/unpacks it to <filename>/var/lib/machines/myContainer_@v</filename>. After each update | |
938 | a symlink <filename>/var/lib/machines/myContainer</filename> is created/updated always pointing to the | |
939 | most recent update.</para> | |
940 | </example> | |
941 | </refsect1> | |
942 | ||
943 | <refsect1> | |
944 | <title>See Also</title> | |
945 | <para> | |
946 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
947 | <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
948 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
949 | </para> | |
950 | </refsect1> | |
951 | ||
952 | </refentry> |