NX Overlayroot

NX Overlayroot implements Nitrux’s immutable root filesystem using OverlayFS. It presents a unified view by overlaying a writable tmpfs layer on top of the read-only root. Changes appear to persist during a session but do not alter the underlying filesystem.

How it Works

OverlayFS combines two layers:

┌─────────────────────────────────┐
│      Upper layer (tmpfs)        │  ← Session writes go here
│         Read/Write              │    Discarded on reboot
├─────────────────────────────────┤
│      Lower layer (root)         │  ← Actual root filesystem
│         Read-only               │    Persistent, immutable
└─────────────────────────────────┘

The kernel merges these layers into a single view at the root.

Data writes land in the upper layer, masking the corresponding paths in the lower layer. On reboot, the kernel discards changes in the upper layer, and the system returns to its original state.

Modifying the Immutable Root

When permanent changes to the root are necessary, use overlayroot-chroot. This tool:

1. Locates the lower (read-only) directory.
2. Remounts it read/write.
3. Bind-mounts /proc, /run, and /sys
4. Chroots into the lower directory.
5. Logs the session to /var/log/overlayroot-audit.log
6. Restores read-only state on exit.

Usage

sudo overlayroot-chroot

Mounting Additional Filesystems

NX Overlayroot only mounts /proc, /run, and /sys by default. The user must mount other filesystems manually depending on the task:

# /dev is required for most utilities (e.g., micro text editor)
mount -t devtmpfs dev /dev

# Mount partitions by label
mount -t auto $(findfs LABEL=NX_VAR_LIB) /var/lib
mount -t auto $(findfs LABEL=NX_HOME) /home

# ... make changes ...

sync

# Unmount before exiting
umount /dev /var/lib /home
exit

When Changes Take Effect

Changes take effect immediately in the lower directory. However, they won’t appear in the running system (the overlay) until you either:

• Reboot.
• Reload the kernel using Kernel Boot (where supported).

Disabling Immutability Temporarily

For debugging purposes, you can boot with immutability disabled:

1. Press E in the GRUB boot menu.
2. Find the parameter overlayroot=tmpfs:swap=1,recurse=0
3. Change it to overlayroot=disabled.
4. Press F10 to continue booting.
5. Reboot when finished to restore immutability.

The preferred method for modifying the root is overlayroot-chroot. Booting with immutability disabled is intended for debugging.

User Responsibility

Permanent changes to the root are the user’s responsibility. If manual modifications cause conflicts during an update via NUTS, users must resolve them independently.