Docs / How it works

quantra-ramfs

The initramfs of Zainium OS — what it does before systemd starts, how it seals the system with fs-verity, and its boot options.

quantra-ramfs is the initramfs of Zainium OS: one static Rust program that runs as /init before systemd, with no shell and no busybox. It is open source: github.com/Zainium-Dynamics/quantra_ramfs. It is installed as /overlayer/zaisys/kernel/quantra-ramfs.img and upgraded with the kernel (elevate zex kernel --u).

What it does at every boot

Finds the system disk (by UUID, label, device or loop image), assembles RAID and LVM when asked, and supports dm-verity.
Unlocks a LUKS disk with a TPM2, a key file or a passphrase.
Loads the display driver and shows the boot splash.
Applies a waiting base upgrade staged by zex syshub --u, with a journal: a failed or interrupted upgrade is undone, or the boot stops — it never continues on a half-applied base.
Seals the system files with fs-verity (below), and moves anything in the userland that would hide a program or library of the base to /overlayer/zexlib/shadowed.
Builds the system view: /overlayer/syshub read-only and sealed (root cannot remount it writable), its etc and var writable with your changes kept in /overlayer/zexlib/union, and /overlayer/zaisys read-only.
Detaches the raw disk and starts systemd.

If it cannot build the protected system view, it stops in a rescue shell instead of starting an unprotected system.

fs-verity

Every file of the base (/overlayer/syshub) and the boot files (/overlayer/zaisys) is sealed with fs-verity at every boot: the kernel refuses any change to their content, for root too. No option turns this off. On the first boot sealing takes a moment ("Securing the system…"); after that, a tree whose files were not added, removed or renamed since the last boot is not checked again, so a normal boot does not wait for it.

Your installed software (/overlayer/zexlib/union) is sealed only when you turn it on, because a sealed file can be replaced but never written:

elevate zex verity --union on    # seal it now and at every boot (not etc and var)
elevate zex verity --union off   # stop sealing new files at boot
elevate zex verity               # show the setting

Boot options

Add them to the kernel command line: press E on an entry in the Limine menu for one boot, or edit limine.conf on the EFI partition to keep them.

Option	What it does
`zainium.overlay=off`	Rescue boot: the base on its own, without your installed software; nothing persists
`zainium.verity=full`	Check and seal every file of the base and the boot files, changed or not
`zainium.verity=union`	Seal your installed software too, for this boot
`rd.break=pre-mount`	Stop in a shell before the root is mounted (also `pre-overlay`, `pre-pivot`)
`rd.shell`	Stop in a shell before booting
`rd.rescue`, `single`	Boot to rescue (single-user) mode
`rd.fsck=0`	Skip the file system check of the root
`rd.tpm2=0`	Do not use the TPM2 to unlock the disk; ask for the passphrase
`rd.udev=0`	Do not process device events in the initramfs
`quiet`	Show only errors
`root=`, `rootfstype=`, `rootflags=`, `rootwait`	The root file system, its type, its mount options, and waiting for it
`luks=`, `luks_keyfile=`, `rd.luks.pkcs11-uri=`	The encrypted root, a key file, or a PKCS#11 token
`rd.md=1`, `rd.md.uuid=`, `rd.lvm=1`, `rd.lvm.vg=`	Assemble RAID, activate LVM
`rd.verity=1`	Check the root device with dm-verity
`rd.vconsole.keymap=`	The keyboard layout for the passphrase prompt
`plymouth.theme=`	The boot splash theme

The emergency shell

When the boot cannot continue, or with rd.break= and rd.shell, quantra-ramfs prints what it knows (the mounts, /dev and the kernel command line) and opens the zainium-emergency # prompt. These commands are built in and need no programs from the disk:

Command	What it does
`ls [dir]`	List a directory (`/` when none is given)
`cat <file>`	Print a file
`mount`	Show what is mounted
`reboot`	Restart
`poweroff`, `halt`	Turn the computer off

Anything else runs through a shell (fish, bash or zsh) if one can be found on the disk. See troubleshooting and rescue.

sys_resolver

How the system protects itself

All documentation