How to Configure Atomic A/B OS Updates in Ubuntu Using systemd-sysupdate

Architecture of systemd-sysupdate and Atomic Image-Based Deployments

Modern Linux infrastructure is rapidly transitioning from traditional package-by-package updates (such as apt upgrade) toward immutable, image-based operating system architectures. In an image-based model, operating system updates are delivered as complete, cryptographically verified filesystem images written into passive A/B partition pairs. If an update fails or becomes corrupted during deployment, the bootloader safely rolls back to the previously functioning partition slot without risking service downtime or partial dependency failures.

Introduced in systemd 251 and integrated deeply into Ubuntu 24.04 LTS and Ubuntu Core deployments, systemd-sysupdate serves as the native orchestrator for discovering, downloading, verifying, and writing atomic updates. It operates directly at the disk and partition level, reading declarative configuration files from /etc/sysupdate.d/ and interacting with the Discoverable Partitions Specification (DPS) to identify active versus inactive root filesystems, Unified Kernel Images (UKIs), and system extensions (sysext).

Unlike monolithic third-party update frameworks, systemd-sysupdate requires no proprietary background daemons during steady state. It leverages HTTP/HTTPS or local staging directories to pull compressed disk delta images (or raw partition images), verifies SHA-256 digests and digital signatures, and automates slot cycling seamlessly.

Verifying System Requirements and Discoverable Partition Layout

Because systemd-sysupdate relies on declarative partition discovery, the host system must use GUID Partition Table (GPT) disks formatted according to the Discoverable Partitions Specification. Standard GPT partition type GUIDs identify partition roles—such as Root (`69dad710-2ce4-4e3c-b16c-21a1d49abed3` for x86-64 root) and EFI System Partitions (`c12a7328-f81f-11d2-ba4b-00a0c93ec93b`).

To inspect your current partition layout and verify DPS compliance in Ubuntu:

# Inspect disk partition types and GUIDs
sudo systemd-dissect --list /dev/sda

# Alternatively, audit partition labels and types using lsblk
lsblk -o NAME,PARTTYPE,PARTLABEL,FSTYPE,MOUNTPOINT

Verify that systemd-sysupdate is installed and review its built-in help and capability flags:

# Check systemd-sysupdate version and availability
systemd-sysupdate --version

Defining Declarative Update Targets in sysupdate.d

The operational logic of systemd-sysupdate is defined in .conf files placed in /usr/lib/sysupdate.d/ (vendor defaults) or /etc/sysupdate.d/ (administrator overrides). Each configuration file defines a specific update target, such as the kernel image, root filesystem, or system extension.

Create the directory structure if it does not already exist:

# Create system configuration directory for update definitions
sudo mkdir -p /etc/sysupdate.d

To configure an A/B root partition update target, create /etc/sysupdate.d/10-root.conf:

# Define A/B partition update rules for the root filesystem
sudo nano /etc/sysupdate.d/10-root.conf

Populate the configuration with the following directives:

[Transfer]
ProtectVersion=%v

[Source]
Type=url-file
Path=https://updates.internal.domain.com/ubuntu-os/
[email protected]

[Target]
Type=partition
Path=/dev/disk/by-partlabel/
MatchPattern=ubuntu-root-@v
MatchPartitionType=root-x86-64
PartitionFlags=0
ReadOnly=yes
Mode=0444
InstancesMax=2

In this definition:

  • [Transfer] ProtectVersion=%v: Prevents overwriting the currently booted operating system version.
  • [Source] Type=url-file: Instructs the tool to query an internal web repository for files matching the regex pattern containing version tokens (@v).
  • [Target] Type=partition: Directs the payload to write directly into an inactive GPT partition marked with the specified partition type GUID.
  • InstancesMax=2: Maintains exactly two slots (Slot A and Slot B), automatically rotating the older inactive partition when a new release arrives.

Configuring Unified Kernel Image (UKI) Updates

In addition to root filesystems, systemd-sysupdate excels at managing Unified Kernel Images (UKIs) placed inside the EFI System Partition (ESP). UKIs combine the kernel binary, initramfs, and kernel command line into a single signed EFI executable.

Create /etc/sysupdate.d/20-kernel.conf to manage kernel rollouts:

sudo nano /etc/sysupdate.d/20-kernel.conf

Populate the file with the following configuration:

[Transfer]
ProtectVersion=%v

[Source]
Type=url-file
Path=https://updates.internal.domain.com/ubuntu-kernel/
[email protected]

[Target]
Type=regular-file
Path=/efi/EFI/Linux/
[email protected]
Mode=0700
InstancesMax=2

This definition manages dual kernel executables within the ESP, ensuring systemd-boot can present the previous working kernel should the newly installed release encounter a boot failure.

Checking for Updates and Auditing Slot States

Once configuration files are in place, query the remote update repositories and inspect local partition availability without performing any writes using the check command:

# Check available remote updates against local partition slots
sudo systemd-sysupdate check

To output a detailed table listing current, candidate, and obsolete versions across all configured targets, execute list:

# Display status table of all update targets
sudo systemd-sysupdate list

A typical output illustrates active versus candidate versions:

TARGET     CURRENT       CANDIDATE     NEWEST
10-root    24.04.1       24.04.2       24.04.2
20-kernel  6.8.0-40      6.8.0-45      6.8.0-45

Applying Updates and Initiating Atomic Partition Writes

To initiate the update process, invoke the update verb. systemd-sysupdate downloads the matching payload, decompresses the image stream on the fly, writes the bits into the designated inactive partition, and updates the GPT partition label and version flags:

# Perform atomic update across all defined targets
sudo systemd-sysupdate update

If you wish to apply updates for only a specific target definition (such as testing the kernel without altering the root filesystem), pass the configuration filename:

# Update only the kernel target
sudo systemd-sysupdate --component=20-kernel update

Because the update writes to passive slots while the active operating system remains untouched in memory, the update process incurs zero operational interruption.

Automating Background Checks via systemd Timers

In production fleets and edge computing deployments, updates should be polled periodically. Systemd includes standard service and timer units for this purpose:

# Enable and start the systemd-sysupdate background polling timer
sudo systemctl enable --now systemd-sysupdate.timer

# Check the next scheduled execution window
systemctl list-timers systemd-sysupdate.timer

By coupling systemd-sysupdate with systemd-boot and automatic watchdog reboots, Ubuntu administrators achieve self-healing, fully automated A/B operating system lifecycle management without external agent dependencies.

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.