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 -->
6 <refentry id=
"sysupdate.d" conditional='ENABLE_SYSUPDATE'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sysupdate.d
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sysupdate.d
</refentrytitle>
16 <manvolnum>5</manvolnum>
20 <refname>sysupdate.d
</refname>
21 <refpurpose>Transfer Definition Files for Automatic Updates
</refpurpose>
25 <para><literallayout><filename>/etc/sysupdate.d/*.conf
</filename>
26 <filename>/run/sysupdate.d/*.conf
</filename>
27 <filename>/usr/lib/sysupdate.d/*.conf
</filename>
28 </literallayout></para>
32 <title>Description
</title>
34 <para><filename>sysupdate.d/*.conf
</filename> files describe how specific resources on the local system
35 shall be updated from a remote source. Each such file defines one such transfer: typically a remote
36 HTTP/HTTPS resource as source; and a local file, directory or partition as target. This may be used as a
37 simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system
38 extension images — but in fact may be used to update any kind of file from a remote source.
</para>
41 <citerefentry><refentrytitle>systemd-sysupdate
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
42 command reads these files and uses them to determine which local resources should be updated, and then
43 executes the update.
</para>
45 <para>Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent
46 versions, in order to implement flexible update schemes, e.g. A/B updating (or a superset thereof,
47 e.g. A/B/C, A/B/C/D, …).
</para>
49 <para>Each
<filename>*.conf
</filename> file defines one transfer, i.e. describes one resource to
50 update. Typically, multiple of these files (i.e. multiple of such transfers) are defined together, and
51 are bound together by a common version identifier in order to update multiple resources at once on each
52 update operation, for example to update a kernel, a root file system and a Verity partition in a single,
53 combined, synchronized operation, so that only a combined update of all three together constitutes a
54 complete update.
</para>
56 <para>Each
<filename>*.conf
</filename> file contains three sections: [Transfer], [Source] and [Target].
</para>
60 <title>Basic Mode of Operation
</title>
62 <para>Disk-image based OS updates typically consist of multiple different resources that need to be
63 updated together, for example a secure OS update might consist of a root file system image to drop into a
64 partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the
65 combination of the two partitions. The first two resources are files that are downloaded and placed in a
66 disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file
67 system (e.g. EFI system partition). Hence, during an update of a hypothetical operating system
"foobarOS"
68 to a hypothetical version
47 the following operations should take place:
</para>
71 <listitem><para>A file
<literal>https://download.example.com/foobarOS_47.root.xz
</literal> should be
72 downloaded, decompressed and written to a previously unused partition with GPT partition type UUID
73 4f68bce3-e8cd-
4db1-
96e7-fbcaf984b709 for x86-
64, as per
<ulink
74 url=
"https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
75 Specification
</ulink>.
</para></listitem>
77 <listitem><para>Similarly, a file
<literal>https://download.example.com/foobarOS_47.verity.xz
</literal>
78 should be downloaded, decompressed and written to a previously empty partition with GPT partition type
79 UUID of
2c7357ed-ebd2-
46d9-aec1-
23d437ec2bf5 (i.e. the partition type for Verity integrity information
80 for x86-
64 root file systems).
</para></listitem>
82 <listitem><para>Finally, a file
<literal>https://download.example.com/foobarOS_47.efi.xz
</literal> (a
83 unified kernel, as per
<ulink url=
"https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
84 Specification
</ulink> Type #
2) should be downloaded, decompressed and written to the ESP file system,
85 i.e. to
<filename>EFI/Linux/foobarOS_47.efi
</filename> in the ESP.
</para></listitem>
88 <para>The version-independent generalization of this would be (using the special marker
89 <literal>@v
</literal> as wildcard for the version identifier):
</para>
92 <listitem><para>A transfer of a file
<literal>https://download.example.com/foobarOS_@v.root.xz
</literal>
93 → a local, previously empty GPT partition of type
4f68bce3-e8cd-
4db1-
96e7-fbcaf984b709, with the label to
94 be set to
<literal>foobarOS_@v
</literal>.
</para></listitem>
96 <listitem><para>A transfer of a file
<literal>https://download.example.com/foobarOS_@v.verity.xz
</literal>
97 → a local, previously empty GPT partition of type
2c7357ed-ebd2-
46d9-aec1-
23d437ec2bf5, with the label to be
98 set to
<literal>foobarOS_@v_verity
</literal>.
</para></listitem>
100 <listitem><para>A transfer of a file
<literal>https://download.example.com/foobarOS_@v.efi.xz
</literal>
101 → a local file
<filename>/efi/EFI/Linux/foobarOS_@v.efi
</filename>.
</para></listitem>
104 <para>An update can only complete if the relevant URLs provide their resources for the same version,
105 i.e. for the same value of
<literal>@v
</literal>.
</para>
107 <para>The above may be translated into three
<filename>*.conf
</filename> files in
108 <filename>sysupdate.d/
</filename>, one for each resource to transfer. The
<filename>*.conf
</filename>
109 files configure the type of download, and what place to write the download to (i.e. whether to a
110 partition or a file in the file system). Most importantly these files contain the URL, partition name and
111 filename patterns shown above that describe how these resources are called on the source and how they
112 shall be called on the target.
</para>
114 <para>In order to enumerate available versions and figuring out candidates to update to, a mechanism is
115 necessary to list suitable files:
</para>
118 <listitem><para>For partitions: the surrounding GPT partition table contains a list of defined
119 partitions, including a partition type UUID and a partition label (in this scheme the partition label
120 plays a role for the partition similar to the filename for a regular file).
</para></listitem>
122 <listitem><para>For regular files: the directory listing of the directory the files are contained in
123 provides a list of existing files in a straightforward way.
</para></listitem>
125 <listitem><para>For HTTP/HTTPS sources a simple scheme is used: a manifest file
126 <filename>SHA256SUMS
</filename>, following the format defined by
<citerefentry
127 project='man-pages'
><refentrytitle>sha256sum
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
128 lists file names and their SHA256 hashes.
</para></listitem>
131 <para>Transfers are done in the alphabetical order of the
<filename>.conf
</filename> file names they are
132 defined in. First, the resource data is downloaded directly into a target file/directory/partition. Once
133 this is completed for all defined transfers, in a second step the files/directories/partitions are
134 renamed to their final names as defined by the target
<varname>MatchPattern=
</varname>, again in the
135 order the
<filename>.conf
</filename> transfer file names dictate. This step is not atomic, however it is
136 guaranteed to be executed strictly in order with suitable disk synchronization in place. Typically, when
137 updating an OS one of the transfers defines the entry point when booting. Thus it is generally a good idea
138 to order the resources via the transfer configuration file names so that the entry point is written
139 last, ensuring that any abnormal termination does not leave an entry point around whose backing is not
140 established yet. In the example above it would hence make sense to establish the EFI kernel image last
141 and thus give its transfer configuration file the alphabetically last name.
</para>
143 <para>See below for an extended, more specific example based on the above.
</para>
147 <title>Resource Types
</title>
149 <para>Each transfer file defines one source resource to transfer to one target resource. The following
150 resource types are supported:
</para>
154 <listitem><para>Resources of type
<literal>url-file
</literal> encapsulate a file on a web server,
155 referenced via a HTTP or HTTPS URL. When an update takes place, the file is downloaded and decompressed
156 and then written to the target file or partition. This resource type is only available for sources, not
157 for targets. The list of available versions of resources of this type is encoded in
158 <filename>SHA256SUMS
</filename> manifest files, accompanied by
159 <filename>SHA256SUMS.gpg
</filename> detached signatures.
</para></listitem>
161 <listitem><para>The
<literal>url-tar
</literal> resource type is similar, but the file must be a
162 <filename>.tar
</filename> archive. When an update takes place, the file is decompressed and unpacked
163 into a directory or btrfs subvolume. This resource type is only available for sources, not for
164 targets. Just like
<literal>url-file
</literal>,
<literal>url-tar
</literal> version enumeration makes
165 use of
<filename>SHA256SUMS
</filename> files, authenticated via
166 <filename>SHA256SUMS.gpg
</filename>.
</para></listitem>
168 <listitem><para>The
<literal>regular-file
</literal> resource type encapsulates a local regular file on
169 disk. During updates the file is uncompressed and written to the target file or partition. This
170 resource type is available both as source and as target. When updating no integrity or authentication
171 verification is done for resources of this type.
</para></listitem>
173 <listitem><para>The
<literal>partition
</literal> resource type is similar to
174 <literal>regular-file
</literal>, and encapsulates a GPT partition on disk. When updating, the partition
175 must exist already, and have the correct GPT partition type. A partition whose GPT partition label is
176 set to
<literal>_empty
</literal> is considered empty, and a candidate to place a newly downloaded
177 resource in. The GPT partition label is used to store version information, once a partition is
178 updated. This resource type is only available for target resources.
</para></listitem>
180 <listitem><para>The
<literal>tar
</literal> resource type encapsulates local
<filename>.tar
</filename>
181 archive files. When an update takes place, the files are uncompressed and unpacked into a target
182 directory or btrfs subvolume. Behaviour of
<literal>tar
</literal> and
<literal>url-tar
</literal> is
183 generally similar, but the latter downloads from remote sources, and does integrity and authentication
184 checks while the former does not. The
<literal>tar
</literal> resource type is only available for source
185 resources.
</para></listitem>
187 <listitem><para>The
<literal>directory
</literal> resource type encapsulates local directory trees. This
188 type is available both for source and target resources. If an update takes place on a source resource
189 of this type, a recursive copy of the directory is done.
</para></listitem>
191 <listitem><para>The
<literal>subvolume
</literal> resource type is identical to
192 <literal>directory
</literal>, except when used as the target, in which case the file tree is placed in
193 a btrfs subvolume instead of a plain directory, if the backing file system supports it (i.e. is
194 btrfs).
</para></listitem>
197 <para>As already indicated, only a subset of source and target resource type combinations are
201 <title>Resource Types
</title>
203 <tgroup cols='
3' align='left' colsep='
1' rowsep='
1'
>
204 <colspec colname=
"name" />
205 <colspec colname=
"explanation" />
209 <entry>Identifier
</entry>
210 <entry>Description
</entry>
211 <entry>Usable as Source
</entry>
212 <entry>When Used as Source: Compatible Targets
</entry>
213 <entry>When Used as Source: Integrity + Authentication
</entry>
214 <entry>When Used as Source: Decompression
</entry>
215 <entry>Usable as Target
</entry>
216 <entry>When Used as Target: Compatible Sources
</entry>
222 <entry><constant>url-file
</constant></entry>
223 <entry>HTTP/HTTPS files
</entry>
225 <entry><constant>regular-file
</constant>,
<constant>partition
</constant></entry>
233 <entry><constant>url-tar
</constant></entry>
234 <entry>HTTP/HTTPS
<filename>.tar
</filename> archives
</entry>
236 <entry><constant>directory
</constant>,
<constant>subvolume
</constant></entry>
244 <entry><constant>regular-file
</constant></entry>
245 <entry>Local files
</entry>
247 <entry><constant>regular-file
</constant>,
<constant>partition
</constant></entry>
251 <entry><constant>url-file
</constant>,
<constant>regular-file
</constant></entry>
255 <entry><constant>partition
</constant></entry>
256 <entry>Local GPT partitions
</entry>
262 <entry><constant>url-file
</constant>,
<constant>regular-file
</constant></entry>
266 <entry><constant>tar
</constant></entry>
267 <entry>Local
<filename>.tar
</filename> archives
</entry>
269 <entry><constant>directory
</constant>,
<constant>subvolume
</constant></entry>
277 <entry><constant>directory
</constant></entry>
278 <entry>Local directories
</entry>
280 <entry><constant>directory
</constant>,
<constant>subvolume
</constant></entry>
284 <entry><constant>url-tar
</constant>,
<constant>tar
</constant>,
<constant>directory
</constant>,
<constant>subvolume
</constant></entry>
288 <entry><constant>subvolume
</constant></entry>
289 <entry>Local btrfs subvolumes
</entry>
291 <entry><constant>directory
</constant>,
<constant>subvolume
</constant></entry>
295 <entry><constant>url-tar
</constant>,
<constant>tar
</constant>,
<constant>directory
</constant>,
<constant>subvolume
</constant></entry>
304 <title>Match Patterns
</title>
306 <para>Both the source and target resources typically exist in multiple versions concurrently. An update
307 operation is done whenever the newest of the source versions is newer than the newest of the target
308 versions. To determine the newest version of the resources a directory listing, partition listing or
309 manifest listing is used, a subset of qualifying entries selected from that, and the version identifier
310 extracted from the file names or partition labels of these selected entries. Subset selection and
311 extraction of the version identifier (plus potentially other metadata) is done via match patterns,
312 configured in
<varname>MatchPattern=
</varname> in the [Source] and [Target] sections. These patterns are
313 strings that describe how files or partitions are named, with named wildcards for specific fields such as
314 the version identifier. The following wildcards are defined:
</para>
317 <title>Match Pattern Wildcards
</title>
319 <tgroup cols='
2' align='left' colsep='
1' rowsep='
1'
>
320 <colspec colname=
"name" />
321 <colspec colname=
"explanation" />
325 <entry>Wildcard
</entry>
326 <entry>Description
</entry>
327 <entry>Format
</entry>
334 <entry><literal>@v
</literal></entry>
335 <entry>Version identifier
</entry>
336 <entry>Valid version string
</entry>
337 <entry>Mandatory
</entry>
341 <entry><literal>@u
</literal></entry>
342 <entry>GPT partition UUID
</entry>
343 <entry>Valid
128-Bit UUID string
</entry>
344 <entry>Only relevant if target resource type chosen as
<constant>partition
</constant></entry>
348 <entry><literal>@f
</literal></entry>
349 <entry>GPT partition flags
</entry>
350 <entry>Formatted hexadecimal integer
</entry>
351 <entry>Only relevant if target resource type chosen as
<constant>partition
</constant></entry>
355 <entry><literal>@a
</literal></entry>
356 <entry>GPT partition flag NoAuto
</entry>
357 <entry>Either
<literal>0</literal> or
<literal>1</literal></entry>
358 <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>
362 <entry><literal>@g
</literal></entry>
363 <entry>GPT partition flag GrowFileSystem
</entry>
364 <entry>Either
<literal>0</literal> or
<literal>1</literal></entry>
365 <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>
369 <entry><literal>@r
</literal></entry>
370 <entry>Read-only flag
</entry>
371 <entry>Either
<literal>0</literal> or
<literal>1</literal></entry>
372 <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>
376 <entry><literal>@t
</literal></entry>
377 <entry>File modification time
</entry>
378 <entry>Formatted decimal integer, µs since UNIX epoch Jan
1st
1970</entry>
379 <entry>Only relevant if target resource type chosen as
<constant>regular-file
</constant></entry>
383 <entry><literal>@m
</literal></entry>
384 <entry>File access mode
</entry>
385 <entry>Formatted octal integer, in UNIX fashion
</entry>
386 <entry>Only relevant if target resource type chosen as
<constant>regular-file
</constant></entry>
390 <entry><literal>@s
</literal></entry>
391 <entry>File size after decompression
</entry>
392 <entry>Formatted decimal integer
</entry>
393 <entry>Useful for measuring progress and to improve partition allocation logic
</entry>
397 <entry><literal>@d
</literal></entry>
398 <entry>Tries done
</entry>
399 <entry>Formatted decimal integer
</entry>
400 <entry>Useful when operating with kernel image files, as per
<ulink url=
"https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment
</ulink></entry>
404 <entry><literal>@l
</literal></entry>
405 <entry>Tries left
</entry>
406 <entry>Formatted decimal integer
</entry>
407 <entry>Useful when operating with kernel image files, as per
<ulink url=
"https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment
</ulink></entry>
411 <entry><literal>@h
</literal></entry>
412 <entry>SHA256 hash of compressed file
</entry>
413 <entry>64 hexadecimal characters
</entry>
414 <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>
420 <para>Of these wildcards only
<literal>@v
</literal> must be present in a valid pattern, all other
421 wildcards are optional. Each wildcard may be used at most once in each pattern. A typical wildcard
422 matching a file system source image could be
<literal>MatchPattern=foobar_@v.raw.xz
</literal>, i.e. any file
423 whose name begins with
<literal>foobar_
</literal>, followed by a version ID and suffixed by
424 <literal>.raw.xz
</literal>.
</para>
426 <para>Do not confuse the
<literal>@
</literal> pattern matching wildcard prefix with the
427 <literal>%
</literal> specifier expansion prefix. The former encapsulate a variable part of a match
428 pattern string, the latter are simple shortcuts that are expanded while the drop-in files are
429 parsed. For details about specifiers, see below.
</para>
433 <title>[Transfer] Section Options
</title>
435 <para>This section defines general properties of this transfer.
</para>
439 <term><varname>MinVersion=
</varname></term>
441 <listitem><para>Specifies the minimum version to require for this transfer to take place. If the
442 source or target patterns in this transfer definition match files older than this version they will
443 be considered obsolete, and never be considered for the update operation.
</para></listitem>
447 <term><varname>ProtectVersion=
</varname></term>
449 <listitem><para>Takes one or more version strings to mark as
"protected". Protected versions are
450 never removed while making room for new, updated versions. This is useful to ensure that the
451 currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten
452 during updates, in order to avoid runtime file system corruptions.
</para>
454 <para>Like many of the settings in these configuration files this setting supports specifier
455 expansion. It's particularly useful to set this setting to one of the
<literal>%A
</literal>,
456 <literal>%B
</literal> or
<literal>%w
</literal> specifiers to automatically refer to the current OS
457 version of the running system. See below for details on supported specifiers.
</para></listitem>
461 <term><varname>Verify=
</varname></term>
463 <listitem><para>Takes a boolean, defaults to yes. Controls whether to cryptographically verify
464 downloaded resources (specifically: validate the GPG signatures for downloaded
465 <filename>SHA256SUMS
</filename> manifest files, via their detached signature files
466 <filename>SHA256SUMS.gpg
</filename> in combination with the system keyring
467 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
468 <filename>/etc/systemd/import-pubring.gpg
</filename>).
</para>
470 <para>This option is essential to provide integrity guarantees for downloaded resources and thus
471 should be left enabled, outside of test environments.
</para>
473 <para>Note that the downloaded payload files are unconditionally checked against the SHA256 hashes
474 listed in the manifest. This option only controls whether the signatures of these manifests are
477 <para>This option only has an effect if the source resource type is selected as
478 <constant>url-file
</constant> or
<constant>url-tar
</constant>, as integrity and authentication
479 checking is only available for transfers from remote sources.
</para></listitem>
486 <title>[Source] Section Options
</title>
488 <para>This section defines properties of the transfer source.
</para>
492 <term><varname>Type=
</varname></term>
494 <listitem><para>Specifies the resource type of the source for the transfer. Takes one of
495 <constant>url-file
</constant>,
<constant>url-tar
</constant>,
<constant>tar
</constant>,
496 <constant>regular-file
</constant>,
<constant>directory
</constant> or
497 <constant>subvolume
</constant>. For details about the resource types, see above. This option is
500 <para>Note that only certain combinations of source and target resource types are supported, see
501 above.
</para></listitem>
507 <term><varname>Path=
</varname></term>
509 <listitem><para>Specifies where to find source versions of this resource.
</para>
511 <para>If the source type is selected as
<constant>url-file
</constant> or
512 <constant>url-tar
</constant> this must be a HTTP/HTTPS URL. The URL is suffixed with
513 <filename>/SHA256SUMS
</filename> to acquire the manifest file, with
514 <filename>/SHA256SUMS.gpg
</filename> to acquire the detached signature file for it, and with the file
515 names listed in the manifest file in case an update is executed and a resource shall be
518 <para>For all other source resource types this must be a local path in the file system, referring to
519 a local directory to find the versions of this resource in.
</para></listitem>
523 <term><varname>MatchPattern=
</varname></term>
525 <listitem><para>Specifies one or more file name match patterns that select the subset of files that
526 are update candidates as source for this transfer. See above for details on match patterns.
</para>
528 <para>This option is mandatory. Any pattern listed must contain at least the
<literal>@v
</literal>
529 wildcard, so that a version identifier may be extracted from the filename. All other wildcards are
530 optional.
</para></listitem>
536 <title>[Target] Section Options
</title>
538 <para>This section defines properties of the transfer target.
</para>
542 <term><varname>Type=
</varname></term>
544 <listitem><para>Specifies the resource type of the target for the transfer. Takes one of
545 <constant>partition
</constant>,
<constant>regular-file
</constant>,
<constant>directory
</constant> or
546 <constant>subvolume
</constant>. For details about the resource types, see above. This option is
549 <para>Note that only certain combinations of source and target resource types are supported, see
550 above.
</para></listitem>
554 <term><varname>Path=
</varname></term>
556 <listitem><para>Specifies a file system path where to look for already installed versions or place
557 newly downloaded versions of this configured resource. If
<varname>Type=
</varname> is set to
558 <constant>partition
</constant>, expects a path to a (whole) block device node, or the special string
559 <literal>auto
</literal> in which case the block device which contains the root file system of the
560 currently booted system is automatically determined and used. If
<varname>Type=
</varname> is set to
561 <constant>regular-file
</constant>,
<constant>directory
</constant> or
<constant>subvolume
</constant>,
562 must refer to a path in the local file system referencing the directory to find or place the version
563 files or directories under.
</para>
565 <para>Note that this mechanism cannot be used to create or remove partitions, in case
566 <varname>Type=
</varname> is set to
<constant>partition
</constant>. Partitions must exist already, and
567 a special partition label
<literal>_empty
</literal> is used to indicate empty partitions. To
568 automatically generate suitable partitions on first boot, use a tool such as
569 <citerefentry><refentrytitle>systemd-repart
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para></listitem>
573 <term><varname>MatchPattern=
</varname></term>
575 <listitem><para>Specifies one or more file name or partition label match patterns that select the
576 subset of files or partitions that are update candidates as targets for this transfer. See above for
577 details on match patterns.
</para>
579 <para>This option is mandatory. Any pattern listed must contain at least the
<literal>@v
</literal>
580 wildcard, so that a version identifier may be extracted from the filename. All other wildcards are
583 <para>This pattern is both used for matching existing installed versions and for determining the name
584 of new versions to install. If multiple patterns are specified, the first specified is used for
585 naming newly installed versions.
</para></listitem>
589 <term><varname>MatchPartitionType=
</varname></term>
591 <listitem><para>When the target
<varname>Type=
</varname> is chosen as
<constant>partition
</constant>,
592 specifies the GPT partition type to look for. Only partitions of this type are considered, all other
593 partitions are ignored. If not specified, the GPT partition type
<constant>linux-generic
</constant>
594 is used. Accepts either a literal type UUID or a symbolic type identifier. For a list of supported
595 type identifiers, see the
<varname>Type=
</varname> setting in
596 <citerefentry><refentrytitle>repart.d
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem>
600 <term><varname>PartitionUUID=
</varname></term>
601 <term><varname>PartitionFlags=
</varname></term>
602 <term><varname>PartitionNoAuto=
</varname></term>
603 <term><varname>PartitionGrowFileSystem=
</varname></term>
605 <listitem><para>When the target
<varname>Type=
</varname> is picked as
<constant>partition
</constant>,
606 selects the GPT partition UUID and partition flags to use for the updated partition. Expects a valid
607 UUID string, a hexadecimal integer, or booleans, respectively. If not set, but the source match
608 pattern includes wildcards for these fields (i.e.
<literal>@u
</literal>,
<literal>@f
</literal>,
609 <literal>@a
</literal>, or
<literal>@g
</literal>), the values from the patterns are used. If neither
610 configured with wildcards or these explicit settings, the values are left untouched. If both the
611 overall
<varname>PartitionFlags=
</varname> flags setting and the individual flag settings
612 <varname>PartitionNoAuto=
</varname> and
<varname>PartitionGrowFileSystem=
</varname> are used (or the
613 wildcards for them), then the latter override the former, i.e. the individual flag bit overrides the
614 overall flags value. See
<ulink url=
"https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
615 Partitions Specification
</ulink> for details about these flags.
</para>
617 <para>Note that these settings are not used for matching, they only have effect on newly written
618 partitions in case a transfer takes place.
</para></listitem>
622 <term><varname>ReadOnly=
</varname></term>
624 <listitem><para>Controls whether to mark the resulting file, subvolume or partition read-only. If the
625 target type is
<constant>partition
</constant> this controls the ReadOnly partition flag, as per
626 <ulink url=
"https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
627 Specification
</ulink>, similar to the
<varname>PartitionNoAuto=
</varname> and
628 <varname>PartitionGrowFileSystem=
</varname> flags described above. If the target type is
629 <constant>regular-file
</constant>, the writable bit is removed from the access mode. If the
630 target type is
<constant>subvolume
</constant>, the subvolume will be marked read-only as a
631 whole. Finally, if the target
<varname>Type=
</varname> is selected as
<constant>directory
</constant>,
632 the
"immutable" file attribute is set, see
<citerefentry
633 project='man-pages'
><refentrytitle>chattr
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
634 details.
</para></listitem>
638 <term><varname>Mode=
</varname></term>
640 <listitem><para>The UNIX file access mode to use for newly created files in case the target resource
641 type is picked as
<constant>regular-file
</constant>. Expects an octal integer, in typical UNIX
642 fashion. If not set, but the source match pattern includes a wildcard for this field
643 (i.e.
<literal>@t
</literal>), the value from the pattern is used.
</para>
645 <para>Note that this setting is not used for matching, it only has an effect on newly written
646 files when a transfer takes place.
</para></listitem>
650 <term><varname>TriesDone=
</varname></term>
651 <term><varname>TriesLeft=
</varname></term>
653 <listitem><para>These options take positive, decimal integers, and control the number of attempts
654 done and left for this file. These settings are useful for managing kernel images, following the
655 scheme defined in
<ulink url=
"https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot
656 Assessment
</ulink>, and only have an effect if the target pattern includes the
<literal>@d
</literal>
657 or
<literal>@l
</literal> wildcards.
</para></listitem>
661 <term><varname>InstancesMax=
</varname></term>
663 <listitem><para>Takes a decimal integer equal to or greater than
2. This configures how many concurrent
664 versions of the resource to keep. Whenever a new update is initiated it is made sure that no more
665 than the number of versions specified here minus one exist in the target. Any excess versions are
666 deleted (in case the target
<varname>Type=
</varname> of
<constant>regular-file
</constant>,
667 <constant>directory
</constant>,
<constant>subvolume
</constant> is used) or emptied (in case the
668 target
<varname>Type=
</varname> of
<constant>partition
</constant> is used; emptying in this case
669 simply means to set the partition label to the special string
<literal>_empty
</literal>; note that no
670 partitions are actually removed). After an update is completed the number of concurrent versions of
671 the target resources is equal to or below the number specified here.
</para>
673 <para>Note that this setting may be set differently for each transfer. However, it generally is
674 advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of
675 files or partitions will be left installed.
</para>
677 <para>If the target
<varname>Type=
</varname> is selected as
<constant>partition
</constant>, the number
678 of concurrent versions to keep is additionally restricted by the number of partition slots of the
679 right type in the partition table. I.e. if there are only
2 partition slots for the selected
680 partition type, setting this value larger than
2 is without effect, since no more than
2 concurrent
681 versions could be stored in the image anyway.
</para></listitem>
685 <term><varname>RemoveTemporary=
</varname></term>
687 <listitem><para>Takes a boolean argument. If this option is enabled (which is the default) before
688 initiating an update, all left-over, incomplete updates from a previous attempt are removed from the
689 target directory. This only has an effect if the target resource
<varname>Type=
</varname> is selected
690 as
<constant>regular-file
</constant>,
<constant>directory
</constant> or
691 <constant>subvolume
</constant>.
</para></listitem>
695 <term><varname>CurrentSymlink=
</varname></term>
697 <listitem><para>Takes a symlink name as argument. If this option is used, as the last step of the
698 update a symlink under the specified name is created/updated pointing to the completed update. This
699 is useful in to provide a stable name always pointing to the newest version of the resource. This is
700 only supported if the target resource
<varname>Type=
</varname> is selected as
701 <constant>regular-file
</constant>,
<constant>directory
</constant> or
702 <constant>subvolume
</constant>.
</para></listitem>
709 <title>Specifiers
</title>
711 <para>Specifiers may be used in the
<varname>MinVersion=
</varname>,
<varname>ProtectVersion=
</varname>,
712 <varname>Path=
</varname>,
<varname>MatchPattern=
</varname> and
<varname>CurrentSymlink=
</varname>
713 settings. The following expansions are understood:
</para>
714 <table class='specifiers'
>
715 <title>Specifiers available
</title>
716 <tgroup cols='
3' align='left' colsep='
1' rowsep='
1'
>
717 <colspec colname=
"spec" />
718 <colspec colname=
"mean" />
719 <colspec colname=
"detail" />
722 <entry>Specifier
</entry>
723 <entry>Meaning
</entry>
724 <entry>Details
</entry>
728 <xi:include href=
"standard-specifiers.xml" xpointer=
"a"/>
729 <xi:include href=
"standard-specifiers.xml" xpointer=
"A"/>
730 <xi:include href=
"standard-specifiers.xml" xpointer=
"b"/>
731 <xi:include href=
"standard-specifiers.xml" xpointer=
"B"/>
732 <xi:include href=
"standard-specifiers.xml" xpointer=
"H"/>
733 <xi:include href=
"standard-specifiers.xml" xpointer=
"l"/>
734 <xi:include href=
"standard-specifiers.xml" xpointer=
"m"/>
735 <xi:include href=
"standard-specifiers.xml" xpointer=
"M"/>
736 <xi:include href=
"standard-specifiers.xml" xpointer=
"o"/>
737 <xi:include href=
"standard-specifiers.xml" xpointer=
"v"/>
738 <xi:include href=
"standard-specifiers.xml" xpointer=
"w"/>
739 <xi:include href=
"standard-specifiers.xml" xpointer=
"W"/>
740 <xi:include href=
"standard-specifiers.xml" xpointer=
"T"/>
741 <xi:include href=
"standard-specifiers.xml" xpointer=
"V"/>
742 <xi:include href=
"standard-specifiers.xml" xpointer=
"percent"/>
747 <para>Do not confuse the
<literal>%
</literal> specifier expansion prefix with the
<literal>@
</literal>
748 pattern matching wildcard prefix. The former are simple shortcuts that are expanded while the drop-in
749 files are parsed, the latter encapsulate a variable part of a match pattern string. For details about
750 pattern matching wildcards, see above.
</para>
754 <title>Examples
</title>
757 <title>Updates for a Verity Enabled Secure OS
</title>
759 <para>With the following three files we define a root file system partition, a matching Verity
760 partition, and a unified kernel image to update as one. This example is an extension of the example
761 discussed earlier in this man page.
</para>
763 <para><programlisting># /usr/lib/sysupdate.d/
50-verity.conf
769 Path=https://download.example.com/
770 MatchPattern=foobarOS_@v_@u.verity.xz
775 MatchPattern=foobarOS_@v_verity
776 MatchPartitionType=root-verity
778 PartitionReadOnly=
1</programlisting></para>
780 <para>The above defines the update mechanism for the Verity partition of the root file system. Verity
781 partition images are downloaded from
782 <literal>https://download.example.com/foobarOS_@v_@u.verity.xz
</literal> and written to a suitable
783 local partition, which is marked read-only. Under the assumption this update is run from the image
784 itself the current image version (i.e. the
<literal>%A
</literal> specifier) is marked as protected, to
785 ensure it is not corrupted while booted. Note that the partition UUID for the target partition is
786 encoded in the source file name. Fixating the partition UUID can be useful to ensure that
787 <literal>roothash=
</literal> on the kernel command line is sufficient to pinpoint both the Verity and
788 root file system partition, and also encode the Verity root level hash (under the assumption the UUID
789 in the file names match their top-level hash, the way
790 <citerefentry><refentrytitle>systemd-gpt-auto-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
793 <para><programlisting># /usr/lib/sysupdate.d/
60-root.conf
799 Path=https://download.example.com/
800 MatchPattern=foobarOS_@v_@u.root.xz
805 MatchPattern=foobarOS_@v
806 MatchPartitionType=root
808 PartitionReadOnly=
1</programlisting></para>
810 <para>The above defines a matching transfer definition for the root file system.
</para>
812 <para><programlisting># /usr/lib/sysupdate.d/
70-kernel.conf
818 Path=https://download.example.com/
819 MatchPattern=foobarOS_@v.efi.xz
824 MatchPattern=foobarOS_@v+@l-@d.efi \
830 InstancesMax=
2</programlisting></para>
832 <para>The above installs a unified kernel image into the ESP (which is mounted to
833 <filename>/efi/
</filename>), as per
<ulink url=
"https://uapi-group.org/specifications/specs/boot_loader_specification">Boot
834 Loader Specification
</ulink> Type #
2. This defines three possible patterns for the names of the
835 kernel images, as per
<ulink url=
"https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot
836 Assessment
</ulink>, and ensures when installing new kernels, they are set up with
3 tries left. No
837 more than two parallel kernels are kept.
</para>
839 <para>With this setup the web server would serve the following files, for a hypothetical version
7 of
843 <listitem><para><filename>SHA256SUMS
</filename> – The manifest file, containing available files and their SHA256 hashes
</para></listitem>
844 <listitem><para><filename>SHA256SUMS.gpg
</filename> – The detached cryptographic signature for the manifest file
</para></listitem>
845 <listitem><para><filename>foobarOS_7_8b8186b1-
2b4e-4eb6-ad39-
8d4d18d2a8fb.verity.xz
</filename> – The Verity image for version
7</para></listitem>
846 <listitem><para><filename>foobarOS_7_f4d1234f-
3ebf-
47c4-b31d-
4052982f9a2f.root.xz
</filename> – The root file system image for version
7</para></listitem>
847 <listitem><para><filename>foobarOS_7_efi.xz
</filename> – The unified kernel image for version
7</para></listitem>
850 <para>For each new OS release a new set of the latter three files would be added, each time with an
851 updated version. The
<filename>SHA256SUMS
</filename> manifest should then be updated accordingly,
852 listing all files for all versions that shall be offered for download.
</para>
856 <title>Updates for Plain Directory Container Image
</title>
858 <para><programlisting>
861 Path=https://download.example.com/
862 MatchPattern=myContainer_@v.tar.gz
866 Path=/var/lib/machines
867 MatchPattern=myContainer_@v
868 CurrentSymlink=myContainer
</programlisting></para>
870 <para>On updates this downloads
<literal>https://download.example.com/myContainer_@v.tar.gz
</literal>
871 and decompresses/unpacks it to
<filename>/var/lib/machines/myContainer_@v
</filename>. After each update
872 a symlink
<filename>/var/lib/machines/myContainer
</filename> is created/updated always pointing to the
873 most recent update.
</para>
878 <title>See Also
</title>
880 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
881 <citerefentry><refentrytitle>systemd-sysupdate
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
882 <citerefentry><refentrytitle>systemd-repart
</refentrytitle><manvolnum>8</manvolnum></citerefentry>