How rpm-ostree Performs Atomic Upgrades in Linux

The rpm-ostree tool is a hybrid image/package system that delivers atomic, reversible operating system upgrades for Linux distributions like Fedora Silverblue, Fedora CoreOS, and Red Hat Enterprise Linux CoreOS. By combining the commit-based, version-controlled architecture of libostree with standard RPM package management, rpm-ostree allows entire operating system states to be downloaded, assembled, and deployed in the background without modifying the active, running environment. This article explains the technical mechanics behind how rpm-ostree prepares, stages, and boots atomic upgrades, ensuring system stability and effortless rollbacks.

Understanding the Core Architecture

To understand how updates work, it is essential to look at the storage model of an rpm-ostree system:

• Read-Only System Root: The /usr directory is mounted read-only to prevent unauthorized or accidental modifications to core binaries and libraries.
• State and Configuration: The /var directory holds writable user data, containers, and logs, while /etc contains system configurations.
• OSTree Commits: System releases are distributed as commits, similar to snapshots in a Git repository. Each commit represents a complete, immutable file tree of the base operating system.

The Atomic Upgrade Workflow

Rather than updating individual RPM packages on a live root filesystem, rpm-ostree performs updates by constructing an entirely new bootable filesystem tree alongside the current one. The upgrade process follows distinct stages:

1. Fetching the Base Commit

When an update is initiated, rpm-ostree pulls a new base commit from a remote OSTree repository. This fetch operation happens in the background while the system is fully operational. Because the files are stored in a content-addressed object store located at /ostree/repo, only new or modified files are downloaded, conserving bandwidth and disk space.

2. Resolving Package Layering

If a user has installed additional native packages via rpm-ostree install, the system does not apply them to the live filesystem. Instead, rpm-ostree uses librpm to resolve dependencies and layer the requested RPMs directly on top of the newly fetched base commit. This creates a custom composite filesystem tree specific to the machine's configuration.

3. Merging Configurations via 3-Way Diff

System configuration files located in /etc must be preserved during an upgrade. To achieve this, rpm-ostree performs a 3-way merge between:

• The original /etc from the previous base commit.
• The local, modified /etc currently running on the system.
• The new /etc provided by the target base commit.

User changes are retained, new configuration defaults are introduced, and any potential conflicts are resolved before the new deployment is finalized.

4. Staging the New Deployment

The resulting filesystem tree is checked out as a new deployment directory within /ostree/deploy/<osname>/deploy/<commit_id>. Hard links are used extensively against the central object store to minimize disk usage. At this point, the newly created deployment exists completely isolated from the current running system, guaranteeing that failures during download or package composition cannot corrupt the active operating system.

5. Updating the Bootloader

Once the new deployment tree and configuration merge are complete, rpm-ostree rewrites the bootloader configuration (such as GRUB or systemd-boot). The new deployment is marked as the default boot entry for the next startup sequence, while the currently running deployment is retained as the secondary entry.

6. Atomic Switch via Reboot

The actual activation of the upgrade occurs atomically at boot time. During the boot sequence, the initramfs reads the bootloader parameters and mounts the new deployment tree as the read-only root (/) filesystem.

Because the transition occurs in the transition between power cycles rather than while services are running, there is zero risk of binary incompatibilities, locked file errors, or partially written files causing service failures.

Rollback Capabilities

If an updated deployment fails to boot or introduces software regressions, the user can reboot the system and select the previous deployment from the boot menu. Alternatively, running the rpm-ostree rollback command swaps the bootloader priorities back to the previous tree, instantly reverting the operating system to its exact pre-upgrade state.