NAME¶

sysupdate.d - Transfer Definition Files for Automatic Updates

SYNOPSIS¶

DESCRIPTION¶

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 — but in fact may be used to update any kind of file from a remote source.

The systemd-sysupdate(8) command reads these files and uses them to determine which local resources should be updated, and then executes the update.

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, ...).

Each *.transfer 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'll call such a collection of transfers a target. systemd-sysupdate always operates on a single target.

Transfers may be grouped together into sets that can be individually enabled or disabled by the system administrator, called "Optional Features": sysupdate.features(5).

Each *.transfer file contains three sections: [Transfer], [Source] and [Target].

BASIC MODE OF OPERATION¶

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:

The version-independent generalization of this would be (using the special marker "@v" as wildcard for the version identifier):

An update can only complete if the relevant URLs provide their resources for the same version, i.e. for the same value of "@v".

The above may be translated into three *.transfer files in sysupdate.d/, one for each resource to transfer. The *.transfer 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.

In order to enumerate available versions and figuring out candidates to update to, a mechanism is necessary to list suitable files:

Transfers are done in the alphabetical order of the .transfer 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 MatchPattern=, again in the order the .transfer 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.

See below for an extended, more specific example based on the above.

RESOURCE TYPES¶

Each transfer file defines one source resource to transfer to one target resource. The following resource types are supported:

As already indicated, only a subset of source and target resource type combinations are supported:

Table 1. Resource Types

MATCH PATTERNS¶

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
MatchPattern= 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:

Table 2. Match Pattern Wildcards

Of these wildcards only
"@v" 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 "MatchPattern=foobar_@v.raw.xz", i.e. any file whose name begins with "foobar_", followed by a version ID and suffixed by ".raw.xz".

Do not confuse the "@" pattern matching wildcard prefix with the "%" 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.

[TRANSFER] SECTION OPTIONS¶

This section defines general properties of this transfer.

MinVersion=

ProtectVersion=

Verify=

ChangeLog=

AppStream=

Features=

RequisiteFeatures=

[SOURCE] SECTION OPTIONS¶

This section defines properties of the transfer source.

Type=

Path=

MatchPattern=

[TARGET] SECTION OPTIONS¶

This section defines properties of the transfer target.

Type=

Path=

PathRelativeTo=

MatchPattern=

MatchPartitionType=

PartitionUUID=, PartitionFlags=, PartitionNoAuto=, PartitionGrowFileSystem=

ReadOnly=

Mode=

TriesDone=, TriesLeft=

InstancesMax=

RemoveTemporary=

CurrentSymlink=

SPECIFIERS¶

Specifiers may be used in the MinVersion=, ProtectVersion=, Path=, MatchPattern= and CurrentSymlink= settings. The following expansions are understood:

Table 3. Specifiers available

Do not confuse the
"%" specifier expansion prefix with the "@" 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.

EXAMPLES¶

Example 1. Updates for a Verity Enabled Secure OS

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.

# /usr/lib/sysupdate.d/50-verity.transfer
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v_@u.verity.xz
[Target]
Type=partition
Path=auto
MatchPattern=foobarOS_@v_verity
MatchPartitionType=root-verity
PartitionFlags=0
ReadOnly=1

The above defines the update mechanism for the Verity partition of the root file system. Verity partition images are downloaded from "https://download.example.com/foobarOS_@v_@u.verity.xz" 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 "%A" 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 "roothash=" 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 systemd-gpt-auto-generator(8) suggests).

# /usr/lib/sysupdate.d/60-root.transfer
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v_@u.root.xz
[Target]
Type=partition
Path=auto
MatchPattern=foobarOS_@v
MatchPartitionType=root
PartitionFlags=0
ReadOnly=1

The above defines a matching transfer definition for the root file system.

# /usr/lib/sysupdate.d/70-kernel.transfer
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v.efi.xz
[Target]
Type=regular-file
Path=/EFI/Linux
PathRelativeTo=boot
MatchPattern=foobarOS_@v+@l-@d.efi \


             foobarOS_@v+@l.efi \


             foobarOS_@v.efi
Mode=0444
TriesLeft=3
TriesDone=0
InstancesMax=2

The above installs a unified kernel image into the $BOOT partition, as per Boot Loader Specification[2] Type #2. This defines three possible patterns for the names of the kernel images, as per Automatic Boot Assessment[3], and ensures when installing new kernels, they are set up with 3 tries left. No more than two parallel kernels are kept.

With this setup the web server would serve the following files, for a hypothetical version 7 of the OS:

For each new OS release a new set of the latter three files would be added, each time with an updated version. The SHA256SUMS manifest should then be updated accordingly, listing all files for all versions that shall be offered for download.

Example 2. Updates for Plain Directory Container Image

[Source]
Type=url-tar
Path=https://download.example.com/
MatchPattern=myContainer_@v.tar.gz
[Target]
Type=subvolume
Path=/var/lib/machines
MatchPattern=myContainer_@v
CurrentSymlink=myContainer

On updates this downloads "https://download.example.com/myContainer_@v.tar.gz" and decompresses/unpacks it to /var/lib/machines/myContainer_@v. After each update a symlink /var/lib/machines/myContainer is created/updated always pointing to the most recent update.

SEE ALSO¶

systemd(1), systemd-sysupdate(8), systemd-repart(8)

NOTES¶

1.

Discoverable Partitions Specification

2.

Boot Loader Specification

3.

Automatic Boot Assessment

4.

AppStream catalog

5.

special metadata