Troubleshooting and rescue

Boot without the userland

Because the base stands on its own, you can always boot it without the software you installed. Edit the boot entry in the Limine menu (press E) and add to the kernel command line:

zainium.overlay=off

The system starts with the base only. Fix or remove the package that caused the problem, then reboot normally.

zainium.verity=full makes quantra-ramfs check and seal every file of the base and the boot files again, not only those of a tree that changed since the last boot.

Stop the boot in a shell

Every boot option is listed on the quantra-ramfs page.

quantra-ramfs can stop at a given step and open a shell:

rd.break=pre-mount      before the root is mounted
rd.break=pre-overlay    before the layers are joined
rd.break=pre-pivot      before switching to the new root

A warning about hidden base files

If the boot log says a file "hid the base", something in the userland layer sat over a program or library of the base. It was moved to /overlayer/zexlib/shadowed, not deleted. If you did not put it there, look at what it is before you trust the system.

Check the system

elevate zex doctor          # registry, links, the base, musl and glibc
elevate zex doctor --fix    # repair what it can
zex history                 # what changed recently
elevate zex rollback <tx_id>

Logs

journalctl -b               # this boot
journalctl -b -1            # the previous boot
systemctl --failed          # services that did not start