syshub: the unbreakable base
Why the base of Zainium OS is not changed by software, updates or mistakes — and how to recover when something else goes wrong.
syshub is the base of Zainium OS: the complete operating system as Zainium ships it — C library, toolchain, systemd, the desktop, drivers. It lives in /overlayer/syshub and is built so that nothing you do in day-to-day use can break it.
What protects it
| Threat | What happens on Zainium OS |
|---|---|
| Installing software | Packages go to the userland layer (zexlib). zex never writes a file into syshub, and leaves out any file of a package that syshub already has. |
| A bad package or a broken app | Remove it — zex deletes exactly the files it installed. Or boot without the userland and fix it from there. |
| An update that fails halfway | Base upgrades are staged first and applied at boot by the initramfs, before anything uses the base. Every step is journaled; an interrupted upgrade recovers. |
| An update that is bad | The last applied base upgrade can be rolled back at the next boot. |
| A mistake as root | elevate refuses rm, rmdir, mv, cp, rsync, shred and unlink on syshub, the boot files and a staged upgrade — even for root. |
| Writing to the system while it runs, even as root | /overlayer/syshub is mounted read-only with the sealed OverlayFS option: writes fail, and remounting it writable is refused for root too. The boot files in /overlayer/zaisys have their own read-only mount that root cannot remount writable. |
| Rewriting a base file, even as root | Every file of syshub and the kernel is sealed with fs-verity on an installed system. The kernel refuses to change its content — for root too, and even when the disk is mounted directly. |
| Hiding a base program from the userland | In bin, sbin, libexec, lib, drivers and the musl directory the base always wins: a file in the userland layer can not replace or hide one of the base. quantra-ramfs also moves such files to /overlayer/zexlib/shadowed at boot. |
| Libraries replaced by other software | The base loads its own libraries from /overlayer/syshub/lib; a second C library (glibc) lives in its own directory and cannot replace them. |
| Tampered packages | .zex packages are signed (Ed25519) and checked (BLAKE3) before they are installed. |
Sealed by the kernel
At every boot quantra-ramfs makes sure fs-verity is on for every file of syshub and the boot files, and seals any file that is not ("Securing the system" on the splash). After the first boot it only re-checks a tree when a file in it was added, removed or renamed. The kernel refuses any write to a sealed file's content: tee, truncate, dd or a program opening the file for writing all get Operation not permitted, as root too. Base upgrades seal their new files as they are applied, and the installer creates the root filesystem with the verity feature.
Installed software in /overlayer/zexlib/union is not sealed unless you turn it on, because a sealed file can be replaced but never written, and some programs update their own files in place:
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 settingzainium.verity=union on the kernel command line turns it on as well. All boot options are on the quantra-ramfs page. zex upgrades and reinstalls replace sealed files, so they keep working either way.
The rest of the kernel's protection is on from the first boot as well: kernel lockdown in integrity mode (no /dev/mem, no unsigned modules, no unsigned kexec), AppArmor with profiles for the base, Landlock and Yama. Every kernel module is signed, and a module whose signature is missing or does not match is refused. IMA measures every program, module and firmware file it runs, and IPE enforces a policy built into the kernel that refuses loading a new kernel at run time. A firewall (nftables) blocks incoming connections by default.
lsattr /path/to/a/base/file # the V flag: sealed with fs-verity
cat /sys/kernel/security/lockdown
elevate aa-statusThe base always boots on its own
The software you install is stacked on top of syshub with OverlayFS when the system starts. On disk the two are separate, so the base can always start without it. Add zainium.overlay=off to the kernel command line in the boot menu and Zainium OS starts with syshub only — see Troubleshooting and rescue.
How syshub changes
Only through base upgrades:
elevate zex update # or: elevate zex syshub --uThe new base packages are downloaded, verified and staged in /overlayer/.syshub-pending, then applied by quantra-ramfs at the next boot. The running system never sees a half-upgraded base. See Updates and upgrades.
Limits
Protecting the base is not the same as being impossible to attack, and no operating system can promise that. What syshub does not protect against today:
- Changing the disk from outside. While Zainium OS runs, the system is read-only for root. Someone who boots another system on the machine can still delete a sealed file or put another in its place. Checking each file against a signed digest, Secure Boot with our own key, and an IPE policy that runs only signed base code are next.
- Kernel vulnerabilities. A flaw in the kernel can give an attacker full control, as on any system. Keep the system updated.
- Malicious packages. Signatures prove where a package came from, not that it is safe. Install software from sources you trust.
- Denial of service. Flooding a machine with traffic or exhausting its memory can make it unresponsive. Firewalls, resource limits and redundancy are still needed for servers.
What syshub guarantees is recovery: whatever happens on top of it, the base on disk stays as it was installed, and the system can always boot from it.
What is still yours
Protecting the base does not lock you out of your system. Your home directory, the software you install, and the system configuration in /overlayer/syshub/etc stay yours to change: when you edit a configuration file, your version is stored in /overlayer/zexlib/union/etc, and it survives base upgrades. Service state in /overlayer/syshub/var works the same way.