Duranium (Immutable postmarketOS)
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:
- U-boot image: gitlab.postmarketos.org/tauchgang/u-boot/-/artifacts. Go to Browse>binaries>u-boot-*.img
- Duranium image: duranium.postmarketos.org and decompress the raw file.
- 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
- Devices with ABL bootloader (typically phones):
| 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. |
| 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.
Manifest signing is not yet implemented. The --verify=false flag disables signature verification. |
Switching Releases or UIs (Experimental)
| WARNING: This feature currently highly experimental. |
To switch to a different postmarketOS release or user interface:
- Copy
/usr/share/factory/etc/os-releaseto/etc/os-release(this replaces the symlink with an actual file) - Edit
/etc/os-releaseand modify:VARIANT_IDto change the UI (e.g.,gnome,phosh,plasma-mobile,console)VERSION_IDto change the release (e.g.,edge)
- Run
doas /usr/lib/systemd/systemd-sysupdate --verify=false update - 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/skelat build time so thatuseraddcopies real files into new home directories rather than symlinks into the immutable/usrtree.
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
- Source repository: https://gitlab.postmarketos.org/postmarketOS/duranium
- Design documentation: https://gitlab.postmarketos.org/postmarketOS/duranium/-/blob/main/DESIGN.md