Restore a LUKS Header Safely with cryptsetup

cryptsetup luksHeaderRestore writes a saved header backup back onto a device: one of the few actions that can brick a volume outright. This guide uses cryptsetup 2.7.0 from the Ubuntu cryptsetup-bin package version 2:2.7.0-1ubuntu4.2.

Allow about fifteen minutes for the checks and command, plus whatever time you need to identify the correct backup. You need root access, the backup file, the encrypted device or detached header device, and a way to confirm that the backup belongs to that volume.

Warning: restoring replaces the target's LUKS header and keyslot area. Afterward, only passphrases present in the backup will work. The operation changes on-disk metadata and can make the volume inaccessible if you choose the wrong target or backup. Do not run the restore until you have checked the device identity and have a recovery copy of the backup.

1. Check the installed command

First confirm which executable and package version you are using. These are ordinary, read-only commands:

$ command -v cryptsetup
/usr/sbin/cryptsetup
$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ dpkg-query -W -f='\${Package} \${Version}\n' cryptsetup-bin
cryptsetup-bin 2:2.7.0-1ubuntu4.2

The version line can contain different feature flags on another machine. The action used below is luksHeaderRestore, with the backup named by --header-backup-file and the target device as the final argument.

Checkpoint: stop if command -v points at an unexpected binary, or if the installed package is not the one you intended to administer.

2. Identify the target without changing it

Use a stable device path such as a path under /dev/disk/by-id where possible. Do not rely on a changing name such as /dev/sdb after reboot. Inspect the device and its existing metadata before choosing it:

$ ls -l /dev/disk/by-id/ata-EXAMPLE_DISK_SERIAL
$ sudo cryptsetup luksDump /dev/disk/by-id/ata-EXAMPLE_DISK_SERIAL

The luksDump command is read-only, but it normally needs access to the block device, so the example uses sudo. Compare the reported LUKS type, key size and data offset with the records kept for the backup. Do not infer the device from its mount point alone, particularly when restoring a detached header.

If the header is stored separately from the encrypted data, the final device argument is still the LUKS device and --header names the separate header device or file. For example:

$ sudo cryptsetup luksDump \
    --header /dev/disk/by-id/usb-EXAMPLE_HEADER_SERIAL \
    /dev/disk/by-id/ata-EXAMPLE_DATA_SERIAL

Checkpoint: write down the exact target and, if applicable, the detached header path. A header restore aimed at the wrong block device is not recoverable by correcting the command afterward.

3. Inspect and preserve the backup

Confirm that the backup file is readable, identify its size, and make a second copy before the restore. The backup contains sensitive metadata and keyslot material, so keep its permissions and storage under control:

$ BACKUP='/secure/path/luks-header-backup.bin'
$ test -r "$BACKUP" && echo 'backup is readable'
backup is readable
$ stat --format='size=%s bytes mode=%A owner=%U:%G' "$BACKUP"
$ sha256sum "$BACKUP"
$ sudo install -m 600 -- "$BACKUP" \
    '/secure/path/luks-header-backup.bin.before-restore'

Compare the checksum with the value recorded when the backup was made, if one exists. A checksum proves that you have the same bytes as the recorded file; it does not prove that the file belongs to this device. Confirm that separately from your backup records.

Do not use - as a way to mean standard input. For this action, the manpage says that - is treated as a literal filename named -.

4. Check the compatibility boundary

The existing header and the backup must have matching volume key size and data offset. If there is no LUKS header on the device, cryptsetup can write the backup there, but that does not remove the need to verify the device. A backup from a different volume is not made safe by having the same capacity or a similar label.

Use the metadata from luksDump, the records made with the backup, and your storage inventory to establish the match. If any value is unknown, stop and recover the original backup records or obtain a second, independently checked copy. Do not guess, and do not use --disable-locks to work around uncertainty.

Also arrange a maintenance window. The target must not be changing underneath the metadata operation. Close applications using the encrypted volume and stop any service that has the device open. Record the service state so that you can restore it after verification.

5. Restore the header and keyslots

Destructive action: this is the point at which on-disk metadata is replaced. The following command needs elevated privileges. Replace every placeholder, and review the complete command before pressing Enter:

$ BACKUP='/secure/path/luks-header-backup.bin'
$ TARGET='/dev/disk/by-id/ata-EXAMPLE_DISK_SERIAL'
$ sudo cryptsetup luksHeaderRestore \
    --header-backup-file "$BACKUP" \
    "$TARGET"
WARNING: The header and keyslots will be replaced.
Type 'YES' to continue: YES

The exact confirmation text and any later passphrase prompt can vary with the installed build and device state. Do not add --batch-mode to a first recovery attempt. That option suppresses confirmation questions, and the manpage warns that it should be used with care.

For a detached header, put --header before the target:

$ sudo cryptsetup luksHeaderRestore \
    --header /dev/disk/by-id/usb-EXAMPLE_HEADER_SERIAL \
    --header-backup-file "$BACKUP" \
    /dev/disk/by-id/ata-EXAMPLE_DATA_SERIAL

Recovery: there is no ordinary undo command. Your recovery path is the preserved, verified backup and the original target metadata if you made a separate backup before this operation. Do not delete either copy until the volume has been tested.

6. Verify before reopening services

Read the restored metadata and check that the expected LUKS type and keyslot information are present:

$ sudo cryptsetup luksDump "$TARGET"
$ sudo cryptsetup isLuks "$TARGET"
$ printf 'cryptsetup status: %s\n' "$?"
cryptsetup status: 0

isLuks returning status 0 confirms that cryptsetup recognises a LUKS header. It does not confirm that the backup is the right one or that a particular passphrase will open the volume.

Test a known passphrase using the normal activation path for this machine, then inspect the mapping before bringing services back:

$ sudo cryptsetup open "$TARGET" restored-check
Enter passphrase for /dev/...:
$ sudo cryptsetup status restored-check
$ sudo cryptsetup close restored-check

Use the exact mapping and mount procedure documented for your system. If the passphrase fails, stop. Do not repeatedly try guesses, do not overwrite the restored header again, and do not remove the backup. Recheck the target, backup provenance, detached-header option and recorded passphrase before taking further action.

Handle diagnostic options carefully

If the command fails, rerun the same operation only after confirming that it has not partially changed the situation. Add --debug to collect diagnostic logs when needed:

$ sudo cryptsetup --debug luksHeaderRestore \
    --header-backup-file "$BACKUP" \
    "$TARGET"

Debug output can expose device details and should be handled as sensitive operational information. The manpage says debug lines are prefixed with #. For LUKS2, --debug-json adds JSON metadata to the diagnostics.

--disable-locks is only valid for LUKS2 and disables protection for metadata on disk. Use it only in a restricted environment where locking is impossible because /run cannot be used. It is not a general fix for a lock error, and bypassing it while another process can touch the metadata increases the risk of damage.

Done means