CRYPTSETUP-CONVERT(8)

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

✨ CRYPTSETUP-CONVERT ✨

okay bestie, welcome to cryptsetup-convert, part of the Maintenance Commands crew — it's giving glow-up, it's giving format-swap era 💅

💖 NAME 💖

cryptsetup-convert — the lil tool that converts the device between LUKS1 and LUKS2 format 🦋

🎀 SYNOPSIS 🎀

cryptsetup convert --type <format> [<options>] <device>

🌸 DESCRIPTION 🌸

So here's the tea: this command converts the device between LUKS1 and LUKS2 format (if possible). And "if possible" is doing a LOT of heavy lifting there, bestie. The conversion will not be performed if there is an additional LUKS2 feature, or if LUKS1 has an unsupported header size. Not me being picky, it's just the rules 😤

Now, for conversion from LUKS2 to LUKS1, listen up because there's a whole checklist:

  • all active keyslots must use the PBKDF2 key-derivation function
  • the PBKDF2 and anti-forensic filter (AF) hash must be the same as the hash used in the digest
  • all keyslot numbers must be lower than 8 (that's the LUKS1 maximum slot number, no cap)
  • there must be at least one active keyslot
  • and no unbound or reencryption keyslots

Conversion (both directions, so either way, no loopholes) must be performed on an inactive device. There must not be an active dm-crypt mapping established for the LUKS header requested for conversion. Like, she needs her space, okay? 🙈

The --type option is mandatory, and these are the only accepted values: luks1 or luks2. Pick one, bestie, there's no third option 💀

⚠️ WARNING: The convert action can destroy the LUKS header in the case of a crash during conversion or if a media error occurs. Always create a header backup before performing this operation! I'm so serious, back it up. Back. It. Up. 🫶

And <options> can be [--header, --type, --disable-locks] — that's the whole vibe check right there ✨

💅 OPTIONS 💅

  • --batch-mode, -q — Suppresses all confirmation questions. Use with care, fr fr! 😭

If the --verify-passphrase option is not specified, this option also switches off the passphrase verification. (so yeah, it's skipping the vibe check on purpose)

  • --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. Iconic for the girlies who love data 🌈

  • --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).
  • --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. Main character energy: living separately but together 💜

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

  • --help, -? — Show help text and default parameters. Your bestie when you're lost 🧚
  • --type type — Specifies required device type, for more info, read the BASIC ACTIONS section in cryptsetup(8).
  • --usage — Show short option help. The snack-sized version 🍓
  • --version, -V — Show the program version. Slay, what version are we on? ⭐

🦋 REPORTING BUGS 🦋

Found a bug? Not the cute kind? Report bugs at the cryptsetup mailing list <cryptsetup@lists.linux.dev> or in the Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>. 🫶

Please attach the output of the failed command with --debug option added. Help them help you, bestie 🙈

🌈 SEE ALSO 🌈

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

cryptsetup(8), integritysetup(8) and veritysetup(8) — the whole squad 👑

👑 CRYPTSETUP 👑

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

k bye bestie!! this page is from cryptsetup 2.8.8, dated 2026-09-07 — go make a header backup before you touch anything, mwah 💋✨

📦 where this page comes from