BOOTC-FILESYSTEM-ENCRYPTION(7)

💾 BOOTC-FILESYSTEM-ENCRYPTION(7) 💅

okay so bestie, welcome to section 7 of the Miscellaneous Information Manual, and today we are talking about the thing that makes everybody's laptop feel mysterious: disk encryption. Specifically, this page is bootc-filesystem-encryption, and it is all about LUKS and friends. let's get into it 🫶

---

✨ NAME ✨

bootc-filesystem-encryption — disk encryption (e.g. LUKS)

---

🌸 DESCRIPTION 🌸

okay first things first: bootc is not picky. it supports literally any Linux filesystem and block storage setup, and it does not dictate any particular architecture. once a writable Linux filesystem is mounted, bootc can just write content (images) into it, exactly the same way podman, apt, and dnf do. it's giving "i go where i'm mounted" energy 👑

concretely: bootc install to-filesystem and bootc upgrade both operate on pre-existing mounted filesystems. and yes, that includes LUKS and RAID underneath for block storage. so the block layer can be doing whatever it wants, bootc does not care.

however 💀 — LUKS is important enough that it deserves its own documentation. so here we are.

---

🎀 Recommendation: handle root filesystem encryption independently of bootc

bestie, listen. if you want an encrypted root, set that up independently of bootc, and then point bootc install to-filesystem at the resulting mounted filesystem. that's the whole vibe. bootc is the guest, you're the host, you handle the locks 🔐

Reference implementations, i.e. the girlies who already did this:

• Anaconda ⟨https://github.com/rhinstaller/anaconda/⟩, via its bootc kickstart command (which drives to-filesystem directly): kickstart's --encrypted options set up LUKS during install, and a %post script can add TPM2 binding with systemd-cryptenroll. iconic behaviour tbh.
• ⟨https://www.freedesktop.org/software/systemd/man/latest/systemd-cryptsetup@.service.html⟩ and ⟨https://www.freedesktop.org/software/systemd/man/latest/systemd-cryptenroll.html⟩ directly, for installers or provisioning tooling that don't use Anaconda. note that data for this can be provided via ⟨https://www.freedesktop.org/software/systemd/man/latest/systemd-imdsd@.service.html⟩ (systemd v261+): on recognized clouds. ✨

whichever one you use, that setup is owned by whoever builds and maintains the image or installer — not by bootc. periodt.

---

🦋 /boot or XBOOTLDR partition

some layouts need a separate /boot or XBOOTLDR partition — for example, tpm2-luks requires one, since GRUB and most bootloaders can't read a LUKS-encrypted /boot. rude of them honestly.

if yours does need one, pass --boot-mount-spec to to-filesystem so bootc knows where to install boot assets. see More advanced installation with to-filesystem (see bootc-installation(7)). 💖

---

🌈 Root filesystem discovery

this one is no different from non-LUKS cases, lowkey. either use discoverable partitions, or root= plus luks.uuid style kernel arguments. that's it, that's the whole thing.

---

🔥 First-boot encryption of an already-populated filesystem

okay so this is the scenario: it's super common to have a "golden image" (a KubeVirt containerdisk, a raw .qcow2, an AMI, and similar) that is already a bootc install — like, it's already the target OS, bestie. typically, the filesystem is not already encrypted, because there'd be nothing to use as a default unlocking mechanism. makes sense, right?

hence encrypting each instance uniquely means converting that already-populated partition to LUKS2 in place, the first time it boots. and no cap: this is OS/distro-level work, not something bootc implements. 🙈

Fedora CoreOS is a reference architecture here: its disk images ship unencrypted, and Ignition ⟨https://coreos.github.io/ignition/⟩ can convert the root filesystem to LUKS2 in place during the initramfs of the machine's first real boot, optionally bound via clevis to tpm2, tang (network-bound unlock), or a Shamir threshold across several pins. see the Fedora CoreOS storage docs ⟨https://docs.fedoraproject.org/en-US/fedora-coreos/storage/⟩ for details. 💫

other notes and prior art:

• openSUSE's ⟨https://github.com/openSUSE/disk-encryption-tool⟩ — shipping today via a dracut hook that runs cryptsetup reencrypt --encrypt --reduce-device-size=<n> before the partition is ever mounted. slay.
• ⟨https://github.com/systemd/systemd/pull/29731⟩ — open, unmerged RFC upstream. we wait 🕰️

⚠️ real talk: this only protects data written after the per-device encryption boundary exists. don't provision machine-specific secrets into the image before that boundary is in place. like, do not do that. 😭

---

👑 Tracking

the following issues track requests to extend tpm2-luks further (configurable PCRs, recovery keys, deferred/first-boot enrollment, all of it). given the direction above, the expectation is that these are better solved by using systemd-cryptsetup / systemd-cryptenroll directly in your own initramfs, rather than by adding more options to bootc's installer. iykyk.

• #421 ⟨https://github.com/bootc-dev/bootc/issues/421⟩ install to-disk with LUKS + TPM broken
• #476 ⟨https://github.com/bootc-dev/bootc/issues/476⟩ Add config option to configure systemd-cryptenroll PCRs
• #477 ⟨https://github.com/bootc-dev/bootc/issues/477⟩ LUKS volumes need configurable password and/or recovery keys
• #1329 ⟨https://github.com/bootc-dev/bootc/issues/1329⟩ Support LUKS password on bootc install
• #2089 ⟨https://github.com/bootc-dev/bootc/issues/2089⟩ install to-disk --block-setup tpm2-luks hangs: libdevmapper udev cookie semaphore deadlock in container IPC namespace (closed; background on why install-time LUKS setup inside a container is fragile) 💀

---

🌟 SEE ALSO 🌟

bootc(8), bootc-docs(7), bootc-installation(7)

---

⭐ VERSION ⭐

v1.17.1

---

and that's the page bestie!! 💖 this was BOOTC-FILESYSTEM-ENCRYPTION(7) from the Miscellaneous Information Manual, version v1.17.1 — go forth and encrypt responsibly, and remember: encrypt your root independently and let bootc do its little write-content-into-mounted-filesystem thing ✨🎀🦋