CRYPTSETUP-...ADERRESTORE(8)

📦
version 2.8.8 · 17 versions
, in arch rolling, fedora 44, nixpkgs unstable

💖 CRYPTSETUP-...ADERRESTORE 💖

okay bestie, so this one's from the Maintenance Commands section of the cryptsetup manual (you know, the CRYPTSETUP-...ADERRESTORE(8) girlies) and it is literally about putting a LUKS header back from a backup. sit down, hydrate, let's go 🫶

✨ NAME ✨

cryptsetup-luksHeaderRestore — restore a binary backup of the LUKS header and keyslot area

no fr that's the whole vibe. it puts your header BACK. 🎀

🌸 SYNOPSIS 🌸

cryptsetup luksHeaderRestore --header-backup-file <file> [<options>]
<device>

so it's cryptsetup luksHeaderRestore, you gotta hand it a --header-backup-file <file>, you can sprinkle [<options>] on top, and then you point it at a <device>. that's the shape of it, periodt. ✨

🦋 DESCRIPTION 🦋

Restores a binary backup of the LUKS header and keyslot area from the specified file.

Using '-' as a filename reads the header backup from a file named '-'.

⚠️ All keyslots will be replaced — like, ALL of them — and only the passphrases from the backup will work afterward. so if you had a passphrase you added after the backup was taken? bestie. it's gone. it's not coming back. 😭

This command requires that the volume key size and data offset of the LUKS header and backup match. Alternatively, the backup will also be written if the device has no LUKS header.

and <options> can be [--header, --header-backup-file, --disable-locks]. that's the short list, but keep reading because there's more below 👇

💅 OPTIONS 💅

  • --batch-mode, -q — suppresses all confirmation questions. Use with care! like, it's not gonna ask you "are you sure bestie" anymore, it's just gonna DO it. 🙈

If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

  • --debug or --debug-json — run in debug mode with full diagnostic logs. Debug output lines are always prefixed by #.

If --debug-json is used, additional LUKS2 JSON data structures are printed. (json girlies stay winning 🏆)

  • --disable-locks — disable lock protection for metadata on disk. This option is valid only for LUKS2 and is ignored for other formats.
WARNING: Do not use this option unless you run cryptsetup in a restricted environment where locking is impossible to perform (where /run directory cannot be used).

ngl that's a whole warning in all caps, so please take it seriously 💀

  • --header <device or file storing the LUKS header> — use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices.

For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

  • --header-backup-file file — specify a file with the header backup file. (yes, the file. the backup file. that one 📁)
  • --help, -? — show help text and default parameters.
  • --usage — show short option help.
  • --version, -V — show the program version.

🐛 REPORTING BUGS 🐛

found a bug? no gatekeeping, tell the people:

Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added. like, help them help you, that's the whole point 🫶

👀 SEE ALSO 👀

Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8) — the whole friend group, iconic honestly ✨

👑 CRYPTSETUP 👑

Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.

and that's the whole page bestie, no cap, you ate it 💅🌈

cryptsetup 2.8.8 · 2026-09-07 · CRYPTSETUP-...ADERRESTORE(8) — go restore that header, main character 💖

📦 where this page comes from