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

  1. 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.
  2. Write the image to the target storage device:
    $ doas sh -c 'zstdcat /path/to/device_ui_release_VERSION.raw.zst > /dev/sdX'
    
    Replace /dev/sdX with the actual device path. GUI image writers may work if they support zstd-compressed images.
  3. Reboot and ensure the system is configured to boot from the storage device containing the image.
Note 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.

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.

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