SYSTEMD-SYSUPDATE(8)

🌈 systemd-sysupdate — bestie's guide to automatically updating your OS (and other stuff too) 💅

okay so first things first, this is the manual page for systemd-sysupdate (that's SYSTEMD-SYSUPDATE(8) if you're being formal, which we are not). It covers a whole little friend group of units: systemd-sysupdate, systemd-sysupdate-update.service, systemd-sysupdate-update.timer, systemd-sysupdate-reboot.service, systemd-sysupdate-reboot.timer, systemd-sysupdate-auto-enable.service, systemd-sysupdate.service, and systemd-sysupdate.timer. Their whole collective vibe? Automatically Update OS or Other Resources. slay.

---

✨ SYNOPSIS ✨

systemd-sysupdate [OPTIONS...]

systemd-sysupdate-update.service

---

🧪 EXPERIMENTAL 🧪

okay bestie, deep breath. This component is experimental and subject to change without advance notice. It will be stabilized and given a backward-compatibility guarantee in a future release, but it might also possibly be removed. So like… it's giving "situationship with the kernel". be aware. 💀

---

💖 DESCRIPTION 💖

So systemd-sysupdate atomically updates the host OS, container images, portable service images, or other sources — all based on the transfer configuration files described over in sysupdate.d(5).

This tool implements file, directory, or partition based update schemes, and it supports multiple parallel installed versions of specific resources in an A/B style (or even A/B/C, A/B/C/D/, … sky's the limit honestly). What does A/B updating mean, you ask? 🦋 It means that when one version of a resource is currently being used, the next version can be downloaded, unpacked, and prepared in an entirely separate location, independently of the first — and once it's complete, it gets activated, swapping the roles so that the new one becomes the used one and the previously used one becomes the one that gets replaced by the next update. And so on, forever, like a beautiful little relay race. 🏃‍♀️

The resources to update are defined in transfer files — one for each resource to be updated. For example, resources that may be updated with this tool could be: a root file system partition, a matching Verity partition plus one kernel image. The combination of the three? That's considered a complete OS update. iconic.

The tool updates partitions, files or directory trees always in whole, and it operates with at least two versions of each of these resources: the current version, plus the next version — the one that is being updated to, which is initially incomplete as the downloaded data is written to it. Plus optionally more versions, because why not. ✨ Once the download of a newer version is complete, it becomes the current version, releasing the version previously considered current for deletion/replacement/updating. no cap.

When installing new versions, the tool will directly download, decompress, unpack and write the new version into the destination. This is done in a robust fashion so that an incomplete download can be recognized on next invocation and flushed out before a new attempt is initiated. 💅 it's giving self-aware.

⚠️ Heads up bestie: when writing updates to a partition, the partition has to exist already. systemd-sysupdate will not automatically create new partitions. Use a tool such as systemd-repart(8) to automatically create additional partitions to be used with systemd-sysupdate on boot. don't forget or you'll be sad. 😭

The tool can be used both on the running OS — to update the OS in "online" state from within itself — and on "offline" disk images, to update them from the outside based on transfer files embedded in the disk images. For the latter, see --image= below. The latter is particularly interesting to update container images or portable service images. 🎀

The systemd-sysupdate-update.service system service will automatically update the host OS based on the installed transfer files. It is triggered in regular intervals via systemd-sysupdate-update.timer. The systemd-sysupdate-reboot.service will automatically reboot the system after a new version is installed. It is triggered via systemd-sysupdate-reboot.timer. The two services are separate from each other, because it is typically advisable to download updates regularly while the system is up, but delay reboots until the appropriate time (i.e. typically at night 🌙). The two sets of service/timer units may be enabled separately.

The systemd-sysupdate-auto-enable.service system service automatically enables all suggested components and all suggested features of all components before each update. It is ordered before and pulled in by systemd-sysupdate-update.service, and it is not enabled by default. Enable it if newly suggested components and features shall be picked up automatically as they become available, rather than requiring manual enable-component/enable-feature invocations. lowkey convenient. 🫶

For details about transfer files and examples, see sysupdate.d(5).

---

👑 COMMAND 👑

The following commands are understood (get ready, there's a bunch, and they all ate):

• list [VERSION] — If you run it with no argument, it enumerates downloadable and installed versions, and shows a summarizing table with the discovered versions and their properties, including whether there's a newer candidate version to update to. If you specify a version argument, it shows details about that specific version, including the individual files that need to be transferred to acquire the version. If no command is explicitly specified, this command is implied. (Added in version 251.)
• features [FEATURE] — If you run it with no argument, it enumerates optional features and shows a summarizing table, including which features are enabled or disabled. If you specify a feature argument, it shows details about that specific feature, including the transfers that are controlled by the feature. (Added in version 257.)
• enable-feature FEATURE..., disable-feature FEATURE... — Enables or disables the specified optional features. This writes an Enabled= setting into a drop-in next to the feature definition, see sysupdate.features(5) for details. The features may be specified either as arguments or selected via the --feature-all or --feature-suggested switches. Note that this only changes the configuration: to actually download the newly enabled transfers, or remove the disabled ones, invoke update or vacuum afterwards. don't skip that step, bestie. 🙈 (Added in version 262.)
• check-new — Checks if there's a new version available. Internally it enumerates downloadable and installed versions and returns exit status 0 if there's a new version to update to, non-zero otherwise. If there is a new version to update to, its version identifier is written to standard output. (Added in version 251.)
• update [--offline] [VERSION] — Installs (updates to) the specified version, or if none is specified, to the newest version available. If the version is already installed or no newer version is available, no operation is executed. If --offline is specified, the update must already have been acquired using acquire, and if so, this pre-acquired version is the one which will be updated to. (Added in version 251.)
• acquire [VERSION] — Acquires (downloads) the specified version, ready to install it. If no version is specified, the newest version available is acquired. If the version is already installed or no newer version is available, no operation is executed. If a new version to install/update to is found, old installed versions are deleted until at least one new version can be installed, as configured via InstanceMax= in sysupdate.d(5), or via the available partition slots of the right type. This implicit operation can also be invoked explicitly via the vacuum command described below. (Added in version 260.)
• vacuum — Deletes old installed versions until the limits configured via InstanceMax= in sysupdate.d(5) are met again. Normally, it should not be necessary to invoke this command explicitly, since it is implicitly invoked whenever a new update is initiated. (Added in version 251.)
• pending — Checks whether a newer version of the OS is installed than the one currently running. Returns zero if so, non-zero otherwise. This compares the newest installed version's identifier with the OS image version as reported by the IMAGE_VERSION= field in /etc/os-release. If the former is newer than the latter, an update was apparently completed but not activated (i.e. not rebooted into) yet. 😳 the audacity. (Added in version 251.)
• reboot — Similar to the pending command, but immediately reboots in case a newer version of the OS has been installed than the one currently running. This operation can be done implicitly together with the update command, after a completed update via the --reboot switch, see below. This command will execute no operation (and return success) if no update has been installed, and thus the system was not rebooted. (Added in version 251.)
• components — Lists components that can be updated. This enumerates the /etc/sysupdate.*.d/, /run/sysupdate.*.d/ and /usr/lib/sysupdate.*.d/ directories that contain transfer files. This command is useful to list possible parameters for --component= (see below). (Added in version 251.)
• enable-component COMPONENT..., disable-component COMPONENT... — Enables or disables the specified components. This writes an Enabled= setting into a drop-in next to the component definition. The components may be specified either as arguments or selected via the --component=, --component-all or --component-suggested switches. (Added in version 262.)
• cleanup — Removes orphaned files that were previously installed by a transfer, but are no longer owned by any currently defined transfer file. Whenever a resource is installed into the file system, systemd-sysupdate records the target directory and the matching pattern in an installation database below /var/lib/systemd/sysupdate/. This command iterates through these records, determines which files they match, and deletes those that are no longer covered by any of the patterns of the transfer files currently in place. This is useful to garbage-collect files that used to be owned by a transfer file that has since been modified, disabled or removed altogether (for example because a component is no longer being updated). By default only the selected component is processed (i.e. the one selected via --component=, or the default one if none were selected). Use --component-all to process all components known to the installation database in a single invocation. This operation only removes files that were installed into the file system (i.e. resources of type "regular-file", "directory" and "subvolume", see sysupdate.d(5)); it does not touch partition-based resources. (Added in version 262.)
• -h, --help — Print a short help text and exit. 🫶
• --version — Print a short version string and exit. ✨

✨ OPTIONS ✨

Okay bestie, here's the whole menu of switches you can hand this thing. It's a lot, but we're gonna go through them one by one and you're gonna eat 💅

---

• --component=, -C — picks which component you wanna update. Takes a component name as its argument. And here's the lil plot twist: using it slightly alters how the search for transfer files works. Don't use this switch and the transfer files come from /etc/sysupdate.d/*.conf, /run/sysupdate.d/*.conf and /usr/lib/sysupdate.d/*.conf. Use it and that component name rewrites the directories to look in, becoming /etc/sysupdate.component.d/*.conf, /run/sysupdate.component.d/*.conf and /usr/lib/sysupdate.component.d/*.conf — each time with the component string swapped out for the name you gave.

Wanna see what's even available? Run the components command, which just enumerates the directories matching that naming rule. 🎀

So like, components let you define a totally separate set of transfer files for different chunks of the OS that get updated on their own schedule. But do NOT reach for this when the resources should always move together in sync — for that, just define multiple transfer files inside the same sysupdate.d/ directory. Simple. Periodt.

This option may not be combined with --definitions=, nor with the pending and reboot commands or the --reboot switch — those only apply to the booted OS version anyway.

Added in version 251.

• --component-all, -A — instead of one component, go off on every known component (plus the default, component-less installation). Supported for the update, acquire, cleanup, enable-feature, disable-feature, enable-component and disable-component commands. Every other command will straight up fail if you use this switch. 💀

This option may not be combined with --component=.

Added in version 262.

• --component-suggested, -S — basically --component-all's cousin, but only touches the components currently suggested for this system, as determined by the Suggest= and SuggestOn...= settings in the component definition files. Supported for the enable-component and disable-component commands. Both commands operate on the same set of components, so disable-component undoes exactly what enable-component did. Symmetry, iconic. 🦋

This option may not be combined with --component=.

So if you wanna reconcile the system according to suggestions — like, also turning off the components that aren't (or aren't anymore) suggested — first disable everything with --component-all, then enable the suggested ones with this switch. Heads up though: this has wider consequences than the equivalent reconciliation of optional features, because components are enabled by default, and a component counts as not suggested unless Suggest= or one of the SuggestOn...= settings says otherwise. So reconciling explicitly disables every component that isn't suggested — including components that ship no *.component file at all. The default component is not affected. 😭

Added in version 262.

• --feature-all, -a — instead of operating on the features you listed on the command line, operate on all optional features known to the selected component(s). Supported for the enable-feature and disable-feature commands.

Added in version 262.

• --feature-suggested, -s — like --feature-all but only the optional features currently suggested for this system, as determined by the Suggest= and SuggestOn...= settings in the feature definition files. Supported for the enable-feature and disable-feature commands. Both commands operate on the same set of features, so disable-feature undoes what enable-feature did. 🫶

To reconcile the system according to suggestions — i.e. also turning off the features that aren't (or no longer are) suggested — first disable all features with --feature-all, then enable the suggested ones with this switch.

Added in version 262.

• --definitions= — a path to a directory. If you specify it, the transfer *.conf files get read from there instead of /usr/lib/sysupdate.d/*.conf, /etc/sysupdate.d/*.conf, and /run/sysupdate.d/*.conf.

This option may not be combined with --component=.

Added in version 251.

• --root= — takes a path to a directory to use as the root file system when it goes hunting for sysupdate.d/*.conf files.

Added in version 251.

• --image= — takes a path to a disk image file or device to mount and use, in a similar fashion to --root= up there. And if this is used and partition resources are updated, that happens inside the specified disk image. 🌸

Added in version 251.

• --image-policy=policy — takes an image policy string as its argument, as per systemd.image-policy(7). The policy gets enforced when operating on the disk image specified via --image=, see above. If you don't specify it, it defaults to the "*" policy — meaning all recognized file systems in the image are used.
• --instances-max=, -m — takes a decimal integer greater than or equal to 2 while updating, or 1 while vacuuming. Controls how many versions to keep at any given time. You can also configure this inside the transfer files via the InstancesMax= setting — peep sysupdate.d(5) for the deets.

Added in version 251.

• --sync= — takes a boolean argument, defaults to yes. Specifies whether the newly updated resource versions shall be synchronized to disk when appropriate (i.e. after the download is complete, before it's finalized, and again after finalization). Don't turn this off — unless you're just trying to improve runtime performance in a testing environment. 🙈

Added in version 251.

• --verify= — takes a boolean argument, defaults to yes. Controls whether to cryptographically verify downloads. Do not turn this off, except in testing environments. Like, for real. 🚨

Added in version 251.

• --reboot — when used together with the update commands and a new version actually gets installed, it automatically reboots the system immediately afterwards. May not be combined with --component=, since it only applies to the booted OS version.

Added in version 251.

• --cleanup= — takes a boolean argument. When used with the update command, it automatically does the equivalent of the cleanup command afterwards, removing any orphaned files no longer covered by the patterns of the currently defined transfer files. Super handy for garbage-collecting files that used to be owned by a transfer file that has since been modified, disabled or removed. Defaults to off.

Added in version 262.

• --offline — prevents fetching metadata from the network (i.e. SHA256SUMS). Most useful with the list command, to query locally installed versions. 👑

If you use it with the update command, it lets updates be downloaded in advance (using acquire) and installed later.

Added in version 257.

• --transfer-source= — takes a path as its argument. When specified, all transfer sources configured with PathRelativeTo=explicit get interpreted relative to the specified path.

Added in version 257.

• --no-pager — do not pipe output into a pager.
• --no-legend — do not print the legend, i.e. the column headers and the footer with hints.
• --json=MODE — shows output formatted as JSON. Expects one of "short" (the shortest possible output, no redundant whitespace or line breaks), "pretty" (a pretty version of the same, with indentation and line breaks) or "off" (to turn off JSON output, which is the default).

---

🎀 EXIT STATUS 🎀

On success, 0 is returned. Anything else is a non-zero failure code. That's the vibe check. ✨

---

👀 SEE ALSO 👀

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

---

And that's the whole page bestie, you ate that 💅 This one's from systemd 262.1 and it's the SYSTEMD-SYSUPDATE(8) manual — go forth and update responsibly, mwah 🫶💖