zbm-openwrt-clevis

What it solves

ZFSBootMenu boots encrypted ZFS well, but it expects a person to type the key. On a remote server or an unattended machine that is not enough: the operator cannot tell whether the prompt belongs to the boot environment they trusted before. Here the key is released automatically only while the TPM measurements match the state the operator approved at the last reseal. Otherwise automatic boot stops, the operator is notified, and a password-protected OpenWrt system waits for a manual decision.

Key features

• Automatic unlock bound to TPM PCRs through clevis; the validated policy clevis.pcr_ids=1,4,5,7,9 also covers the kernel command line passed by rEFInd.
• Fallback to a full OpenWrt system with password or SSH-key login, not a passwordless shell; root is locked in the base image.
• Manual unlock and reseal for a new measured state over the console or SSH, also over Wi-Fi or with two WAN uplinks.
• Three storage backends for the sealed JWE: ZFS properties, EFI variables or a file on a VFAT partition.
• Updating the target kernel and initramfs needs no new manual unlock: they live inside the encrypted pool, outside the measured runtime.
• Optional Telegram message when automatic unlock fails; disk and network repair tools in the image.

How it works

rEFInd loads one OpenWrt UKI and passes it the policy on the kernel command line. At boot zbm-auto-boot runs zbm-start; the load-key hook asks clevis to recover the key and hands it to the donor ZFSBootMenu runtime, which reads the target kernel and initramfs from the encrypted root and starts them with kexec. Automatic and manual entry use the same path and share one lock. The pool is imported read-only, except for a short write when a reseal stores its result in ZFS properties.

UEFI → rEFInd → OpenWrt UKI → zbm-auto-boot → zbm-start
     → load-key hook / clevis → ZFSBootMenu → kexec → Ubuntu (ZFS)

Requirements

• A target system on a ZFS root with native encryption and a key file location (keylocation=file://…).
• UEFI, rEFInd as the boot manager and a TPM 2.0; the policy lives on the rEFInd options line.
• Build host: the OpenWrt ImageBuilder flow from the repository, ukify, refind and the usual build tools.
• Lab: qemu-system-x86_64, OVMF and swtpm; the validated target is Ubuntu on encrypted ZFS.