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 full disk image from https://duranium.postmarketos.org/images - the file ending in
.raw.zst. Images are organized in directories named after the device, UI, and release (e.g.,lenovo-21bx_cosmic_edge/). Other files in the directory (e.g..efi,.usr-arm64*) are used for system updates after installation. - Write the image to the target storage device:
$ doas sh -c 'zstdcat /path/to/device_ui_release_VERSION.raw.zst > /dev/sdX'
- Replace
/dev/sdXwith the actual device path. GUI image writers may work if they support zstd-compressed images.
- Reboot and ensure the system is configured to boot from the storage device containing the image.
| Booting from USB may not work correctly. See issue #1. |
Updating the System
List available updates:
$ doas /usr/lib/systemd/systemd-sysupdate --verify=false list
Apply updates:
$ doas /usr/lib/systemd/systemd-sysupdate --verify=false 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.
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
For known issues, see the open issues list.
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