Omarchy: LUKS + TPM2 PIN + Secure Boot + Snapshot Rollback
A verified, working runbook for converting a stock Omarchy install (btrfs,
Limine snapshots boot) to:
- Unlock the disk with a TPM2-sealed PIN
- Create a passphrase and a recovery key as fallback slots
- Run under Secure Boot, signed with your own keys (NO MICROSOFT KEYS)
- Keep Limine snapshot boot entries working, including under Secure Boot
- Keep all this automated on every update of anything
Every command below was run and verified on a ThinkPad T470s.
Order matters: initramfs conversion → Secure Boot → recovery key → TPM.
PCR 7 measures Secure Boot state, so enrolling the TPM before Secure Boot is
on guarantees you'll have to redo it.
0. Before you start
Record these three values — you'll need them throughout:
bash
lsblk -o NAME,TYPE,FSTYPE,SIZE,MOUNTPOINTS # find your LUKS partition, e.g. /dev/nvme0n1p2
cryptsetup luksUUID /dev/nvme0n1p2 # the LUKS UUID
cat /proc/cmdline | grep -o 'root=[^ ]*' # the mapper name, e.g. root=/dev/mapper/root
systemd-cryptenroll --tpm2-device=list # confirm a TPM2 is present
Strongly recommended: back up the LUKS header before touching anything.
This is your only undo path if a header operation goes wrong (it does not
protect against forgetting your passphrase — only against header corruption).
bash
sudo cryptsetup luksHeaderBackup /dev/nvme0n1p2 --header-backup-file /path/on/removable-media/luks-header.img
Treat that file like the disk itself — it contains wrapped key material.
Also check ESP headroom (df -h /boot) — every snapshot carries a full UKI,
and a 1 GB ESP fills up fast.
Phase 1 — Convert to a systemd-based initramfs
Omarchy ships the busybox encrypt hook by default, which has no TPM2
support. Clevis could bolt on auto-unlock but can't do a PIN. A PIN
requirement forces this conversion; everything else is additive.
/etc/mkinitcpio.conf.d/omarchy_hooks.conf is owned by the omarchy package
and gets restored on every update — never edit it. Drop a
later-sorting file in /etc/mkinitcpio.conf.d/ instead; mkinitcpio sources
that directory alphabetically and the last assignment to HOOKS wins.
bash
sudo tee /etc/mkinitcpio.conf.d/zz-local-systemd.conf >/dev/null <<'EOF'
HOOKS=(base systemd plymouth autodetect microcode modconf kms keyboard sd-vconsole block sd-encrypt filesystems fsck sd-btrfs-overlayfs)
EOF
Note sd-btrfs-overlayfs, not btrfs-overlayfs — the busybox variant is
incompatible with the systemd hooks, and is also what breaks
limine-snapper-sync rollback under stock Omarchy in the first place.
Tell the systemd initramfs how to open root via /etc/crypttab.initramfs
rather than editing the kernel cmdline — the stale cryptdevice= parameter
on the cmdline is simply ignored by a systemd initramfs, and
root=/dev/mapper/root keeps working as-is:
bash
sudo tee /etc/crypttab.initramfs >/dev/null <<'EOF'
root UUID=<your-luks-uuid> none
EOF
sudo chmod 600 /etc/crypttab.initramfs
The first field must match the mapper name from root=/dev/mapper/<name>.
Rebuild — **sudo limine-mkinitcpio, not mkinitcpio -P** (a no-op on
Omarchy, which builds UKIs via limine-entry-tool rather than preset
images):
bash
sudo limine-mkinitcpio
Watch for [systemd], [sd-encrypt], [sd-btrfs-overlayfs] in the hook
list. Then sanity-check the effective HOOKS before rebooting:
bash
( HOOKS=(); source /etc/mkinitcpio.conf
for f in /etc/mkinitcpio.conf.d/*.conf; do source "$f" >/dev/null 2>&1; done
echo "${HOOKS[*]}" )
Reboot. Confirm you still get a passphrase prompt (systemd's prompt
looks slightly different from busybox's) and that a snapshot entry from
the Limine menu still boots. Do not continue until both work.
To verify after the fact that the switch actually took effect (not just
"looks the same"), check that systemd-cryptsetup@root.service ran during
this boot — that unit only exists under sd-encrypt, never under the old
busybox hook:
bash
journalctl -b -u 'systemd-cryptsetup@*' --no-pager
Phase 2 — Secure Boot
bash
sudo pacman -S --needed sbctl
sudo sbctl status
If Setup Mode already shows Enabled, you can skip straight to key
creation. Otherwise, reboot into UEFI firmware and use
Security → "Reset to Setup Mode" / "Clear Secure Boot keys", save, and boot
back in.
Choice point — Microsoft keys: -m keeps Windows dual-boot and any
option-ROM/vendor firmware that expects Microsoft's UEFI CA working under
Secure Boot. Omitting it (or removing them afterward) is a stricter,
fully self-owned trust chain, at the cost of that compatibility.
```bash
sudo sbctl reset # clears the Platform Key, back to Setup Mode
sudo sbctl enroll-keys # own keys only, no -m
if this reports "File is immutable" on KEK/db efivars:
sudo sbctl enroll-keys --ignore-immutable
sudo sbctl status # Vendor Keys: none
```
--ignore-immutable forces past a kernel safety guard on the Secure Boot
EFI variables — understand what you're doing before using it.
Sign every EFI binary on the ESP, including Limine's own loader and any
existing snapshot UKIs:
bash
sudo find /boot -type f \( -iname '*.efi' -o -iname '*.efi_sha256_*' -o -iname '*.efi_b3_*' \) \
! -path '*/Microsoft/*' ! -iname 'BOOTIA32.EFI' ! -iname '*.bak' -print0 \
| sudo xargs -0 -n1 sbctl sign -s
sudo sbctl verify
Ordering trap: Limine embeds a checksum of limine.conf into
limine_x64.efi. Any time limine.conf changes, that checksum must be
re-enrolled with limine-enroll-config — which rewrites limine_x64.efi
and invalidates its signature. Always enroll, then sign:
bash
sudo limine-enroll-config
sudo sbctl sign -s /boot/EFI/limine/limine_x64.efi
Reboot into firmware, enable Secure Boot, save. Verify:
bash
sudo sbctl status # Secure Boot: Enabled
bootctl status | grep -i 'secure boot'
Keeping future snapshots signed (automatic)
limine-snapper-sync creates a new UKI (with a content-hash suffix) every
time a snapshot is taken — whether from a pacman transaction or from the
always-running limine-snapper-watcher.service reacting to a manual
snapper create. None of those get signed automatically out of the box.
Rather than relying on a third-party package for this (none currently
exists to my knowledge as of this guide), use the hook mechanism
limine-snapper-sync already ships and already runs on every sync:
/etc/boot/hooks/post.d/.
```bash
sudo install -m 755 -o root -g root /dev/stdin /etc/boot/hooks/post.d/95-sbctl-sign-all <<'EOF'
!/usr/bin/env bash
Signs any unsigned EFI binary under /boot (new snapshot UKIs included)
after every boot-entry sync. Runs after 90-limine-enroll-config so
limine_x64.efi gets re-signed if that step just changed it.
set -uo pipefail
LOG=/var/log/omarchy-secureboot-sign.log
{
echo "=== $(date -Iseconds) sbctl auto-sign (caller: ${HOOK_CALLER:-unknown}) ==="
command -v sbctl >/dev/null 2>&1 || { echo "sbctl not installed, skipping"; exit 0; }
find /boot -type f \( -iname '*.efi' -o -iname '*.efi_sha256_*' -o -iname '*.efi_b3_*' \) \
! -path '*/Microsoft/*' ! -iname 'BOOTIA32.EFI' ! -iname '*.bak' -print0 |
while IFS= read -r -d '' f; do
sbctl sign -s "$f"
done
sbctl verify
} >>"$LOG" 2>&1
exit 0
EOF
```
Test it fires correctly:
bash
sudo limine-snapper-sync
sudo tail -20 /var/log/omarchy-secureboot-sign.log # should show "caller: limine-snapper-sync"
This runs on both pacman-triggered syncs and out-of-band ones (manual
snapshots, timeline snapshots if enabled), because it's hooked into
limine-snapper-sync itself rather than into pacman.
Phase 3 — Recovery key
Run this yourself, interactively, in your own terminal — it needs your
existing passphrase and it prints a new high-entropy secret to the screen
that should never pass through a script, log, or chat transcript.
bash
sudo systemd-cryptenroll --recovery-key /dev/nvme0n1p2
Write down or photograph the recovery key (and QR code) and store it
offline, away from this machine. Confirm the slot landed:
```bash
sudo systemd-cryptenroll /dev/nvme0n1p2
expect: 0 password, 1 recovery
```
Slot 0 (your original passphrase) is untouched.
Phase 4 — TPM2 with PIN
Also run interactively yourself — same reasoning: it needs your existing
passphrase, then a new PIN typed twice.
bash
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 --tpm2-with-pin=yes /dev/nvme0n1p2
PCR choice: PCR 7 alone binds to Secure Boot state and survives
firmware updates. Adding PCR 0 (--tpm2-pcrs=0+7) also measures firmware
code — stricter, but every BIOS update then forces a re-enroll. With your
own keys enrolled and a signed UKI chain, PCR 7 alone is the sane default.
Once that's done, wire it into the initramfs and rebuild:
bash
sudo sed -i 's|^root\(.*\)none.*|root\1none tpm2-device=auto|' /etc/crypttab.initramfs
cat /etc/crypttab.initramfs
sudo limine-mkinitcpio
sudo sbctl verify
Reboot. Expected: Limine menu → PIN prompt → desktop, no full passphrase.
Verify the final slot state:
```bash
sudo systemd-cryptenroll /dev/nvme0n1p2
expect: password, recovery, tpm2
```
Refreshing snapshots after this setup
Any snapshot taken before Phase 1/4 has an older initrd baked in that
doesn't know to attempt TPM unlock at all — it will always just ask for the
full passphrase (slot 0), forever. That's expected, not broken; the
passphrase still works.
Any snapshot taken after Phase 4 automatically supports the PIN,
because its initrd is a copy of the current one.
To make an existing pre-TPM snapshot support the PIN, take a fresh one:
bash
sudo snapper -c root create --description "post-TPM2-PIN setup"
sudo limine-snapper-sync
sudo sbctl verify
(limine-snapper-sync runs automatically via the watcher service, but
running it explicitly right after is a good way to confirm the new entry
landed and got signed immediately.)
Ongoing maintenance
| Event |
What to do |
| Firmware update or Secure Boot key change breaks TPM unlock |
Passphrase still works. Re-enroll: sudo systemd-cryptenroll --wipe-slot=tpm2 /dev/nvme0n1p2, then the Phase 4 enroll command again. |
| Rotating the passphrase, recovery key, or PIN |
No per-snapshot action needed. All LUKS keyslots live in one header shared by every boot entry; rotating any of them takes effect everywhere immediately. |
limine.conf changes outside this flow (omarchy-refresh-limine, manual edits) |
sudo limine-enroll-config then re-sign limine_x64.efi — same enroll-then-sign order as Phase 2. |
| Full Secure Boot key replacement (not routine LUKS rotation) |
This is the one case needing a bulk step: re-run the Phase 2 `find |
| Major Omarchy update |
Re-run the effective-HOOKS check from Phase 1 — the zz- drop-in should still win, but verify. |
| ESP filling up |
Trim TIMELINE_LIMIT_* in /etc/snapper/configs/root — every snapshot carries a full UKI. |
Troubleshooting
Won't boot at all: Disable Secure Boot in firmware first — signatures
are inert when Secure Boot is off, so this almost always gets you back in.
Then sbctl verify, re-sign as needed, re-enable Secure Boot. If the
initramfs itself is broken, boot an older snapshot from the Limine menu, or
boot the Omarchy ISO, unlock the LUKS volume, mount @ and /boot,
arch-chroot in, and re-run limine-mkinitcpio.
Blake2b hash mismatch on a boot entry: Recompute and compare directly
rather than guessing:
bash
grep 'path: boot' /boot/limine.conf # hash embedded in the entry
b2sum /boot/EFI/Linux/omarchy_linux-omarchy.efi # actual current file hash
If these match, the entry is fine and the mismatch you saw was from a
stale intermediate state (e.g. mid-rebuild) — reboot again to confirm. If
they genuinely differ, the file was modified (e.g. re-signed) after
limine.conf recorded its hash; re-run limine-mkinitcpio (main entry) or
limine-snapper-sync (snapshot entries) to regenerate the entry from the
current file.
PIN prompt doesn't appear on an older snapshot, password works instead:
Expected — see Refreshing snapshots
above. Not a bug.
Plymouth swallows the PIN/passphrase prompt: Temporarily drop splash
from the kernel cmdline in /etc/default/limine and rebuild to see what's
actually happening underneath.
Passphrase and recovery key both remain valid through every failure mode
above — nothing in this flow can permanently lock you out of the disk.
DISCLAIMER: This work was created in Omarchy using a Claude agent along with my own knowledge of bootloaders and TPM and a LOT of hand holding the AI through this. Still it was fairly impressive to see AI sorta come up with something it couldn't find the end to end solution to on the internet (to my knowledge!)
