Jump to content

Duranium (Immutable postmarketOS)

From postmarketOS Wiki

Introduction

Immutable postmarketOS (project name: Duranium) is an image-based variant of postmarketOS that provides atomic A/B updates with automatic rollback on boot failure. The system uses a read-only /usr partition verified by dm-verity, ensuring the operating system files remain unmodified.

The implementation uses systemd tooling: systemd-sysupdate for updates, systemd-repart for partition management, systemd-boot for bootloader functionality, and Unified Kernel Images (UKI) containing the kernel, initramfs, command line, and device trees as a single versioned artifact. Images are built with mkosi.

Key features include atomic partition-based updates, cryptographic verification of the /usr partition, LUKS encryption for user data, automatic boot slot selection with fallback on failure, remote HTTP-based updates, first-boot provisioning wizard, factory reset capability, and the ability to switch between different postmarketOS releases or user interfaces.

Prerequisites & Requirements

  • EFI boot support (either native or via u-boot with EFI capabilities)
  • GPT partition table support (subpartitioned devices not currently supported)
  • Minimum 16GB storage recommended

The actual storage requirement depends on the size of the /usr partition, which varies by device and UI selection. The system maintains two complete sets of /usr partitions (slots A and B) plus associated verity partitions for atomic updates.

Installation

  • Download the required images to flash for your device:
  • Read the installation instructions on your device wiki page, as flashing duranium will not be too different from flashing regular postmarketOS.
    • Devices with ABL bootloader (typically phones): fastboot flash boot u-boot* && fastboot flash userdata *.raw && fastboot erase dtbo && fastboot reboot
    • Devices with UEFI bootloader (typically computers): dd if=*.raw of=/dev/$dev_blk bs=8M status=progress
Warning WARNING: Upon fastboot reboot, do not disconnect the USB cable until the device reboots by itself. Even if is showing that all commands finished successfully. It will take a few minutes.
Note Booting from USB may not work correctly. See issue #1.

Updating the System

Some UI software applications, like GNOME Software and KDE's Discover, have plugins in Duranium to check, display, and apply updates. This can also be done manually with updatectl

List available updates:

$ updatectl check

Apply updates:

$ updatectl update

After updating, reboot to boot into the new system image. If the new image fails to boot, systemd-boot automatically falls back to the previous working image.

Note Manifest signing is not yet implemented. The --verify=false flag disables signature verification.

Switching Releases or UIs (Experimental)

Warning WARNING: This feature currently highly experimental.

To switch to a different postmarketOS release or user interface:

  1. Copy /usr/share/factory/etc/os-release to /etc/os-release (this replaces the symlink with an actual file)
  2. Edit /etc/os-release and modify:
    • VARIANT_ID to change the UI (e.g., gnome, phosh, plasma-mobile, console)
    • VERSION_ID to change the release (e.g., edge)
  3. Run doas /usr/lib/systemd/systemd-sysupdate --verify=false update
  4. Reboot to apply changes

The system will download and install the image matching the new configuration.

Configuration (/etc)

Duranium does not use a writable overlay on top of a read-only /etc. Instead, /usr/share/factory/etc ships the default configuration files, and systemd-tmpfiles populates /etc on first boot by creating real directories and symlinking individual files back into the factory tree.

This means that files you have not customized automatically reflect the defaults of the currently booted image. Rolling back to an older image restores the older defaults for any un-customized files.

Customizing a configuration file

To customize a file, copy it out of the factory tree, breaking the symlink:

cp /usr/share/factory/etc/ssh/sshd_config /etc/ssh/sshd_config

Edit /etc/ssh/sshd_config as normal. Your changes persist across updates. Other files in the same directory remain symlinked and continue to track the current image's defaults.

To revert a file to the image default, delete your copy and let tmpfiles restore the symlink on next boot, or restore it manually:

rm /etc/ssh/sshd_config
ln -s /usr/share/factory/etc/ssh/sshd_config /etc/ssh/sshd_config

Exceptions

The following files are not symlinked and are managed separately:

  • User and group databases (passwd, group, shadow)
 and their backup and lock files — modified by first-boot setup and normal
 user management.
  • Machine-specific files: machine-id, hostname.
  • fstab — created empty by tmpfiles; Duranium does not use it for
 normal mounts.
  • The skeleton directory (/etc/skel) is relocated to
 /usr/share/skel at build time so that useradd
 copies real files into new home directories rather than symlinks into the
 immutable /usr tree.

Troubleshooting

The UKI includes profiles for debugging boot issues. During boot, systemd-boot displays a menu before the timeout expires. Select the desired profile:

  • Debug shell - provides an interactive shell in the initramfs for troubleshooting
  • Splash screen disabled - boots without the graphical splash screen

Known Issues

For known issues that are not documented here, see the open issues list.

Fastboot broken after flashing Duranium

The vendor fastboot interface could be broken by flashing Duranium on the OnePlus 6 (oneplus-enchilada) or OnePlus 6T (oneplus-fajita). The bootloader on these devices has an artificial limit on the length of GPT partition names. Flashing an image that has a subpartition with a name longer than 24 characters (well within the GPT specification) breaks fastboot due to the quirks. Unfortunately, Duranium builds until April 2026 were such an image. If you already flashed one and broke fastboot, you can recover by erasing the problematic partition with EDL: edl.py e userdata

Reporting Issues

Report bugs and issues at the issue tracker.

For discussion and support, see the 'immutable' room on the Matrix and IRC page.

Project Resources