What keyboot can boot — the supported-OS boundary
keyboot is a launcher, not a container. After it opens the encrypted pool it
kexecs into the OS’s own kernel + initramfs and exits — once your OS is
running, keyboot is gone. That one fact decides which operating systems keyboot
can boot, and why.
The BE initramfs requirement
Your root filesystem is the encrypted ZFS pool — there is no plaintext /,
and even /boot lives inside the encrypted dataset. So the only path to a
mountable root runs through: load dm-crypt + the ciphers, open the LUKS
volumes, load zfs.ko, import the pool, mount the dataset. After kexec, the
thing that must do all of that is the OS’s own initramfs.
Therefore every boot environment needs its own initramfs carrying crypto +
zfs + the keyboot be-unlock hook, plus a kernel that supports dm-crypt and
a zfs.ko matching that kernel. keyboot’s install-os plugins bundle exactly
these (Alpine mkinitfs, Debian initramfs-tools boot=keyboot, Gentoo
dracut 90keyboot). An OS image whose initramfs lacks them will not boot —
it has no way to reach its own root.
The single-prompt handoff carries the key, not the tools. keyboot passes the 32-byte keyfile payload across kexec so the BE doesn’t re-prompt — but the BE still has to open the disks and import the pool itself, which needs the crypto + zfs + be-unlock bits in its initramfs. A no-crypto/no-zfs image gets handed a key it has nothing to use.
The boundary
The decision rule for “can this run as a keyboot OS” is not “does it have
zfs/crypto modules” — it’s “is its root a mountable ZFS dataset, and can I get
a zfs.ko for its kernel.”
| Target | Root model | Works under keyboot? |
|---|---|---|
| Conventional ZFS-root distro (Alpine, Debian, Gentoo, Arch, Void, …) | a mounted ZFS dataset | Yes — install-os bakes crypto+zfs+be-unlock into the BE initramfs |
| memtest86+ | none (no root at all) | Yes, trivially — kexec target, needs nothing from disk (ADR 0014) |
| Live / install ISO | squashfs from network or RAM | Yes, via netboot/toram only — the live initramfs fetches its squashfs over HTTP/NFS, so the encrypted pool never enters the picture. An ISO-as-a-file-on-the-pool does not work (the live initramfs has no crypto/zfs) unless keyboot pre-stages it to RAM |
| Immutable / image-based distro (LibreELEC squashfs, Bazzite/Silverblue ostree, SteamOS A/B, ChromeOS verity) | its own model — NOT a plain mounted ZFS dataset | No — needs per-distro porting, not an initramfs rebuild (see below) |
Why immutable/image distros don’t fit
Two walls, and the modules are the least of them:
- No kernel-matched
zfs.ko. ZFS is out-of-tree; it must be compiled against that exact kernel. These distros ship no ZFS and are precisely the kind you can’t build it on in place (read-only squashfs appliance; rpm-ostree-immutable). - Their root isn’t a mountable ZFS dataset. LibreELEC loop-mounts a SYSTEM
squashfs with its own init; ostree selects a deployment via an
ostree=karg; SteamOS/ChromeOS use A/B image + verity.be-unlockmountingrpool/ROOT/<be>at/satisfies none of those — the blocker is what the OS expects/to be, not which modules are present.
So an immutable distro is fine as an install target you put on a different system, but it can’t be a keyboot BE without porting it to a ZFS-dataset root — a per-distro project, not a config tweak.
A durability gotcha: keep the BE initramfs keyboot-aware
The fragile moment is whenever the OS regenerates its own initramfs (a kernel upgrade). The new initramfs must still carry crypto + zfs + the keyboot hook, or the next boot can’t mount root:
- Debian (initramfs-tools) & Gentoo (dracut): self-healing. The integration is a persistent hook/module, so a kernel bump re-includes it automatically.
- Alpine (mkinitfs): NOT self-healing.
mkinitfshas no hook mechanism; theapklinux-ltstrigger rebuilds the initramfs with the default init, dropping keyboot’sbe-init. A kernel bump outsidekeyboot-be-upgrade(which rebuilds it) leaves an unbootable image — a known footgun on Alpine.
Also: zfs.ko must match the running kernel after an upgrade (a failed
dkms/akmod rebuild → no pool import), and don’t uninstall cryptsetup/zfs
(they feed the next initramfs regeneration).
This is intrinsic to encrypted-ZFS-on-LUKS root, not a keyboot quirk: the initramfs is always the bridge between kexec and your encrypted root. keyboot’s contributions are doing it uniformly across the three initramfs frameworks and the single-prompt key hand-off — it satisfies the requirement, it doesn’t remove it.