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