SYSUPDATE.D(5)

๐Ÿ“ฆ
version 262.1 ยท 14 versions
, in arch rolling

๐ŸŽ€ NAME ๐ŸŽ€

sysupdate.d โ€” Transfer Definition Files for Automatic Updates ๐Ÿ’–

okay bestie so this is the manual for sysupdate.d, the little directory full of files that tell your system exactly how to update itself. no cap.

โœจ SYNOPSIS โœจ

/etc/sysupdate.d/*.transfer
/run/sysupdate.d/*.transfer
/usr/local/lib/sysupdate.d/*.transfer
/usr/lib/sysupdate.d/*.transfer

๐Ÿฆ‹ DESCRIPTION ๐Ÿฆ‹

So these files? They describe how specific resources on the local system shall be updated from a remote source. Every single one of these files defines one such transfer: typically a remote HTTP/HTTPS resource as the source, and a local file, directory or partition as the target. Lowkey iconic. You can use this as a simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system extension images โ€” but fr fr it 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. it's giving "just read the config and do the thing".

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, ...). so many versions. so much slay.

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(8) always operates on a single target. one target at a time, bestie, it's not multitasking.

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]. three sections, that's it, that's the whole vibe.

๐ŸŒˆ 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:

  1. A file https://download.example.com/foobarOS_47.root.xz 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 UAPI.2 Discoverable Partitions Specification[1]. ๐Ÿซถ
  2. Similarly, a file https://download.example.com/foobarOS_47.verity.xz 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). ๐Ÿ”ฅ
  3. Finally, a file https://download.example.com/foobarOS_47.efi (a unified kernel, as per UAPI.1 Boot Loader Specification[2] Type #2) should be downloaded, decompressed and written to the $BOOT file system, i.e. to EFI/Linux/foobarOS_47.efi in the ESP or XBOOTLDR partition. ๐Ÿ‘‘

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

  1. A transfer of a file https://download.example.com/foobarOS_@v.root.xz โ†’ a local, previously empty GPT partition of type 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, with the label to be set to "foobarOS_@v".
  2. A transfer of a file https://download.example.com/foobarOS_@v.verity.xz โ†’ a local, previously empty GPT partition of type 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5, with the label to be set to "foobarOS_@v_verity".
  3. A transfer of a file https://download.example.com/foobarOS_@v.efi โ†’ a local file $BOOT/EFI/Linux/foobarOS_@v.efi.

An update can only complete if the relevant URLs provide their resources for the same version, i.e. for the same value of "@v". so like, if one of them is out here on version 46 and the rest are on 47? nope. not happening. ๐Ÿ™ˆ

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:

  • 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).
  • For regular files: the directory listing of the directory the files are contained in provides a list of existing files in a straightforward way.
  • For HTTP/HTTPS sources a simple scheme is used: a manifest file SHA256SUMS, following the format defined by sha256sum(1), lists file names and their SHA256 hashes.

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. ๐Ÿงš

๐Ÿ’€ bestie listen to me: put the boot entry point LAST alphabetically. if something dies mid-update you do NOT want a bootable thing pointing at a partition that doesn't exist yet. that's the whole reason. ok love u.

See below for an extended, more specific example based on the above. ๐ŸŒธ

๐ŸŒˆ RESOURCE TYPES ๐ŸŒˆ

Okay bestie, so every transfer file defines one source resource that gets transferred to one target resource. That's the whole vibe. And here are the resource types you can work with:

  1. url-file โ€” this one wraps up a file sitting on a web server, referenced by an HTTP or HTTPS URL. When an update happens, the file gets downloaded, decompressed, and then written to the target file or partition. Heads up: this type is only available for sources, never for targets. The list of available versions of resources of this type lives in SHA256SUMS manifest files, and those come with SHA256SUMS.gpg detached signatures alongside them. ๐Ÿ’…
  2. url-tar โ€” basically the same energy, but the file has to be a .tar archive. On update, it gets decompressed and unpacked into a directory or a btrfs subvolume. Also sources only, no targets, sorry. And just like url-file, the version enumeration uses SHA256SUMS files, authenticated via SHA256SUMS.gpg.
  3. regular-file โ€” this one is a local regular file on disk. During updates it's uncompressed and written to the target file or partition. This type works as both source and target. But ngl, when updating, no integrity or authentication verification is done for resources of this type. None. Zero. ๐Ÿ™ˆ
  4. partition โ€” similar to regular-file, but it wraps a GPT partition on disk. When updating, the partition has to already exist and have the correct GPT partition type. A partition whose GPT partition label is set to "_empty" counts as empty, and is a candidate to place a newly downloaded resource in. Once a partition gets updated, the GPT partition label is where version info is stored. This type is targets only.
  5. tar โ€” local .tar archive files. On update, the files get uncompressed and unpacked into a target directory or btrfs subvolume. Behaviour of tar and url-tar is generally similar, except the latter downloads from remote sources and does integrity and authentication checks, while the former does not. Sources only for this one.
  6. directory โ€” local directory trees. Available for both source and target resources. If an update takes place on a source resource of this type, a recursive copy of the directory happens.
  7. subvolume โ€” identical to directory, except when it's used as the target: in that case the file tree goes into a btrfs subvolume instead of a plain directory, as long as the backing file system supports it (i.e. it's btrfs).

And like I already hinted, only a subset of source + target resource type combos are supported. Here's the whole tea:

๐Ÿ“‹ Table 1. Resource Types

  • url-file โ€” HTTP/HTTPS files
    • Usable as source: yes
    • When used as source โ€” compatible targets: regular-file, partition
    • When used as source โ€” integrity + authentication: yes
    • When used as source โ€” decompression: yes
    • Usable as target: no
    • When used as target โ€” compatible sources: -
  • url-tar โ€” HTTP/HTTPS .tar archives
    • Usable as source: yes
    • When used as source โ€” compatible targets: directory, subvolume
    • When used as source โ€” integrity + authentication: yes
    • When used as source โ€” decompression: yes
    • Usable as target: no
    • When used as target โ€” compatible sources: -
  • regular-file โ€” Local files
    • Usable as source: yes
    • When used as source โ€” compatible targets: regular-file, partition
    • When used as source โ€” integrity + authentication: no
    • When used as source โ€” decompression: yes
    • Usable as target: yes
    • When used as target โ€” compatible sources: url-file, regular-file
  • partition โ€” Local GPT partitions
    • Usable as source: no
    • When used as source โ€” compatible targets: -
    • When used as source โ€” integrity + authentication: -
    • When used as source โ€” decompression: -
    • Usable as target: yes
    • When used as target โ€” compatible sources: url-file, regular-file
  • tar โ€” Local .tar archives
    • Usable as source: yes
    • When used as source โ€” compatible targets: directory, subvolume
    • When used as source โ€” integrity + authentication: no
    • When used as source โ€” decompression: yes
    • Usable as target: no
    • When used as target โ€” compatible sources: -
  • directory โ€” Local directories
    • Usable as source: yes
    • When used as source โ€” compatible targets: directory, subvolume
    • When used as source โ€” integrity + authentication: no
    • When used as source โ€” decompression: no
    • Usable as target: yes
    • When used as target โ€” compatible sources: url-tar, tar, directory, subvolume
  • subvolume โ€” Local btrfs subvolumes
    • Usable as source: yes
    • When used as source โ€” compatible targets: directory, subvolume
    • When used as source โ€” integrity + authentication: no
    • When used as source โ€” decompression: no
    • Usable as target: yes
    • When used as target โ€” compatible sources: url-tar, tar, directory, subvolume

Now, the SHA256SUMS manifest files used by the url-file and url-tar resource types follow the usual file format that GNU's sha256sum(1) tool generates. It's recommended to use --binary mode, even if that has no real effect on Linux systems. The listing should only contain ASCII characters, no cap. Entries are usually plain file names, but they may also be relative subpaths (e.g., "foo_1/bar.efi").

Okay so here's the strict part: absolute paths, non-normalized paths containing "./", "../", or "//" components, and entries containing a "%" character are all rejected. Periodt.

And one more lil spicy detail: if the SHA256SUMS listing contains a special file "BEST-BEFORE-YYYY-MM-DD" (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. ๐Ÿ‘‘

๐Ÿฆ‹ MATCH PATTERNS ๐Ÿฆ‹

Bestie, here's the situation: 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. Simple enough, right?

So to figure out the newest version of the resources, one of these gets used: a directory listing, a partition listing, or a manifest listing. Then a subset of qualifying entries is selected from that, and the version identifier gets extracted from the file names or partition labels of those selected entries.

The subset selection and the 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 โœจ

okay bestie here's the full wildcard menu, every single one, no skips ๐Ÿ’…

  • @v โ€” Version identifier. Format: a valid version string. Mandatory โ€” this one is literally required, she's the main character ๐Ÿ‘‘
  • @u โ€” GPT partition UUID. Format: a valid 128-Bit UUID string. Only relevant if the target resource type is chosen as partition. ๐ŸŽ€
  • @f โ€” GPT partition flags. Format: formatted hexadecimal integer. Only relevant if the target resource type is chosen as partition. ๐ŸŽ€
  • @a โ€” GPT partition flag NoAuto. Format: either "0" or "1". Controls the NoAuto bit of the GPT partition flags, as per UAPI.2 Discoverable Partitions Specification[1]; only relevant if the target resource type is chosen as partition. ๐Ÿซถ
  • @g โ€” GPT partition flag GrowFileSystem. Format: either "0" or "1". Controls the GrowFileSystem bit of the GPT partition flags, as per UAPI.2 Discoverable Partitions Specification[1]; only relevant if the target resource type is chosen as partition. ๐Ÿซถ
  • @r โ€” Read-only flag. Format: either "0" or "1". Controls the ReadOnly bit of the GPT partition flags, as per UAPI.2 Discoverable Partitions Specification[1] and other output read-only flags, see ReadOnly= below. ๐Ÿ’–
  • @t โ€” File modification time. Format: formatted decimal integer, ฮผs since UNIX epoch Jan 1st 1970. Only relevant if the target resource type is chosen as regular-file. โญ
  • @m โ€” File access mode. Format: formatted octal integer, in UNIX fashion. Only relevant if the target resource type is chosen as regular-file. โญ
  • @s โ€” File size after decompression. Format: formatted decimal integer. Useful for measuring progress and to improve partition allocation logic. ๐Ÿ”ฅ
  • @d โ€” Tries done. Format: formatted decimal integer. Useful when operating with kernel image files, as per Automatic Boot Assessment[3]. ๐ŸŒธ
  • @l โ€” Tries left. Format: formatted decimal integer. Useful when operating with kernel image files, as per Automatic Boot Assessment[3]. ๐ŸŒธ
  • @h โ€” SHA256 hash of compressed file. Format: 64 hexadecimal characters. This is the SHA256 hash of the compressed file; it's not useful for url-file or url-tar, where the SHA256 hash is already included in the manifest file anyway. ๐Ÿ’€

so like, of all these wildcards, only @v has to be present in a valid pattern โ€” every other one is optional, do whatever feels right โœจ And heads up: each wildcard may be used at most once in each pattern, so no double-dipping, she's not that kind of girl ๐Ÿ™ˆ

a typical wildcard matching a file system source image would be like:

MatchPattern=foobar_@v.raw.xz

which means: any file whose name begins with foobar_, followed by a version ID, and suffixed by .raw.xz. cute right? ๐Ÿฆ‹

๐Ÿงš the **/ prefix thing

a source MatchPattern= may additionally be prefixed with **/. It can not contain **/ anywhere else, and no further subdirectories are allowed in the rest of the pattern. ๐Ÿšซ

This prefix matches any number of nested subdirectories โ€” or none at all โ€” which basically means only the basenames get matched against the rest of the pattern. lowkey elegant. โœจ

not me clarifying this: the **/ prefix is not a wildcard like the ones in the table up there, because it captures nothing and it can't be used in a target MatchPattern=. It's also not supported for the source types directory and subvolume. ๐Ÿ™…โ€โ™€๏ธ

๐Ÿ’… do NOT confuse the two

okay this is the classic mix-up, pay attention bestie:

  • the @ pattern matching wildcard prefix
  • the % specifier expansion prefix

Completely different things. The former encapsulates a variable part of a match pattern string. The latter are just simple shortcuts that get expanded while the drop-in files are parsed. ๐Ÿ“

For all the details about specifiers, see below. ๐Ÿ‘€

โœจ [TRANSFER] SECTION OPTIONS โœจ

okay bestie, this section is literally the general-properties era of this transfer โ€” it sets the whole vibe for what this transfer is allowed to do. ๐Ÿ’…

  • MinVersion= โ€” sets the minimum version that this transfer needs in order to actually happen. If the source or target patterns in this transfer definition match files older than this version, those files are considered obsolete and will never be considered for the update operation. Added in version 251.
  • ProtectVersion= โ€” takes one or more version strings and marks them 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, so runtime file system corruptions stay avoided. Like many of the settings in these configuration files, this setting supports specifier expansion. It's especially useful to set this setting to one of the %A, %B or %w specifiers to automatically refer to the current OS version of the running system. See below for details on supported specifiers. Added in version 251.
  • Verify= โ€” takes a boolean, defaults to yes. This controls whether to cryptographically verify downloaded resources โ€” specifically: validate the GPG signatures for downloaded SHA256SUMS manifest files, via their detached signature files SHA256SUMS.gpg, in combination with the system keyring consisting of /usr/lib/systemd/import-pubring.pgp and the local keyring in /etc/systemd/import-pubring.pgp (or, if that does not exist, /etc/systemd/import-pubring.gpg). This option is essential to provide integrity guarantees for downloaded resources and thus should be left enabled, outside of test environments. 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. This option only has an effect if the source resource type is selected as url-file or url-tar, as integrity and authentication checking is only available for transfers from remote sources. Added in version 251.
  • ChangeLog= โ€” optionally takes a human-presentable URL to a website containing a change-log of the resource being updated. 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. This setting supports specifier expansion. See below for details on supported specifiers. This setting will also expand the "@v" wildcard pattern. See above for details. Added in version 257.
  • AppStream= โ€” optionally takes a URL to an AppStream catalog[4] 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 special metadata[5] to be correctly associated with systemd-sysupdate(8) by the software centers. This setting supports specifier expansion. See below for details on supported specifiers. Added in version 257.
  • Features= โ€” a space-separated list of sysupdate.features(5) 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: "Features=foo bar" specifies that the transfer belongs to "foo.feature" and "bar.feature". 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 any 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. Added in version 257.
  • RequisiteFeatures= โ€” this is like Features=, except that all 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 Features= is enabled. Added in version 257.

๐Ÿฆ‹ [SOURCE] SECTION OPTIONS ๐Ÿฆ‹

this section defines properties of the transfer source. it's giving origin story, but for files. ๐Ÿ’–

  • Type= โ€” specifies the resource type of the source for the transfer. Takes one of url-file, url-tar, tar, regular-file, directory or subvolume. For details about the resource types, see above. This option is mandatory. Note that only certain combinations of source and target resource types are supported, see above. Added in version 251.
  • Path= โ€” specifies where to find source versions of this resource. If the source type is selected as url-file or url-tar this must be a HTTP/HTTPS URL. The URL is suffixed with /SHA256SUMS to acquire the manifest file, with /SHA256SUMS.gpg 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. 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. Added in version 251.
  • MatchPattern= โ€” 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. This option is mandatory. Any pattern listed must contain at least the "@v" wildcard, so that a version identifier may be extracted from the filename. All other wildcards are optional. The pattern may contain slash characters. In this case, it will match the file or directory in the corresponding subdirectory. For example "MatchPattern=foo_@v/bar.efi" will match "bar.efi" in directory "foo_1". For url-file and url-tar sources, the corresponding SHA256SUMS manifest may then list entries as subpaths such as "foo_1/bar.efi"; such entries are fetched from the matching subpath of the source URL. Manifest entries that are absolute, non-normalized (containing "./", "../", or "//" components), or that contain a "%" character are rejected. A "**/" prefix on a source MatchPattern= matches any number of subdirectories and will as a result only match the basename against the rest of the pattern. For url-file and url-tar sources, SHA256SUMS entries may then list the file under any subpath and the subpath is still used to construct the actual download URL. The pattern after "**/" must not contain further slashes. The prefix is not accepted on target patterns or for the source Type=directory and Type=subvolume. Added in version 251.

๐ŸŽฏ [TARGET] SECTION OPTIONS ๐ŸŽฏ

Okay bestie, this section is all about the target โ€” the place where stuff actually lands. The source gives, the target receives. ๐Ÿ’…

  • Type= โ€” Says what kind of resource the target is. You gotta pick exactly one of partition, regular-file, directory or subvolume. Wanna know what those resource types actually mean? Scroll up, it's all there. โœจ This one is mandatory, no skipping it.

Heads up though: only certain combos of source type + target type actually work. The full list is above, go check it. ๐Ÿ‘€

Added in version 251.

  • Path= โ€” Where to look for versions you already installed, or where to drop the new ones you just downloaded for this resource. If Type= is partition, this expects a path to a (whole) block device node โ€” or the special string "auto", which is the vibe where the block device holding the root file system of the currently booted system gets auto-detected and used for you. ๐Ÿฆ‹ If Type= is regular-file, directory or subvolume, it has to be a path in the local file system pointing at the directory where the version files or directories live (or will live).
Real talk: this mechanism cannot create or remove partitions when Type= is partition. The partitions have to already exist, and a special partition label "_empty" is what marks empty partitions. If you want suitable partitions auto-generated on first boot, go use a tool like systemd-repart(8). ๐Ÿซถ

Added in version 251.

  • PathRelativeTo= โ€” Tells you what Path= is relative to. Takes one of root, esp, xbootldr, boot or explicit. If you don't set it, it defaults to root.
    • Set it to root, esp or xbootldr and your Path= gets resolved relative to the mount point of the matching partition, exactly as defined by the UAPI.1 Boot Loader Specification[2]. ๐Ÿ‘‘
    • Set it to boot and Path= resolves relative to the mount point of the $BOOT partition (that's the ESP or XBOOTLDR), as defined by the UAPI.1 Boot Loader Specification[2]. ๐ŸŒธ
    • Set it to explicit and Path= resolves relative to the directory you gave with --transfer-source= when you invoked systemd-sysupdate(8). ๐ŸŽ€

The values esp, xbootldr and boot are only supported when Type= is regular-file or directory. No cap.

Added in version 254.

  • MatchPattern= โ€” One or more file name or partition label match patterns that pick out which files or partitions count as update candidates for this transfer. The full match-pattern lore is above. ๐Ÿ”

This one is mandatory too. Every pattern you list must contain at least the "@v" wildcard, so a version identifier can be extracted from the filename. All the other wildcards are optional. โœจ

This pattern does double duty: it matches existing installed versions and it figures out what to name new versions when installing. If you list multiple patterns, the first one is the one used to name newly installed versions. ๐Ÿฅ‡

If the target type is regular-file or directory, the pattern is allowed to contain slash characters. In that case it matches the file or directory inside the corresponding subdirectory. For example, "MatchPattern=foo_@v/bar.efi" matches "bar.efi" inside the directory "foo_1". Directories along the path get created when the file is installed, and empty directories get removed when the file is removed. Clean. ๐Ÿงน

Added in version 251.

  • MatchPartitionType= โ€” When target Type= is partition, this says which GPT partition type to look for. Only partitions of that type are considered, everything else is ignored, sorry not sorry. ๐Ÿ’… If you don't specify it, the GPT partition type linux-generic is used. It accepts either a literal type UUID or a symbolic type identifier. For the list of supported type identifiers, go see the Type= setting in repart.d(5).

Added in version 251.

  • PartitionUUID=, PartitionFlags=, PartitionNoAuto=, PartitionGrowFileSystem= โ€” When target Type= is partition, these pick the GPT partition UUID and the partition flags to use on the updated partition. They expect a valid UUID string, a hexadecimal integer, or booleans, respectively. ๐ŸŽฏ If you don't set them, but the source match pattern has wildcards for those fields (that's "@u", "@f", "@a", or "@g"), then the values from the patterns get used instead. If neither the wildcards nor these explicit settings are there, the values are just left untouched. And if you use both the overall PartitionFlags= flags setting and the individual PartitionNoAuto= and PartitionGrowFileSystem= settings (or the wildcards for them), the individual ones win โ€” i.e. the individual flag bit overrides the overall flags value. Want the details on these flags? UAPI.2 Discoverable Partitions Specification[1], babes. ๐Ÿ“–
Note note note: these settings are not used for matching. They only do anything to newly written partitions when an actual transfer happens. ๐Ÿ”ฅ

Added in version 251.

  • PartitionZeroFill= โ€” Takes a boolean. When target Type= is partition, this controls whether the leftover space in the partition gets overwritten with zeroes after the payload has been written in. If it's disabled, only as much of the partition as the payload is large gets written, and whatever data was sitting in the rest of the partition just... stays there. ๐Ÿ’€ If it's enabled, everything from the end of the payload all the way to the end of the partition gets zeroed out, so no remnants of an earlier, bigger payload survive. On block devices this gets offloaded to the kernel and therefore to the storage device itself where possible. ๐Ÿ˜Œ

If you don't specify it, it defaults to on for Verity signature partitions (that's when MatchPartitionType= selects one of the "*-verity-sig" types) and off for all other partition types. Why? Because Verity signature partitions carry a JSON object that has to be followed by zero bytes only, all the way to the end of the partition โ€” while the artifacts installed into them (for example the ones generated via the --split= mode of systemd-repart(8)) generally don't carry that padding. Makes sense, right? ๐Ÿง 

Added in version 263.

  • ReadOnly= โ€” Controls whether the resulting file, subvolume or partition gets marked read-only. ๐Ÿ”’ If the target type is partition, this controls the ReadOnly partition flag, per UAPI.2 Discoverable Partitions Specification[1], similar to the PartitionNoAuto= and PartitionGrowFileSystem= flags we just talked about. If the target type is regular-file, the writable bit gets removed from the access mode. If the target type is subvolume, the whole subvolume gets marked read-only. And finally, if the target Type= is directory, the "immutable" file attribute gets set โ€” see chattr(1) for the deets. ๐Ÿ’…

Added in version 251.

  • Mode= โ€” The UNIX file access mode to use for newly created files, when the target resource type is regular-file. Expects an octal integer, classic UNIX style. ๐Ÿง If it's not set, but the source match pattern has a wildcard for this field (that's "@t"), the value from the pattern gets used.
Again bestie: this setting is not used for matching. It only does something to newly written files when a transfer happens. โœจ

Added in version 251.

  • TriesDone=, TriesLeft= โ€” These take positive, decimal integers, and they control the number of attempts done and left for this file. Super useful for managing kernel images, following the scheme defined in Automatic Boot Assessment[3]. They only have any effect if the target pattern includes the "@d" or "@l" wildcards. ๐Ÿ‘‘

Added in version 251.

  • InstancesMax= โ€” Takes a decimal integer that's equal to or greater than 2. This configures how many concurrent versions of the resource to keep. Whenever a new update kicks off, it makes sure no more than the number you specified here minus one exist in the target. Anything extra gets deleted (if target Type= is regular-file, directory or subvolume) or emptied (if target Type= is partition โ€” and "emptied" here just means setting the partition label to the special string "_empty"; no partitions actually get removed, promise ๐Ÿซถ). Once an update finishes, the number of concurrent versions of the target resources is equal to or below the number you set here. โœจ
This setting can totally be different for each transfer. But honestly? It's generally advisable to keep it the same across all of them, because otherwise you'll end up with incomplete combos of files or partitions left installed. Messy. ๐Ÿ™ˆ

If target Type= is partition, the number of concurrent versions to keep gets additionally restricted by how many partition slots of the right type exist in the partition table. Like, if there are only 2 partition slots for the selected partition type, setting this larger than 2 does literally nothing โ€” you couldn't store more than 2 concurrent versions in that image anyway. ๐Ÿ’€

Added in version 251.

  • RemoveTemporary= โ€” Takes a boolean argument. If this is enabled (and it is the default), then before an update starts, all the left-over, incomplete updates from a previous attempt get removed from the target directory. ๐Ÿงน This only has an effect if the target resource Type= is regular-file, directory or subvolume.

Added in version 251.

  • CurrentSymlink= โ€” Takes a symlink name as its argument. If you use this, then as the very last step of the update, a symlink under the name you gave gets created/updated pointing at the completed update. ๐ŸŽ€ So useful for having one stable name that always points to the newest version of the resource. This is only supported if the target resource Type= is regular-file, directory or subvolume.

Added in version 251.

โœจ SPECIFIERS โœจ

Specifiers are allowed in the MinVersion=, ProtectVersion=, Path=, MatchPattern= and CurrentSymlink= settings. The following expansions are understood ๐Ÿ‘‡

โœจ Table 3. Specifiers available โœจ

okay bestie, here's the full roster of specifiers โ€” every single one, no skips ๐Ÿ’–

  • "%a" โ€” Architecture. A short string identifying the architecture of the local system. Like a string such as x86, x86-64 or arm64. Wanna see the whole list? Check the architectures defined for ConditionArchitecture= in systemd.unit(5). ๐Ÿฆ‹
  • "%A" โ€” Operating system image version. The operating system image version identifier of the running system, read from the IMAGE_VERSION= field of /etc/os-release. If it's not set, it resolves to an empty string. See os-release(5) for more.
  • "%b" โ€” Boot ID. The boot ID of the running system, formatted as string. See random(4) for more info. ๐ŸŽ€
  • "%B" โ€” Operating system build ID. The operating system build identifier of the running system, read from the BUILD_ID= field of /etc/os-release. Not set? Resolves to an empty string. See os-release(5).
  • "%H" โ€” Host name. The hostname of the running system. Simple as that. ๐Ÿ’…
  • "%l" โ€” Short host name. The hostname of the running system, truncated at the first dot to remove any domain component. So myhost.example.com girlies become just myhost. โœจ
  • "%m" โ€” Machine ID. The machine ID of the running system, formatted as string. See machine-id(5) for more.
  • "%M" โ€” Operating system image identifier. The operating system image identifier of the running system, read from the IMAGE_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more.
  • "%o" โ€” Operating system ID. The operating system identifier of the running system, read from the ID= field of /etc/os-release. See os-release(5) for more info.
  • "%v" โ€” Kernel release. Identical to uname -r output. no cap ๐Ÿ”ฅ
  • "%w" โ€” Operating system version ID. The operating system version identifier of the running system, read from the VERSION_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5).
  • "%W" โ€” Operating system variant ID. The operating system variant identifier of the running system, read from the VARIANT_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5).
  • "%T" โ€” Directory for temporary files. 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.) ๐ŸŒธ
  • "%V" โ€” Directory for larger and persistent temporary files. 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.)
  • "%%" โ€” Single percent sign. Use "%%" in place of "%" to specify a single percent sign. iykyk ๐Ÿ’œ
โš ๏ธ do NOT confuse the "%" specifier expansion prefix with the "@" pattern matching wildcard prefix, bestie. They are not the same vibe. The former are simple shortcuts that get expanded while the drop-in files are parsed; the latter encapsulate a variable part of a match pattern string. For the deets about pattern matching wildcards, see above. ๐Ÿ‘‘

not me making percent signs sound like a whole personality... but fr fr, that distinction matters ๐Ÿ’€

๐Ÿ’– EXAMPLES ๐Ÿ’–

Okay bestie, this is the part where it all comes together and honestly? It's giving main character energy. Two whole real-life setups, step by step. Grab a snack. ๐Ÿ“

๐ŸŒธ Example 1. Updates for a Verity Enabled Secure OS

So with the following three files we define a root file system partition, a matching Verity partition, and a unified kernel image, all updated as one thing. This is an extension of the example we talked about earlier in this man page, iykyk.

# /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. ๐Ÿ’…

Not me pointing out 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. Slay, they match. โœจ

# /usr/lib/sysupdate.d/70-kernel.transfer
[Transfer]
ProtectVersion=%A

[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v.efi

[Target]
Type=regular-file
Path=/EFI/Linux
PathRelativeTo=boot
MatchPattern=foobarOS_@v+@l-@d.efi \
             foobarOS_@v+@l.efi \
             foobarOS_@v.efi
Mode=0644
TriesLeft=3
TriesDone=0
InstancesMax=2

The above installs a unified kernel image into the $BOOT partition, as per UAPI.1 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. Obsessed with the tidiness tbh. ๐ŸŽ€

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

  • SHA256SUMS โ€“ The manifest file, containing available files and their SHA256 hashes
  • SHA256SUMS.gpg โ€“ The detached cryptographic signature for the manifest file
  • foobarOS_7_8b8186b1-2b4e-4eb6-ad39-8d4d18d2a8fb.verity.xz โ€“ The Verity image for version 7
  • foobarOS_7_f4d1234f-3ebf-47c4-b31d-4052982f9a2f.root.xz โ€“ The root file system image for version 7
  • foobarOS_7.efi โ€“ The unified kernel image for version 7

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. It's giving always-fresh, never-stale. ๐ŸŒˆ

โœจ SEE ALSO โœจ

systemd(1), systemd-sysupdate(8), sysupdate.features(5), sysupdate.components(5), systemd-repart(8)

๐Ÿ“š NOTES ๐Ÿ“š

  1. UAPI.2 Discoverable Partitions Specification https://uapi-group.org/specifications/specs/discoverable_partitions_specification
  2. UAPI.1 Boot Loader Specification https://uapi-group.org/specifications/specs/boot_loader_specification
  3. Automatic Boot Assessment https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
  4. AppStream catalog https://www.freedesktop.org/software/appstream/docs/chap-CatalogData.html
  5. special metadata https://systemd.io/APPSTREAM_BUNDLE
๐Ÿ’€ okay that's the whole page, bestie. You read a whole manual page. That's lowkey iconic.

systemd 262.1 energy, SYSUPDATE.D(5), and yeah โ€” that version/date footer at the bottom of the page is just this page saying hi from itself. Go forth and sysupdate, you absolute legend. ๐Ÿซถ๐Ÿ‘‘

๐Ÿ“ฆ where this page comes from
  • arch rolling: systemd 262.1-1 ยท LGPL-2.1-or-later AND CC0-1.0 AND GPL-2.0-or-later AND MIT-0
  • ๐Ÿ’– girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms