Jump to content

Duranium (Immutable Nura)

From Nura Wiki

Introduction

Immutable Nura (project name: Duranium) is an image-based variant of Nura 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 Nura 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 Nura.
    • 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 Phosh's Mobile Settings and KDE's Discover, have plugins 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 after two attempts, systemd-boot automatically falls back to the previous working image.

Switching Releases or UIs (Experimental)

Warning WARNING: This feature currently highly experimental.

To switch to a different Nura release or user interface:

  1. Remove /etc/os-release-symlink and Copy over from image /usr/lib/os-release: rm /etc/os-release && cp /usr/lib/os-release /etc/os-release
  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 sudo /usr/lib/systemd/systemd-sysupdate update
  4. Reboot to apply changes

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

Configuration (/etc)

Duranium uses systemd-confext to make default configuration available in /etc. Users/system admins can create and modify files under /etc as expected, any changes are applied on top of confext automatically on boot.

Changes to /etc that were added on top of the default configuration can be viewed at /var/lib/extensions.mutable. This is helpful e.g. during debug when trying to figure out if config in /etc was changed to cause a system's behavior to change or when backing up changes to the default /etc.

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

Versions of packages used to build the image are written to /usr/share/duranium and may be useful for comparing with previous images to identify changed packages.

Known Issues

For known issues that are not documented here, see the open issues list. Also see the Duranium MVP milestone tracker.

Fastboot broken after flashing Duranium

Note This issue has been resolved for a while now. This section should be dropped soon.

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.

Issues with building images using mkosi can be reported here

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

Project Resources

Retrieved from "https://wiki.nura.eco/index.php?title=Duranium_(Immutable_Nura)&oldid=107083"