Recovery & Reinstall

This page covers the paths back to a working system when something goes wrong: a boot that drops to a recovery shell, a kernel upgrade that breaks the signed-boot chain, a corrupted LUKS header, or a forgotten passphrase. It also covers when the right answer is simply to reinstall.

InterGenOS is built to be a machine you understand, can modify, and can trust. That extends to recovery: the paths are deliberately minimal, transparent, and free of any hidden back channel.

Most of the time you will never need this page. When you do, work top to bottom — the paths are ordered roughly from “least invasive” to “reinstall.”

Before you start: back up

The single most important recovery measure is a backup you made before the failure. InterGenOS holds no escrow, no master key, and no remote recovery service. If your system uses full-disk encryption and you lose the passphrase, the data is unrecoverable by design. Back up early and often.

If you use full-disk encryption, also back up the LUKS header to a separate, offline medium. A damaged header makes the payload unrecoverable even with the correct passphrase. See Back up and restore the LUKS header below.

Reinstall with Forge

A clean reinstall is the most reliable recovery path when the installed system is too damaged to repair in place, or when you have decided to start fresh.

Boot the InterGenOS live ISO and run Forge, the installer. Forge offers two frontends that behave identically:

A GTK4 / libadwaita GUI, a multi-screen wizard (welcome, keyboard and locale, disk, user, packages, confirm, progress, done).
A dialog-based TUI, suited to SSH-based installs, headless machines, or keyboard-driven setups.

Before any disk write, Forge runs a supply-chain integrity gate: it computes the SHA-256 hash of every package archive to be deployed and verifies each against the cryptographically signed release manifest. A mismatch halts the install before partitioning begins. Overriding that halt requires typing an override phrase in full — paste, drag-and-drop, and the right-click menu are disabled on that field, so the override is a deliberate, conscious act.

A reinstall wipes the target disk. Anything not backed up is lost. For the full walkthrough, see the FORGE Installation Guide.

Recovering an encrypted system

If your system uses LUKS2 full-disk encryption, the recovery paths below apply. For the full encryption model, see Disk Encryption & LUKS.

Boot drops to the FDE recovery shell

Three failed passphrase attempts — or a missing /etc/crypttab, or a LUKS volume that does not appear — drop you into a minimal busybox recovery shell with cryptsetup available. This shell has no network and writes no logs; it is intentionally bare.

From the recovery shell you can:

Retry the unlock manually, then continue the boot:

cryptsetup open /dev/disk/by-uuid/<uuid> cryptroot
mount /dev/mapper/cryptroot /newroot
exec switch_root /newroot /sbin/init

Inspect what the disk exposes: ls /dev/disk/by-uuid/
Inspect the unlock config: cat /etc/crypttab
Reboot: reboot -f (the standard reboot is not available this early in boot)

If /etc/crypttab is empty, encryption was never enabled on this install and the recovery shell is a symptom of a different problem — boot a live ISO and reinstall.

Every passphrase attempt fails

The most common cause is a keyboard-layout mismatch. The FDE unlock prompt uses the US-QWERTY layout by default. If your passphrase contains layout-sensitive characters, type the QWERTY-position equivalents. If the layout is correct and the passphrase still fails, see the forgot-passphrase path.

“LUKS volume not found after 30s wait”

The disk did not enumerate in time. Causes include a failing drive, USB-attached storage, or a slow-initializing RAID controller. From the recovery shell, run ls /dev/disk/by-uuid/ to see what is visible. If the volume appears, retry cryptsetup open manually. If it does not appear, the disk itself is the problem.

EXPERIMENTAL unlock fell through to the passphrase prompt

TPM2-sealed unlock and FIDO2-token unlock are EXPERIMENTAL v1.0 sub-options. Both compose alongside the passphrase slot — the passphrase is never replaced, so it is always the fallback.

TPM2 fell through: a measured-boot value changed — typically PCR0 (firmware update) or PCR7 (Secure Boot reconfiguration, or a shim/MOK update). Enter the passphrase to boot. Re-enrolling TPM2 against the new state restores automatic unlock. Diagnose with:
```
journalctl -b | grep '\[EXPERIMENTAL TPM2\]'
```
FIDO2 did not detect the token: plug the token in before boot — the initramfs waits up to 30 seconds for it to enumerate. A dead token battery means falling back to the passphrase. Diagnose with:
```
journalctl -b | grep '\[EXPERIMENTAL FIDO2\]'
```

More broadly, all FDE-unlock messages carry a [fde-init] prefix and can be reviewed post-boot with journalctl -b | grep fde-init.

I forgot my passphrase

Your data is gone. There is no master key, no recovery-key escrow, and no back door. This is intentional: a recovery channel that the project could use is a channel an attacker could use.

Boot a live ISO and reinstall. A backup made earlier is the only mitigation.

Add or remove a key slot

LUKS2 supports up to eight key slots. From a running, unlocked system, as root:

# Add a second passphrase (prompts for an existing one first)
cryptsetup luksAddKey /dev/disk/by-uuid/<uuid>

# Remove a slot (prompts for the passphrase belonging to that slot)
cryptsetup luksRemoveKey /dev/disk/by-uuid/<uuid>

Adding or removing one slot never affects the others. If luksAddKey reports “No key available with this passphrase,” the passphrase you entered matches no existing slot — try others, and if none work, you are in the forgot-passphrase case above.

Back up and restore the LUKS header

The LUKS header holds the encryption metadata. If it is corrupted — disk damage at the wrong offset, or an accidental dd to the wrong device — the payload is unrecoverable even with the correct passphrase. Back it up to offline media:

cryptsetup luksHeaderBackup /dev/disk/by-uuid/<uuid> \
    --header-backup-file /path/to/external/header.bin

To restore:

cryptsetup luksHeaderRestore /dev/disk/by-uuid/<uuid> \
    --header-backup-file /path/to/external/header.bin

Anyone with the header backup and your passphrase can decrypt the disk. Treat the backup with the same care as the disk itself.

Recovering a broken signed-boot chain

InterGenOS boots a signed UKI: a single file bundling the kernel, the initramfs, and the kernel command line, signed with your machine’s Machine Owner Key (MOK). On an encrypted install, that bundled initramfs is the FDE initramfs, so the unlock prompt lives inside the signed envelope and cannot be substituted by an attacker.

A kernel upgrade rebuilds and re-signs the UKI. If that signing step fails, you can be left unable to boot the normal path.

UKI signing failed on a kernel upgrade

The kernel post-install hook preserves a GRUB-loads-vmlinuz path as a recovery fallback. From the GRUB recovery entry you can boot the bare vmlinuz, supply the FDE initramfs with an initrd= argument, and unlock as normal.

Before retrying the post-install hook, check the underlying signing-failure messages:

cat /var/log/intergen-kernel-postinstall.log

The ESP filled up and the new UKI was not written

When the ESP runs out of space during a kernel upgrade, UKI generation logs the condition and skips writing the new UKI; the previous kernel’s UKI remains the default, so the system still boots. To recover space and write the current kernel’s UKI, remove an old kernel and re-run the post-install hook:

pkm remove linux-kernel-<old-version>

Then re-run the post-install hook for the current kernel. The same log file records the underlying messages.

For the full signed-boot model and MOK enrollment, see Verified Boot & Secure Boot.

What recovery never includes

InterGenOS recovery has hard boundaries by design:

No remote recovery service and no escrowed key. The project cannot decrypt your disk for you.
No telemetry in the recovery paths. The FDE recovery shell has no network and writes no logs.
No silent overrides. The Forge integrity gate cannot be bypassed by accident; the override phrase must be typed in full, with paste disabled.

These are not limitations to work around. They are the point: a recovery channel that exists for your convenience also exists for an attacker’s.

When in doubt, reinstall from a known-good ISO

If you cannot trace a failure to one of the paths above, the safest move is to back up what you can, verify your live ISO, and reinstall with Forge. The integrity gate ensures the packages deployed match the signed manifest, so a reinstall returns you to a known-good state.

InterGenOS Wiki