Debian Codegraph @

upstream/debian-unstable/man5/sysupdate.d.5

raw
1 '\" t
2 .TH "SYSUPDATE\&.D" "5" "" "systemd 261~rc3" "sysupdate.d"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sysupdate.d \- Transfer Definition Files for Automatic Updates
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 /etc/sysupdate\&.d/*\&.transfer
28 .RE
29 .RS 4
30 /run/sysupdate\&.d/*\&.transfer
31 .RE
32 .RS 4
33 /usr/local/lib/sysupdate\&.d/*\&.transfer
34 .RE
35 .RS 4
36 /usr/lib/sysupdate\&.d/*\&.transfer
37 .RE
38 .SH "DESCRIPTION"
39 .PP
40 These files describe how specific resources on the local system shall be updated from a remote source\&. Each such file defines one such transfer: typically a remote HTTP/HTTPS resource as source; and a local file, directory or partition as target\&. This may be used as a simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system extension images \(em but in fact may be used to update any kind of file from a remote source\&.
41 .PP
42 The
43 \fBsystemd-sysupdate\fR(8)
44 command reads these files and uses them to determine which local resources should be updated, and then executes the update\&.
45 .PP
46 Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent versions, in order to implement flexible update schemes, e\&.g\&. A/B updating (or a superset thereof, e\&.g\&. A/B/C, A/B/C/D, \&...)\&.
47 .PP
48 Each
49 *\&.transfer
50 file defines one transfer, i\&.e\&. describes one resource to update\&. Typically, multiple of these files (i\&.e\&. multiple of such transfers) are defined together, and are bound together by a common version identifier in order to update multiple resources at once on each update operation, for example to update a kernel, a root file system and a Verity partition in a single, combined, synchronized operation, so that only a combined update of all three together constitutes a complete update\&. We\*(Aqll call such a collection of transfers a target\&.
51 \fBsystemd-sysupdate\fR(8)
52 always operates on a single target\&.
53 .PP
54 Transfers may be grouped together into sets that can be individually enabled or disabled by the system administrator, called "Optional Features":
55 \fBsysupdate.features\fR(5)\&.
56 .PP
57 Each
58 *\&.transfer
59 file contains three sections: [Transfer], [Source] and [Target]\&.
60 .SH "BASIC MODE OF OPERATION"
61 .PP
62 Disk\-image based OS updates typically consist of multiple different resources that need to be updated together, for example a secure OS update might consist of a root file system image to drop into a partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the combination of the two partitions\&. The first two resources are files that are downloaded and placed in a disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file system (e\&.g\&. EFI system partition)\&. Hence, during an update of a hypothetical operating system "foobarOS" to a hypothetical version 47 the following operations should take place:
63 .sp
64 .RS 4
65 .ie n \{\
66 \h'-04' 1.\h'+01'\c
67 .\}
68 .el \{\
69 .sp -1
70 .IP " 1." 4.2
71 .\}
72 A file
73 "https://download\&.example\&.com/foobarOS_47\&.root\&.xz"
74 should be downloaded, decompressed and written to a previously unused partition with GPT partition type UUID 4f68bce3\-e8cd\-4db1\-96e7\-fbcaf984b709 for x86\-64, as per
75 \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
76 .RE
77 .sp
78 .RS 4
79 .ie n \{\
80 \h'-04' 2.\h'+01'\c
81 .\}
82 .el \{\
83 .sp -1
84 .IP " 2." 4.2
85 .\}
86 Similarly, a file
87 "https://download\&.example\&.com/foobarOS_47\&.verity\&.xz"
88 should be downloaded, decompressed and written to a previously empty partition with GPT partition type UUID of 2c7357ed\-ebd2\-46d9\-aec1\-23d437ec2bf5 (i\&.e\&. the partition type for Verity integrity information for x86\-64 root file systems)\&.
89 .RE
90 .sp
91 .RS 4
92 .ie n \{\
93 \h'-04' 3.\h'+01'\c
94 .\}
95 .el \{\
96 .sp -1
97 .IP " 3." 4.2
98 .\}
99 Finally, a file
100 "https://download\&.example\&.com/foobarOS_47\&.efi"
101 (a unified kernel, as per
102 \m[blue]\fBUAPI\&.1 Boot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
103 Type #2) should be downloaded, decompressed and written to the $BOOT file system, i\&.e\&. to
104 EFI/Linux/foobarOS_47\&.efi
105 in the ESP or XBOOTLDR partition\&.
106 .RE
107 .PP
108 The version\-independent generalization of this would be (using the special marker
109 "@v"
110 as wildcard for the version identifier):
111 .sp
112 .RS 4
113 .ie n \{\
114 \h'-04' 1.\h'+01'\c
115 .\}
116 .el \{\
117 .sp -1
118 .IP " 1." 4.2
119 .\}
120 A transfer of a file
121 "https://download\&.example\&.com/foobarOS_@v\&.root\&.xz"
122 → a local, previously empty GPT partition of type 4f68bce3\-e8cd\-4db1\-96e7\-fbcaf984b709, with the label to be set to
123 "foobarOS_@v"\&.
124 .RE
125 .sp
126 .RS 4
127 .ie n \{\
128 \h'-04' 2.\h'+01'\c
129 .\}
130 .el \{\
131 .sp -1
132 .IP " 2." 4.2
133 .\}
134 A transfer of a file
135 "https://download\&.example\&.com/foobarOS_@v\&.verity\&.xz"
136 → a local, previously empty GPT partition of type 2c7357ed\-ebd2\-46d9\-aec1\-23d437ec2bf5, with the label to be set to
137 "foobarOS_@v_verity"\&.
138 .RE
139 .sp
140 .RS 4
141 .ie n \{\
142 \h'-04' 3.\h'+01'\c
143 .\}
144 .el \{\
145 .sp -1
146 .IP " 3." 4.2
147 .\}
148 A transfer of a file
149 "https://download\&.example\&.com/foobarOS_@v\&.efi"
150 → a local file
151 $BOOT/EFI/Linux/foobarOS_@v\&.efi\&.
152 .RE
153 .PP
154 An update can only complete if the relevant URLs provide their resources for the same version, i\&.e\&. for the same value of
155 "@v"\&.
156 .PP
157 The above may be translated into three
158 *\&.transfer
159 files in
160 sysupdate\&.d/, one for each resource to transfer\&. The
161 *\&.transfer
162 files configure the type of download, and what place to write the download to (i\&.e\&. whether to a partition or a file in the file system)\&. Most importantly these files contain the URL, partition name and filename patterns shown above that describe how these resources are called on the source and how they shall be called on the target\&.
163 .PP
164 In order to enumerate available versions and figuring out candidates to update to, a mechanism is necessary to list suitable files:
165 .sp
166 .RS 4
167 .ie n \{\
168 \h'-04'\(bu\h'+03'\c
169 .\}
170 .el \{\
171 .sp -1
172 .IP \(bu 2.3
173 .\}
174 For partitions: the surrounding GPT partition table contains a list of defined partitions, including a partition type UUID and a partition label (in this scheme the partition label plays a role for the partition similar to the filename for a regular file)\&.
175 .RE
176 .sp
177 .RS 4
178 .ie n \{\
179 \h'-04'\(bu\h'+03'\c
180 .\}
181 .el \{\
182 .sp -1
183 .IP \(bu 2.3
184 .\}
185 For regular files: the directory listing of the directory the files are contained in provides a list of existing files in a straightforward way\&.
186 .RE
187 .sp
188 .RS 4
189 .ie n \{\
190 \h'-04'\(bu\h'+03'\c
191 .\}
192 .el \{\
193 .sp -1
194 .IP \(bu 2.3
195 .\}
196 For HTTP/HTTPS sources a simple scheme is used: a manifest file
197 SHA256SUMS, following the format defined by
198 \fBsha256sum\fR(1), lists file names and their SHA256 hashes\&.
199 .RE
200 .PP
201 Transfers are done in the alphabetical order of the
202 \&.transfer
203 file names they are defined in\&. First, the resource data is downloaded directly into a target file/directory/partition\&. Once this is completed for all defined transfers, in a second step the files/directories/partitions are renamed to their final names as defined by the target
204 \fIMatchPattern=\fR, again in the order the
205 \&.transfer
206 transfer file names dictate\&. This step is not atomic, however it is guaranteed to be executed strictly in order with suitable disk synchronization in place\&. Typically, when updating an OS one of the transfers defines the entry point when booting\&. Thus it is generally a good idea to order the resources via the transfer configuration file names so that the entry point is written last, ensuring that any abnormal termination does not leave an entry point around whose backing is not established yet\&. In the example above it would hence make sense to establish the EFI kernel image last and thus give its transfer configuration file the alphabetically last name\&.
207 .PP
208 See below for an extended, more specific example based on the above\&.
209 .SH "RESOURCE TYPES"
210 .PP
211 Each transfer file defines one source resource to transfer to one target resource\&. The following resource types are supported:
212 .sp
213 .RS 4
214 .ie n \{\
215 \h'-04' 1.\h'+01'\c
216 .\}
217 .el \{\
218 .sp -1
219 .IP " 1." 4.2
220 .\}
221 Resources of type
222 "url\-file"
223 encapsulate a file on a web server, referenced via a HTTP or HTTPS URL\&. When an update takes place, the file is downloaded and decompressed and then written to the target file or partition\&. This resource type is only available for sources, not for targets\&. The list of available versions of resources of this type is encoded in
224 SHA256SUMS
225 manifest files, accompanied by
226 SHA256SUMS\&.gpg
227 detached signatures\&.
228 .RE
229 .sp
230 .RS 4
231 .ie n \{\
232 \h'-04' 2.\h'+01'\c
233 .\}
234 .el \{\
235 .sp -1
236 .IP " 2." 4.2
237 .\}
238 The
239 "url\-tar"
240 resource type is similar, but the file must be a
241 \&.tar
242 archive\&. When an update takes place, the file is decompressed and unpacked into a directory or btrfs subvolume\&. This resource type is only available for sources, not for targets\&. Just like
243 "url\-file",
244 "url\-tar"
245 version enumeration makes use of
246 SHA256SUMS
247 files, authenticated via
248 SHA256SUMS\&.gpg\&.
249 .RE
250 .sp
251 .RS 4
252 .ie n \{\
253 \h'-04' 3.\h'+01'\c
254 .\}
255 .el \{\
256 .sp -1
257 .IP " 3." 4.2
258 .\}
259 The
260 "regular\-file"
261 resource type encapsulates a local regular file on disk\&. During updates the file is uncompressed and written to the target file or partition\&. This resource type is available both as source and as target\&. When updating no integrity or authentication verification is done for resources of this type\&.
262 .RE
263 .sp
264 .RS 4
265 .ie n \{\
266 \h'-04' 4.\h'+01'\c
267 .\}
268 .el \{\
269 .sp -1
270 .IP " 4." 4.2
271 .\}
272 The
273 "partition"
274 resource type is similar to
275 "regular\-file", and encapsulates a GPT partition on disk\&. When updating, the partition must exist already, and have the correct GPT partition type\&. A partition whose GPT partition label is set to
276 "_empty"
277 is considered empty, and a candidate to place a newly downloaded resource in\&. The GPT partition label is used to store version information, once a partition is updated\&. This resource type is only available for target resources\&.
278 .RE
279 .sp
280 .RS 4
281 .ie n \{\
282 \h'-04' 5.\h'+01'\c
283 .\}
284 .el \{\
285 .sp -1
286 .IP " 5." 4.2
287 .\}
288 The
289 "tar"
290 resource type encapsulates local
291 \&.tar
292 archive files\&. When an update takes place, the files are uncompressed and unpacked into a target directory or btrfs subvolume\&. Behaviour of
293 "tar"
294 and
295 "url\-tar"
296 is generally similar, but the latter downloads from remote sources, and does integrity and authentication checks while the former does not\&. The
297 "tar"
298 resource type is only available for source resources\&.
299 .RE
300 .sp
301 .RS 4
302 .ie n \{\
303 \h'-04' 6.\h'+01'\c
304 .\}
305 .el \{\
306 .sp -1
307 .IP " 6." 4.2
308 .\}
309 The
310 "directory"
311 resource type encapsulates local directory trees\&. This type is available both for source and target resources\&. If an update takes place on a source resource of this type, a recursive copy of the directory is done\&.
312 .RE
313 .sp
314 .RS 4
315 .ie n \{\
316 \h'-04' 7.\h'+01'\c
317 .\}
318 .el \{\
319 .sp -1
320 .IP " 7." 4.2
321 .\}
322 The
323 "subvolume"
324 resource type is identical to
325 "directory", except when used as the target, in which case the file tree is placed in a btrfs subvolume instead of a plain directory, if the backing file system supports it (i\&.e\&. is btrfs)\&.
326 .RE
327 .PP
328 As already indicated, only a subset of source and target resource type combinations are supported:
329 .sp
330 .it 1 an-trap
331 .nr an-no-space-flag 1
332 .nr an-break-flag 1
333 .br
334 .B Table\ \&1.\ \&Resource Types
335 .TS
336 allbox tab(:);
337 lB lB lB lB lB lB lB lB.
338 T{
339 Identifier
340 T}:T{
341 Description
342 T}:T{
343 Usable as Source
344 T}:T{
345 When Used as Source: Compatible Targets
346 T}:T{
347 When Used as Source: Integrity + Authentication
348 T}:T{
349 When Used as Source: Decompression
350 T}:T{
351 Usable as Target
352 T}:T{
353 When Used as Target: Compatible Sources
354 T}
355 .T&
356 l l l l l l l l
357 l l l l l l l l
358 l l l l l l l l
359 l l l l l l l l
360 l l l l l l l l
361 l l l l l l l l
362 l l l l l l l l.
363 T{
364 \fBurl\-file\fR
365 T}:T{
366 HTTP/HTTPS files
367 T}:T{
368 yes
369 T}:T{
370 \fBregular\-file\fR, \fBpartition\fR
371 T}:T{
372 yes
373 T}:T{
374 yes
375 T}:T{
376 no
377 T}:T{
378 \-
379 T}
380 T{
381 \fBurl\-tar\fR
382 T}:T{
383 HTTP/HTTPS \&.tar archives
384 T}:T{
385 yes
386 T}:T{
387 \fBdirectory\fR, \fBsubvolume\fR
388 T}:T{
389 yes
390 T}:T{
391 yes
392 T}:T{
393 no
394 T}:T{
395 \-
396 T}
397 T{
398 \fBregular\-file\fR
399 T}:T{
400 Local files
401 T}:T{
402 yes
403 T}:T{
404 \fBregular\-file\fR, \fBpartition\fR
405 T}:T{
406 no
407 T}:T{
408 yes
409 T}:T{
410 yes
411 T}:T{
412 \fBurl\-file\fR, \fBregular\-file\fR
413 T}
414 T{
415 \fBpartition\fR
416 T}:T{
417 Local GPT partitions
418 T}:T{
419 no
420 T}:T{
421 \-
422 T}:T{
423 \-
424 T}:T{
425 \-
426 T}:T{
427 yes
428 T}:T{
429 \fBurl\-file\fR, \fBregular\-file\fR
430 T}
431 T{
432 \fBtar\fR
433 T}:T{
434 Local \&.tar archives
435 T}:T{
436 yes
437 T}:T{
438 \fBdirectory\fR, \fBsubvolume\fR
439 T}:T{
440 no
441 T}:T{
442 yes
443 T}:T{
444 no
445 T}:T{
446 \-
447 T}
448 T{
449 \fBdirectory\fR
450 T}:T{
451 Local directories
452 T}:T{
453 yes
454 T}:T{
455 \fBdirectory\fR, \fBsubvolume\fR
456 T}:T{
457 no
458 T}:T{
459 no
460 T}:T{
461 yes
462 T}:T{
463 \fBurl\-tar\fR, \fBtar\fR, \fBdirectory\fR, \fBsubvolume\fR
464 T}
465 T{
466 \fBsubvolume\fR
467 T}:T{
468 Local btrfs subvolumes
469 T}:T{
470 yes
471 T}:T{
472 \fBdirectory\fR, \fBsubvolume\fR
473 T}:T{
474 no
475 T}:T{
476 no
477 T}:T{
478 yes
479 T}:T{
480 \fBurl\-tar\fR, \fBtar\fR, \fBdirectory\fR, \fBsubvolume\fR
481 T}
482 .TE
483 .sp 1
484 .PP
485 The
486 SHA256SUMS
487 manifest files used by
488 "url\-file"
489 and
490 "url\-tar"
491 resource types follow the usual file format generated by GNU\*(Aqs
492 \fBsha256sum\fR(1)
493 tool\&. It is recommended to use
494 \fB\-\-binary\fR
495 mode, even if that has no real effect on Linux systems\&. The listing should only contain ASCII characters, and only regular file names (i\&.e\&. no absolute or relative paths)\&. If the
496 SHA256SUMS
497 listing contains a special file
498 "BEST\-BEFORE\-YYYY\-MM\-DD"
499 (with the year, month, day filled in), then the file listing will not be considered valid past the specified date, and the transfer will fail in such a case\&. This may be used to detect "freshness" of the manifest file\&.
500 .SH "MATCH PATTERNS"
501 .PP
502 Both the source and target resources typically exist in multiple versions concurrently\&. An update operation is done whenever the newest of the source versions is newer than the newest of the target versions\&. To determine the newest version of the resources a directory listing, partition listing or manifest listing is used, a subset of qualifying entries selected from that, and the version identifier extracted from the file names or partition labels of these selected entries\&. Subset selection and extraction of the version identifier (plus potentially other metadata) is done via match patterns, configured in
503 \fIMatchPattern=\fR
504 in the [Source] and [Target] sections\&. These patterns are strings that describe how files or partitions are named, with named wildcards for specific fields such as the version identifier\&. The following wildcards are defined:
505 .sp
506 .it 1 an-trap
507 .nr an-no-space-flag 1
508 .nr an-break-flag 1
509 .br
510 .B Table\ \&2.\ \&Match Pattern Wildcards
511 .TS
512 allbox tab(:);
513 lB lB lB lB.
514 T{
515 Wildcard
516 T}:T{
517 Description
518 T}:T{
519 Format
520 T}:T{
521 Notes
522 T}
523 .T&
524 l l l l
525 l l l l
526 l l l l
527 l l l l
528 l l l l
529 l l l l
530 l l l l
531 l l l l
532 l l l l
533 l l l l
534 l l l l
535 l l l l.
536 T{
537 "@v"
538 T}:T{
539 Version identifier
540 T}:T{
541 Valid version string
542 T}:T{
543 Mandatory
544 T}
545 T{
546 "@u"
547 T}:T{
548 GPT partition UUID
549 T}:T{
550 Valid 128\-Bit UUID string
551 T}:T{
552 Only relevant if target resource type chosen as \fBpartition\fR
553 T}
554 T{
555 "@f"
556 T}:T{
557 GPT partition flags
558 T}:T{
559 Formatted hexadecimal integer
560 T}:T{
561 Only relevant if target resource type chosen as \fBpartition\fR
562 T}
563 T{
564 "@a"
565 T}:T{
566 GPT partition flag NoAuto
567 T}:T{
568 Either "0" or "1"
569 T}:T{
570 Controls NoAuto bit of the GPT partition flags, as per \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2; only relevant if target resource type chosen as \fBpartition\fR
571 T}
572 T{
573 "@g"
574 T}:T{
575 GPT partition flag GrowFileSystem
576 T}:T{
577 Either "0" or "1"
578 T}:T{
579 Controls GrowFileSystem bit of the GPT partition flags, as per \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2; only relevant if target resource type chosen as \fBpartition\fR
580 T}
581 T{
582 "@r"
583 T}:T{
584 Read\-only flag
585 T}:T{
586 Either "0" or "1"
587 T}:T{
588 Controls ReadOnly bit of the GPT partition flags, as per \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2 and other output read\-only flags, see \fIReadOnly=\fR below
589 T}
590 T{
591 "@t"
592 T}:T{
593 File modification time
594 T}:T{
595 Formatted decimal integer, μs since UNIX epoch Jan 1st 1970
596 T}:T{
597 Only relevant if target resource type chosen as \fBregular\-file\fR
598 T}
599 T{
600 "@m"
601 T}:T{
602 File access mode
603 T}:T{
604 Formatted octal integer, in UNIX fashion
605 T}:T{
606 Only relevant if target resource type chosen as \fBregular\-file\fR
607 T}
608 T{
609 "@s"
610 T}:T{
611 File size after decompression
612 T}:T{
613 Formatted decimal integer
614 T}:T{
615 Useful for measuring progress and to improve partition allocation logic
616 T}
617 T{
618 "@d"
619 T}:T{
620 Tries done
621 T}:T{
622 Formatted decimal integer
623 T}:T{
624 Useful when operating with kernel image files, as per \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[3]\d\s+2
625 T}
626 T{
627 "@l"
628 T}:T{
629 Tries left
630 T}:T{
631 Formatted decimal integer
632 T}:T{
633 Useful when operating with kernel image files, as per \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[3]\d\s+2
634 T}
635 T{
636 "@h"
637 T}:T{
638 SHA256 hash of compressed file
639 T}:T{
640 64 hexadecimal characters
641 T}:T{
642 The SHA256 hash of the compressed file; not useful for \fBurl\-file\fR or \fBurl\-tar\fR where the SHA256 hash is already included in the manifest file anyway
643 T}
644 .TE
645 .sp 1
646 .PP
647 Of these wildcards only
648 "@v"
649 must be present in a valid pattern, all other wildcards are optional\&. Each wildcard may be used at most once in each pattern\&. A typical wildcard matching a file system source image could be
650 "MatchPattern=foobar_@v\&.raw\&.xz", i\&.e\&. any file whose name begins with
651 "foobar_", followed by a version ID and suffixed by
652 "\&.raw\&.xz"\&.
653 .PP
654 Do not confuse the
655 "@"
656 pattern matching wildcard prefix with the
657 "%"
658 specifier expansion prefix\&. The former encapsulate a variable part of a match pattern string, the latter are simple shortcuts that are expanded while the drop\-in files are parsed\&. For details about specifiers, see below\&.
659 .SH "[TRANSFER] SECTION OPTIONS"
660 .PP
661 This section defines general properties of this transfer\&.
662 .PP
663 \fIMinVersion=\fR
664 .RS 4
665 Specifies the minimum version to require for this transfer to take place\&. If the source or target patterns in this transfer definition match files older than this version they will be considered obsolete, and never be considered for the update operation\&.
666 .sp
667 Added in version 251\&.
668 .RE
669 .PP
670 \fIProtectVersion=\fR
671 .RS 4
672 Takes one or more version strings to mark as "protected"\&. Protected versions are never removed while making room for new, updated versions\&. This is useful to ensure that the currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten during updates, in order to avoid runtime file system corruptions\&.
673 .sp
674 Like many of the settings in these configuration files this setting supports specifier expansion\&. It\*(Aqs particularly useful to set this setting to one of the
675 "%A",
676 "%B"
677 or
678 "%w"
679 specifiers to automatically refer to the current OS version of the running system\&. See below for details on supported specifiers\&.
680 .sp
681 Added in version 251\&.
682 .RE
683 .PP
684 \fIVerify=\fR
685 .RS 4
686 Takes a boolean, defaults to yes\&. Controls whether to cryptographically verify downloaded resources (specifically: validate the GPG signatures for downloaded
687 SHA256SUMS
688 manifest files, via their detached signature files
689 SHA256SUMS\&.gpg
690 in combination with the system keyring
691 /usr/lib/systemd/import\-pubring\&.pgp
692 or
693 /etc/systemd/import\-pubring\&.pgp)\&.
694 .sp
695 This option is essential to provide integrity guarantees for downloaded resources and thus should be left enabled, outside of test environments\&.
696 .sp
697 Note that the downloaded payload files are unconditionally checked against the SHA256 hashes listed in the manifest\&. This option only controls whether the signatures of these manifests are verified\&.
698 .sp
699 This option only has an effect if the source resource type is selected as
700 \fBurl\-file\fR
701 or
702 \fBurl\-tar\fR, as integrity and authentication checking is only available for transfers from remote sources\&.
703 .sp
704 Added in version 251\&.
705 .RE
706 .PP
707 \fIChangeLog=\fR
708 .RS 4
709 Optionally takes a human\-presentable URL to a website containing a change\-log of the resource being updated\&.
710 .sp
711 This may be set multiple times in a single transfer definition\&. If set multiple times, the values are gathered into a list of URLs\&. Adding a value of the empty string will clear the existing list of all values\&.
712 .sp
713 This setting supports specifier expansion\&. See below for details on supported specifiers\&. This setting will also expand the
714 "@v"
715 wildcard pattern\&. See above for details\&.
716 .sp
717 Added in version 257\&.
718 .RE
719 .PP
720 \fIAppStream=\fR
721 .RS 4
722 Optionally takes a URL to an
723 \m[blue]\fBAppStream catalog\fR\m[]\&\s-2\u[4]\d\s+2
724 XML file\&. This may be used by software centers (such as GNOME Software or KDE Discover) to present rich metadata about the resources being updated\&. This includes display names, changelogs, icons, and more\&. The specified catalog must include
725 \m[blue]\fBspecial metadata\fR\m[]\&\s-2\u[5]\d\s+2
726 to be correctly associated with
727 \fBsystemd-sysupdate\fR(8)
728 by the software centers\&.
729 .sp
730 This setting supports specifier expansion\&. See below for details on supported specifiers\&.
731 .sp
732 Added in version 257\&.
733 .RE
734 .PP
735 \fIFeatures=\fR
736 .RS 4
737 A space\-separated list of
738 \fBsysupdate.features\fR(5)
739 that this transfer belongs to, by name\&. This option may be specified more than once, in which case the specified list of features is merged\&. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect\&. For example:
740 "Features=foo bar"
741 specifies that the transfer belongs to
742 "foo\&.feature"
743 and
744 "bar\&.feature"\&.
745 .sp
746 If the list of features is empty, then this transfer is always used\&. If this transfer belongs to more than one feature, then it will be used if
747 \fIany\fR
748 one of the listed features is enabled\&. A name that does not correspond to a defined feature will resolve to an implicit feature that is always disabled\&.
749 .sp
750 Added in version 257\&.
751 .RE
752 .PP
753 \fIRequisiteFeatures=\fR
754 .RS 4
755 This is like
756 \fIFeatures=\fR, except that
757 \fIall\fR
758 features listed here must be enabled for this transfer to be enabled\&. If both options are specified, then they both apply: the transfer will be enabled only if all features specified here are enabled, and at least one feature listed in
759 \fIFeatures=\fR
760 is enabled\&.
761 .sp
762 Added in version 257\&.
763 .RE
764 .SH "[SOURCE] SECTION OPTIONS"
765 .PP
766 This section defines properties of the transfer source\&.
767 .PP
768 \fIType=\fR
769 .RS 4
770 Specifies the resource type of the source for the transfer\&. Takes one of
771 \fBurl\-file\fR,
772 \fBurl\-tar\fR,
773 \fBtar\fR,
774 \fBregular\-file\fR,
775 \fBdirectory\fR
776 or
777 \fBsubvolume\fR\&. For details about the resource types, see above\&. This option is mandatory\&.
778 .sp
779 Note that only certain combinations of source and target resource types are supported, see above\&.
780 .sp
781 Added in version 251\&.
782 .RE
783 .PP
784 \fIPath=\fR
785 .RS 4
786 Specifies where to find source versions of this resource\&.
787 .sp
788 If the source type is selected as
789 \fBurl\-file\fR
790 or
791 \fBurl\-tar\fR
792 this must be a HTTP/HTTPS URL\&. The URL is suffixed with
793 /SHA256SUMS
794 to acquire the manifest file, with
795 /SHA256SUMS\&.gpg
796 to acquire the detached signature file for it, and with the file names listed in the manifest file in case an update is executed and a resource shall be downloaded\&.
797 .sp
798 For all other source resource types this must be a local path in the file system, referring to a local directory to find the versions of this resource in\&.
799 .sp
800 Added in version 251\&.
801 .RE
802 .PP
803 \fIMatchPattern=\fR
804 .RS 4
805 Specifies one or more file name match patterns that select the subset of files that are update candidates as source for this transfer\&. See above for details on match patterns\&.
806 .sp
807 This option is mandatory\&. Any pattern listed must contain at least the
808 "@v"
809 wildcard, so that a version identifier may be extracted from the filename\&. All other wildcards are optional\&.
810 .sp
811 If the source type is
812 \fBregular\-file\fR
813 or
814 \fBdirectory\fR, the pattern may contain slash characters\&. In this case, it will match the file or directory in corresponding subdirectory\&. For example
815 "MatchPattern=foo_@v/bar\&.efi"
816 will match
817 "bar\&.efi"
818 in directory
819 "foo_1"\&.
820 .sp
821 Added in version 251\&.
822 .RE
823 .SH "[TARGET] SECTION OPTIONS"
824 .PP
825 This section defines properties of the transfer target\&.
826 .PP
827 \fIType=\fR
828 .RS 4
829 Specifies the resource type of the target for the transfer\&. Takes one of
830 \fBpartition\fR,
831 \fBregular\-file\fR,
832 \fBdirectory\fR
833 or
834 \fBsubvolume\fR\&. For details about the resource types, see above\&. This option is mandatory\&.
835 .sp
836 Note that only certain combinations of source and target resource types are supported, see above\&.
837 .sp
838 Added in version 251\&.
839 .RE
840 .PP
841 \fIPath=\fR
842 .RS 4
843 Specifies a file system path where to look for already installed versions or place newly downloaded versions of this configured resource\&. If
844 \fIType=\fR
845 is set to
846 \fBpartition\fR, expects a path to a (whole) block device node, or the special string
847 "auto"
848 in which case the block device which contains the root file system of the currently booted system is automatically determined and used\&. If
849 \fIType=\fR
850 is set to
851 \fBregular\-file\fR,
852 \fBdirectory\fR
853 or
854 \fBsubvolume\fR, must refer to a path in the local file system referencing the directory to find or place the version files or directories under\&.
855 .sp
856 Note that this mechanism cannot be used to create or remove partitions, in case
857 \fIType=\fR
858 is set to
859 \fBpartition\fR\&. Partitions must exist already, and a special partition label
860 "_empty"
861 is used to indicate empty partitions\&. To automatically generate suitable partitions on first boot, use a tool such as
862 \fBsystemd-repart\fR(8)\&.
863 .sp
864 Added in version 251\&.
865 .RE
866 .PP
867 \fIPathRelativeTo=\fR
868 .RS 4
869 Specifies what anchor point
870 \fIPath=\fR
871 should be relative to\&. Takes one of
872 \fBroot\fR,
873 \fBesp\fR,
874 \fBxbootldr\fR,
875 \fBboot\fR
876 or
877 \fBexplicit\fR\&. If unspecified, defaults to
878 \fBroot\fR\&.
879 .sp
880 If set to
881 \fBroot\fR,
882 \fBesp\fR,
883 \fBxbootldr\fR, the specified
884 \fIPath=\fR
885 will be resolved relative to the mount point of the corresponding partition, as defined by the
886 \m[blue]\fBUAPI\&.1 Boot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
887 .sp
888 If set to
889 \fBboot\fR, the specified
890 \fIPath=\fR
891 will be resolved relative to the mount point of the $BOOT partition (i\&.e\&. the ESP or XBOOTLDR), as defined by the
892 \m[blue]\fBUAPI\&.1 Boot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
893 .sp
894 If set to
895 \fBexplicit\fR, the specified
896 \fIPath=\fR
897 will be resolved relative to the directory specified with
898 \fB\-\-transfer\-source=\fR
899 when invoking
900 \fBsystemd-sysupdate\fR(8)\&.
901 .sp
902 The values
903 \fBesp\fR,
904 \fBxbootldr\fR, and
905 \fBboot\fR
906 are only supported when
907 \fIType=\fR
908 is set to
909 \fBregular\-file\fR
910 or
911 \fBdirectory\fR\&.
912 .sp
913 Added in version 254\&.
914 .RE
915 .PP
916 \fIMatchPattern=\fR
917 .RS 4
918 Specifies one or more file name or partition label match patterns that select the subset of files or partitions that are update candidates as targets for this transfer\&. See above for details on match patterns\&.
919 .sp
920 This option is mandatory\&. Any pattern listed must contain at least the
921 "@v"
922 wildcard, so that a version identifier may be extracted from the filename\&. All other wildcards are optional\&.
923 .sp
924 This pattern is both used for matching existing installed versions and for determining the name of new versions to install\&. If multiple patterns are specified, the first specified is used for naming newly installed versions\&.
925 .sp
926 If the target type is
927 \fBregular\-file\fR
928 or
929 \fBdirectory\fR, the pattern may contain slash characters\&. In this case, it will match the file or directory in corresponding subdirectory\&. For example
930 "MatchPattern=foo_@v/bar\&.efi"
931 will match
932 "bar\&.efi"
933 in directory
934 "foo_1"\&. Directories in the path will be created when file is installed\&. Empty directories will be removed when file is removed\&.
935 .sp
936 Added in version 251\&.
937 .RE
938 .PP
939 \fIMatchPartitionType=\fR
940 .RS 4
941 When the target
942 \fIType=\fR
943 is chosen as
944 \fBpartition\fR, specifies the GPT partition type to look for\&. Only partitions of this type are considered, all other partitions are ignored\&. If not specified, the GPT partition type
945 \fBlinux\-generic\fR
946 is used\&. Accepts either a literal type UUID or a symbolic type identifier\&. For a list of supported type identifiers, see the
947 \fIType=\fR
948 setting in
949 \fBrepart.d\fR(5)\&.
950 .sp
951 Added in version 251\&.
952 .RE
953 .PP
954 \fIPartitionUUID=\fR, \fIPartitionFlags=\fR, \fIPartitionNoAuto=\fR, \fIPartitionGrowFileSystem=\fR
955 .RS 4
956 When the target
957 \fIType=\fR
958 is picked as
959 \fBpartition\fR, selects the GPT partition UUID and partition flags to use for the updated partition\&. Expects a valid UUID string, a hexadecimal integer, or booleans, respectively\&. If not set, but the source match pattern includes wildcards for these fields (i\&.e\&.
960 "@u",
961 "@f",
962 "@a", or
963 "@g"), the values from the patterns are used\&. If neither configured with wildcards or these explicit settings, the values are left untouched\&. If both the overall
964 \fIPartitionFlags=\fR
965 flags setting and the individual flag settings
966 \fIPartitionNoAuto=\fR
967 and
968 \fIPartitionGrowFileSystem=\fR
969 are used (or the wildcards for them), then the latter override the former, i\&.e\&. the individual flag bit overrides the overall flags value\&. See
970 \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2
971 for details about these flags\&.
972 .sp
973 Note that these settings are not used for matching, they only have effect on newly written partitions in case a transfer takes place\&.
974 .sp
975 Added in version 251\&.
976 .RE
977 .PP
978 \fIReadOnly=\fR
979 .RS 4
980 Controls whether to mark the resulting file, subvolume or partition read\-only\&. If the target type is
981 \fBpartition\fR
982 this controls the ReadOnly partition flag, as per
983 \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2, similar to the
984 \fIPartitionNoAuto=\fR
985 and
986 \fIPartitionGrowFileSystem=\fR
987 flags described above\&. If the target type is
988 \fBregular\-file\fR, the writable bit is removed from the access mode\&. If the target type is
989 \fBsubvolume\fR, the subvolume will be marked read\-only as a whole\&. Finally, if the target
990 \fIType=\fR
991 is selected as
992 \fBdirectory\fR, the "immutable" file attribute is set, see
993 \fBchattr\fR(1)
994 for details\&.
995 .sp
996 Added in version 251\&.
997 .RE
998 .PP
999 \fIMode=\fR
1000 .RS 4
1001 The UNIX file access mode to use for newly created files in case the target resource type is picked as
1002 \fBregular\-file\fR\&. Expects an octal integer, in typical UNIX fashion\&. If not set, but the source match pattern includes a wildcard for this field (i\&.e\&.
1003 "@t"), the value from the pattern is used\&.
1004 .sp
1005 Note that this setting is not used for matching, it only has an effect on newly written files when a transfer takes place\&.
1006 .sp
1007 Added in version 251\&.
1008 .RE
1009 .PP
1010 \fITriesDone=\fR, \fITriesLeft=\fR
1011 .RS 4
1012 These options take positive, decimal integers, and control the number of attempts done and left for this file\&. These settings are useful for managing kernel images, following the scheme defined in
1013 \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[3]\d\s+2, and only have an effect if the target pattern includes the
1014 "@d"
1015 or
1016 "@l"
1017 wildcards\&.
1018 .sp
1019 Added in version 251\&.
1020 .RE
1021 .PP
1022 \fIInstancesMax=\fR
1023 .RS 4
1024 Takes a decimal integer equal to or greater than 2\&. This configures how many concurrent versions of the resource to keep\&. Whenever a new update is initiated it is made sure that no more than the number of versions specified here minus one exist in the target\&. Any excess versions are deleted (in case the target
1025 \fIType=\fR
1026 of
1027 \fBregular\-file\fR,
1028 \fBdirectory\fR,
1029 \fBsubvolume\fR
1030 is used) or emptied (in case the target
1031 \fIType=\fR
1032 of
1033 \fBpartition\fR
1034 is used; emptying in this case simply means to set the partition label to the special string
1035 "_empty"; note that no partitions are actually removed)\&. After an update is completed the number of concurrent versions of the target resources is equal to or below the number specified here\&.
1036 .sp
1037 Note that this setting may be set differently for each transfer\&. However, it generally is advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of files or partitions will be left installed\&.
1038 .sp
1039 If the target
1040 \fIType=\fR
1041 is selected as
1042 \fBpartition\fR, the number of concurrent versions to keep is additionally restricted by the number of partition slots of the right type in the partition table\&. I\&.e\&. if there are only 2 partition slots for the selected partition type, setting this value larger than 2 is without effect, since no more than 2 concurrent versions could be stored in the image anyway\&.
1043 .sp
1044 Added in version 251\&.
1045 .RE
1046 .PP
1047 \fIRemoveTemporary=\fR
1048 .RS 4
1049 Takes a boolean argument\&. If this option is enabled (which is the default) before initiating an update, all left\-over, incomplete updates from a previous attempt are removed from the target directory\&. This only has an effect if the target resource
1050 \fIType=\fR
1051 is selected as
1052 \fBregular\-file\fR,
1053 \fBdirectory\fR
1054 or
1055 \fBsubvolume\fR\&.
1056 .sp
1057 Added in version 251\&.
1058 .RE
1059 .PP
1060 \fICurrentSymlink=\fR
1061 .RS 4
1062 Takes a symlink name as argument\&. If this option is used, as the last step of the update a symlink under the specified name is created/updated pointing to the completed update\&. This is useful in to provide a stable name always pointing to the newest version of the resource\&. This is only supported if the target resource
1063 \fIType=\fR
1064 is selected as
1065 \fBregular\-file\fR,
1066 \fBdirectory\fR
1067 or
1068 \fBsubvolume\fR\&.
1069 .sp
1070 Added in version 251\&.
1071 .RE
1072 .SH "SPECIFIERS"
1073 .PP
1074 Specifiers may be used in the
1075 \fIMinVersion=\fR,
1076 \fIProtectVersion=\fR,
1077 \fIPath=\fR,
1078 \fIMatchPattern=\fR
1079 and
1080 \fICurrentSymlink=\fR
1081 settings\&. The following expansions are understood:
1082 .sp
1083 .it 1 an-trap
1084 .nr an-no-space-flag 1
1085 .nr an-break-flag 1
1086 .br
1087 .B Table\ \&3.\ \&Specifiers available
1088 .TS
1089 allbox tab(:);
1090 lB lB lB.
1091 T{
1092 Specifier
1093 T}:T{
1094 Meaning
1095 T}:T{
1096 Details
1097 T}
1098 .T&
1099 l l l
1100 l l l
1101 l l l
1102 l l l
1103 l l l
1104 l l l
1105 l l l
1106 l l l
1107 l l l
1108 l l l
1109 l l l
1110 l l l
1111 l l l
1112 l l l
1113 l l l.
1114 T{
1115 "%a"
1116 T}:T{
1117 Architecture
1118 T}:T{
1119 A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&.
1120 T}
1121 T{
1122 "%A"
1123 T}:T{
1124 Operating system image version
1125 T}:T{
1126 The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1127 T}
1128 T{
1129 "%b"
1130 T}:T{
1131 Boot ID
1132 T}:T{
1133 The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&.
1134 T}
1135 T{
1136 "%B"
1137 T}:T{
1138 Operating system build ID
1139 T}:T{
1140 The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1141 T}
1142 T{
1143 "%H"
1144 T}:T{
1145 Host name
1146 T}:T{
1147 The hostname of the running system\&.
1148 T}
1149 T{
1150 "%l"
1151 T}:T{
1152 Short host name
1153 T}:T{
1154 The hostname of the running system, truncated at the first dot to remove any domain component\&.
1155 T}
1156 T{
1157 "%m"
1158 T}:T{
1159 Machine ID
1160 T}:T{
1161 The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&.
1162 T}
1163 T{
1164 "%M"
1165 T}:T{
1166 Operating system image identifier
1167 T}:T{
1168 The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1169 T}
1170 T{
1171 "%o"
1172 T}:T{
1173 Operating system ID
1174 T}:T{
1175 The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&.
1176 T}
1177 T{
1178 "%v"
1179 T}:T{
1180 Kernel release
1181 T}:T{
1182 Identical to \fBuname \-r\fR output\&.
1183 T}
1184 T{
1185 "%w"
1186 T}:T{
1187 Operating system version ID
1188 T}:T{
1189 The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1190 T}
1191 T{
1192 "%W"
1193 T}:T{
1194 Operating system variant ID
1195 T}:T{
1196 The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1197 T}
1198 T{
1199 "%T"
1200 T}:T{
1201 Directory for temporary files
1202 T}:T{
1203 This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
1204 T}
1205 T{
1206 "%V"
1207 T}:T{
1208 Directory for larger and persistent temporary files
1209 T}:T{
1210 This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
1211 T}
1212 T{
1213 "%%"
1214 T}:T{
1215 Single percent sign
1216 T}:T{
1217 Use "%%" in place of "%" to specify a single percent sign\&.
1218 T}
1219 .TE
1220 .sp 1
1221 .PP
1222 Do not confuse the
1223 "%"
1224 specifier expansion prefix with the
1225 "@"
1226 pattern matching wildcard prefix\&. The former are simple shortcuts that are expanded while the drop\-in files are parsed, the latter encapsulate a variable part of a match pattern string\&. For details about pattern matching wildcards, see above\&.
1227 .SH "EXAMPLES"
1228 .PP
1229 \fBExample\ \&1.\ \&Updates for a Verity Enabled Secure OS\fR
1230 .PP
1231 With the following three files we define a root file system partition, a matching Verity partition, and a unified kernel image to update as one\&. This example is an extension of the example discussed earlier in this man page\&.
1232 .PP
1233 .if n \{\
1234 .RS 4
1235 .\}
1236 .nf
1237 # /usr/lib/sysupdate\&.d/50\-verity\&.transfer
1238 [Transfer]
1239 ProtectVersion=%A
1240
1241 [Source]
1242 Type=url\-file
1243 Path=https://download\&.example\&.com/
1244 MatchPattern=foobarOS_@v_@u\&.verity\&.xz
1245
1246 [Target]
1247 Type=partition
1248 Path=auto
1249 MatchPattern=foobarOS_@v_verity
1250 MatchPartitionType=root\-verity
1251 PartitionFlags=0
1252 ReadOnly=1
1253 .fi
1254 .if n \{\
1255 .RE
1256 .\}
1257 .PP
1258 The above defines the update mechanism for the Verity partition of the root file system\&. Verity partition images are downloaded from
1259 "https://download\&.example\&.com/foobarOS_@v_@u\&.verity\&.xz"
1260 and written to a suitable local partition, which is marked read\-only\&. Under the assumption this update is run from the image itself the current image version (i\&.e\&. the
1261 "%A"
1262 specifier) is marked as protected, to ensure it is not corrupted while booted\&. Note that the partition UUID for the target partition is encoded in the source file name\&. Fixating the partition UUID can be useful to ensure that
1263 "roothash="
1264 on the kernel command line is sufficient to pinpoint both the Verity and root file system partition, and also encode the Verity root level hash (under the assumption the UUID in the file names match their top\-level hash, the way
1265 \fBsystemd-gpt-auto-generator\fR(8)
1266 suggests)\&.
1267 .PP
1268 .if n \{\
1269 .RS 4
1270 .\}
1271 .nf
1272 # /usr/lib/sysupdate\&.d/60\-root\&.transfer
1273 [Transfer]
1274 ProtectVersion=%A
1275
1276 [Source]
1277 Type=url\-file
1278 Path=https://download\&.example\&.com/
1279 MatchPattern=foobarOS_@v_@u\&.root\&.xz
1280
1281 [Target]
1282 Type=partition
1283 Path=auto
1284 MatchPattern=foobarOS_@v
1285 MatchPartitionType=root
1286 PartitionFlags=0
1287 ReadOnly=1
1288 .fi
1289 .if n \{\
1290 .RE
1291 .\}
1292 .PP
1293 The above defines a matching transfer definition for the root file system\&.
1294 .PP
1295 .if n \{\
1296 .RS 4
1297 .\}
1298 .nf
1299 # /usr/lib/sysupdate\&.d/70\-kernel\&.transfer
1300 [Transfer]
1301 ProtectVersion=%A
1302
1303 [Source]
1304 Type=url\-file
1305 Path=https://download\&.example\&.com/
1306 MatchPattern=foobarOS_@v\&.efi
1307
1308 [Target]
1309 Type=regular\-file
1310 Path=/EFI/Linux
1311 PathRelativeTo=boot
1312 MatchPattern=foobarOS_@v+@l\-@d\&.efi \e
1313 foobarOS_@v+@l\&.efi \e
1314 foobarOS_@v\&.efi
1315 Mode=0644
1316 TriesLeft=3
1317 TriesDone=0
1318 InstancesMax=2
1319 .fi
1320 .if n \{\
1321 .RE
1322 .\}
1323 .PP
1324 The above installs a unified kernel image into the $BOOT partition, as per
1325 \m[blue]\fBUAPI\&.1 Boot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
1326 Type #2\&. This defines three possible patterns for the names of the kernel images, as per
1327 \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[3]\d\s+2, and ensures when installing new kernels, they are set up with 3 tries left\&. No more than two parallel kernels are kept\&.
1328 .PP
1329 With this setup the web server would serve the following files, for a hypothetical version 7 of the OS:
1330 .sp
1331 .RS 4
1332 .ie n \{\
1333 \h'-04'\(bu\h'+03'\c
1334 .\}
1335 .el \{\
1336 .sp -1
1337 .IP \(bu 2.3
1338 .\}
1339 SHA256SUMS
1340 \(en The manifest file, containing available files and their SHA256 hashes
1341 .RE
1342 .sp
1343 .RS 4
1344 .ie n \{\
1345 \h'-04'\(bu\h'+03'\c
1346 .\}
1347 .el \{\
1348 .sp -1
1349 .IP \(bu 2.3
1350 .\}
1351 SHA256SUMS\&.gpg
1352 \(en The detached cryptographic signature for the manifest file
1353 .RE
1354 .sp
1355 .RS 4
1356 .ie n \{\
1357 \h'-04'\(bu\h'+03'\c
1358 .\}
1359 .el \{\
1360 .sp -1
1361 .IP \(bu 2.3
1362 .\}
1363 foobarOS_7_8b8186b1\-2b4e\-4eb6\-ad39\-8d4d18d2a8fb\&.verity\&.xz
1364 \(en The Verity image for version 7
1365 .RE
1366 .sp
1367 .RS 4
1368 .ie n \{\
1369 \h'-04'\(bu\h'+03'\c
1370 .\}
1371 .el \{\
1372 .sp -1
1373 .IP \(bu 2.3
1374 .\}
1375 foobarOS_7_f4d1234f\-3ebf\-47c4\-b31d\-4052982f9a2f\&.root\&.xz
1376 \(en The root file system image for version 7
1377 .RE
1378 .sp
1379 .RS 4
1380 .ie n \{\
1381 \h'-04'\(bu\h'+03'\c
1382 .\}
1383 .el \{\
1384 .sp -1
1385 .IP \(bu 2.3
1386 .\}
1387 foobarOS_7\&.efi
1388 \(en The unified kernel image for version 7
1389 .RE
1390 .PP
1391 For each new OS release a new set of the latter three files would be added, each time with an updated version\&. The
1392 SHA256SUMS
1393 manifest should then be updated accordingly, listing all files for all versions that shall be offered for download\&.
1394 .PP
1395 \fBExample\ \&2.\ \&Updates for Plain Directory Container Image\fR
1396 .PP
1397 .if n \{\
1398 .RS 4
1399 .\}
1400 .nf
1401 [Source]
1402 Type=url\-tar
1403 Path=https://download\&.example\&.com/
1404 MatchPattern=myContainer_@v\&.tar\&.gz
1405
1406 [Target]
1407 Type=subvolume
1408 Path=/var/lib/machines
1409 MatchPattern=myContainer_@v
1410 CurrentSymlink=myContainer
1411 .fi
1412 .if n \{\
1413 .RE
1414 .\}
1415 .PP
1416 On updates this downloads
1417 "https://download\&.example\&.com/myContainer_@v\&.tar\&.gz"
1418 and decompresses/unpacks it to
1419 /var/lib/machines/myContainer_@v\&. After each update a symlink
1420 /var/lib/machines/myContainer
1421 is created/updated always pointing to the most recent update\&.
1422 .SH "SEE ALSO"
1423 .PP
1424 \fBsystemd\fR(1), \fBsystemd-sysupdate\fR(8), \fBsystemd-repart\fR(8)
1425 .SH "NOTES"
1426 .IP " 1." 4
1427 UAPI.2 Discoverable Partitions Specification
1428 .RS 4
1429 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
1430 .RE
1431 .IP " 2." 4
1432 UAPI.1 Boot Loader Specification
1433 .RS 4
1434 \%https://uapi-group.org/specifications/specs/boot_loader_specification
1435 .RE
1436 .IP " 3." 4
1437 Automatic Boot Assessment
1438 .RS 4
1439 \%https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
1440 .RE
1441 .IP " 4." 4
1442 AppStream catalog
1443 .RS 4
1444 \%https://www.freedesktop.org/software/appstream/docs/chap-CatalogData.html
1445 .RE
1446 .IP " 5." 4
1447 special metadata
1448 .RS 4
1449 \%https://systemd.io/APPSTREAM_BUNDLE
1450 .RE