You are staring at a GRUB rescue prompt because the boot partition got corrupted during a botched dnf system-upgrade. Or maybe you accidentally ran dd on the wrong device and wiped the first megabyte of your root volume. The data is still there, encrypted and safe, but the LUKS header is gone. Without that header, the encryption keys are inaccessible. Your data is mathematically unrecoverable unless you have a backup of the header. This is the moment you wish you had prepared.
What's actually happening
LUKS stores the encryption metadata at the very beginning of the partition. This metadata includes the key slots, the master key derivation parameters, the UUID, and the version information. Think of the header as the lock mechanism on a safe. The encrypted data is the contents inside. If you smash the lock, you cannot open the safe, even if you have the combination. The cryptsetup tool manages this header. Backing up the header is copying the lock mechanism to a separate file. Restoring it puts the lock back so you can use your keys again.
Fedora uses LUKS2 by default. The LUKS2 header is larger and more flexible than LUKS1. It supports multiple keyslots, JSON metadata, and different encryption algorithms. The header size is not fixed. It depends on the number of keyslots and the metadata configuration. Using dd to copy a fixed number of sectors is risky because you might miss part of the header or overwrite adjacent data. cryptsetup calculates the exact header size and handles the format correctly. Always use cryptsetup for header operations.
The header also contains the key slots. Each key slot holds a hashed version of a passphrase or key file. If you add a new key with cryptsetup luksAddKey, the header changes. Your old backup becomes stale. You must create a new backup after any key management operation. A backup is only valid for the exact state of the header at the time of creation.
The fix
Identify the encrypted partition first. Device names can change between boots, especially with USB drives or NVMe devices. Verify the UUID or label before running commands. Run lsblk -f to list block devices and their filesystems. Look for the device with crypto_LUKS in the FSTYPE column.
lsblk -f
# WHY: Lists all block devices with filesystem types.
# Look for the device showing crypto_LUKS to identify your encrypted partition.
# Do not guess the device path. A wrong path here can corrupt a different disk.
# Note the UUID to cross-reference with /etc/crypttab if needed.
Create the backup. The file must be stored on a different physical device than the encrypted partition. If the disk fails, a backup on the same disk is useless. Use a USB drive, a remote server, or a separate internal volume. The backup file contains sensitive key material. Treat it like a password. Restrict access permissions immediately after creation.
cryptsetup luksHeaderBackup /dev/nvme0n1p3 --header-backup-file /mnt/usb/luks-header-2024-05-20.img
# WHY: Dumps the LUKS header to a file.
# Replace /dev/nvme0n1p3 with your actual encrypted partition.
# The backup file contains sensitive key material. Treat it like a password.
# Store this file on a separate physical medium, not the same disk.
# Include a timestamp in the filename to track versions.
Set strict permissions on the backup file. Root should be the only user who can read it.
chmod 600 /mnt/usb/luks-header-2024-05-20.img
# WHY: Restricts file access to the owner only.
# Prevents other users from reading the key material.
# Run this immediately after creating the backup.
Restoring the header requires the device to be inactive. You cannot restore while the LUKS device is open or the filesystem is mounted. Unmount the filesystem first, then close the LUKS mapping.
umount /mnt/fedora_root
# WHY: Unmounts the filesystem on top of the LUKS device.
# You must unmount before closing the LUKS mapping.
# If the device is busy, check for open files or processes.
cryptsetup close /dev/mapper/fedora_root
# WHY: Closes the active LUKS mapping.
# You must close the device before restoring the header.
# The device name in /dev/mapper/ matches the name in /etc/crypttab.
Restore the header from the backup file. This operation overwrites the current header. Double-check the device path. A wrong path destroys another disk's header and locks you out of that volume.
cryptsetup luksHeaderRestore /dev/nvme0n1p3 --header-backup-file /mnt/usb/luks-header-2024-05-20.img
# WHY: Overwrites the current LUKS header with the backup.
# This operation is destructive to the existing header.
# Ensure the device path is correct. A wrong path destroys another disk's header.
# The device must not be currently active or mounted.
Reopen the LUKS device and mount the filesystem. Verify you can access your data.
cryptsetup open /dev/nvme0n1p3 fedora_root
# WHY: Opens the LUKS device using the restored header.
# You will be prompted for the passphrase.
# If the passphrase fails, the restore may have failed or the backup is corrupted.
mount /dev/mapper/fedora_root /mnt/fedora_root
# WHY: Mounts the filesystem to verify data integrity.
# Check a few files to ensure the data is accessible.
# If mount fails, check journalctl for errors.
Verify the backup immediately. A backup you cannot read is worse than no backup.
Verify it worked
Inspect the backup file without mounting anything. cryptsetup luksDump reads the header and prints the metadata. Check the output for the UUID and key slot status. The UUID must match the device you backed up. The key slots should show ENABLED for the keys you use.
cryptsetup luksDump --header-backup-file /mnt/usb/luks-header-2024-05-20.img
# WHY: Reads the backup file and prints the LUKS metadata.
# Check the output for the UUID and key slot status.
# If this command fails, the backup file is corrupted. Create a new backup immediately.
# Look for "LUKS version: 2" to confirm LUKS2 format.
Test the backup in a safe environment if possible. Create a dummy file, write a small amount of data, encrypt it with a test key, and restore the header from your backup. This proves the backup file is structurally valid and can be restored. Do not test on production data.
Check the key slots after a restore. If you added keys after the backup was created, those keys will be gone. The restore reverts the header to the state at backup time. You will need to re-add any keys that were added after the backup.
cryptsetup luksDump /dev/nvme0n1p3 | grep -A 5 "Keyslots"
# WHY: Lists the active key slots on the device.
# Compare this with the backup file output.
# If slots are missing, you need to re-add those keys.
# Key management changes require a new header backup.
Verify the backup file is readable. A backup you cannot read is worse than no backup.
Common pitfalls and what the error looks like
The most common error is targeting the wrong device. If you point luksHeaderBackup at a non-LUKS partition, you get a clear error.
Device /dev/sda1 is not a valid LUKS device.
This means the device does not contain a LUKS header. Check your device path. Verify with lsblk or blkid. Do not force the operation. Forcing a backup on a non-LUKS device creates a useless file.
Another pitfall is overwriting the backup file. If you run the backup command with the same filename, the old backup is destroyed. Always use a timestamp or version number in the filename. Keep multiple backups if you make frequent key changes.
Restoring to an active device fails with a busy error.
Device /dev/mapper/fedora_root is busy.
You must close the device first. Unmount the filesystem, then close the LUKS mapping. Check for processes holding files open with lsof or fuser.
lsof +D /mnt/fedora_root
# WHY: Lists processes with open files on the mount point.
# Kill or stop these processes before unmounting.
# A busy mount prevents closing the LUKS device.
SELinux can block access to the backup file if the context is wrong. If you move the backup file to a different location, restore the context.
restorecon -v /mnt/usb/luks-header-2024-05-20.img
# WHY: Resets the SELinux context to the default for the path.
# SELinux may deny access if the context is incorrect.
# Run this if cryptsetup fails with a permission error despite correct chmod.
Double-check the device path before restore. One typo can lock you out of a different volume forever.
When to use this vs alternatives
Use cryptsetup luksHeaderBackup when you need a portable copy of the LUKS metadata for disaster recovery. Use cryptsetup luksDump when you only need to inspect the header contents without creating a backup file. Use dd to copy raw sectors only when you are performing low-level forensics and understand the exact header layout. Use full disk imaging tools like ddrescue when the disk has physical read errors and you need to salvage the entire partition. Use cryptsetup luksAddKey when you need to add a new passphrase without modifying the existing keys. Use cryptsetup luksChangeKey when you need to replace a specific key slot.
Use the right tool for the job. Header backups are for metadata recovery, not full data cloning.