Safely Convert a LUKS Device Between LUKS1 and LUKS2

You will convert an existing LUKS container to the other supported metadata format, then verify the result without activating the data mapping. The procedure uses cryptsetup convert from cryptsetup 2.7.0, installed here from the cryptsetup-bin package.

Allow 10 to 20 minutes for preparation and the conversion itself. The command may take longer on a busy or slow device. The conversion changes on-disk metadata, so treat it as a maintenance window rather than a routine read-only inspection.

Before you start

You need root access, a recent tested backup of the encrypted data, and a device path that you have identified beyond doubt. Substitute your real path for /dev/mapper/example-data below. Do not copy that placeholder unchanged.

The target must be the LUKS device containing the header. The device must be inactive: no dm-crypt mapping may be established for the header being converted. Stop services that use the volume, unmount its filesystems, and close its mapping before continuing. A mounted filesystem or an open mapping is a common reason for a refusal, and forcing the operation around it risks making the system unusable.

Check the installed version and inspect the current header. These commands do not convert anything:

cryptsetup --version
sudo cryptsetup luksDump /dev/mapper/example-data

On this system the version check reports cryptsetup 2.7.0. The dump shows whether the current format is LUKS1 or LUKS2. Do not use --dump-volume-key; a volume key can decrypt the data without a passphrase.

Checkpoint: make a header backup

Cryptsetup warns that a crash or media error during conversion can destroy the LUKS header. Create the backup on storage that is not the device being converted, then protect it as a decryption credential. A header backup contains the header and keyslot area, so anyone with the backup and a valid passphrase can access the encrypted data.

sudo cryptsetup luksHeaderBackup /dev/mapper/example-data \
  --header-backup-file /secure/backup/example-data-luks-header.bin

Check that the file exists and has a plausible non-zero size:

sudo stat --format='%n %s bytes' \
  /secure/backup/example-data-luks-header.bin

Keep this backup until you have tested the converted device and have another recovery plan. Do not leave it in a general-purpose shared directory. A backup is not an undo button for unrelated writes to the encrypted data area, but it can restore the previous metadata if the conversion fails and the header remains compatible with that restore.

Choose the target format

The --type option is mandatory. Its only accepted values for this action are luks1 and luks2. Use luks2 when the software that must open the volume supports it. Use luks1 only for a specific compatibility requirement, such as an older recovery environment. LUKS2 offers newer metadata features, but not every LUKS2 device can be converted back to LUKS1.

The direction is explicit in the requested type. For example, this command requests LUKS1 to LUKS2:

sudo cryptsetup convert --type luks2 /dev/mapper/example-data

For the reverse direction, request LUKS1 instead:

sudo cryptsetup convert --type luks1 /dev/mapper/example-data

Checkpoint: convert the inactive device

Recheck that the volume is inactive immediately before the write. In a separate terminal, verify that the relevant mapping is not open and that no filesystem is mounted from it. Stop if a service has reopened it.

Conversion is destructive metadata work. Do not add --batch-mode merely to avoid a confirmation question. That option suppresses confirmations and also disables passphrase verification unless --verify-passphrase is supplied.

Run the chosen command with elevated privileges. Cryptsetup will ask for a passphrase when it needs one:

sudo cryptsetup convert --type luks2 /dev/mapper/example-data

A successful command returns to the shell without an error. An error about an additional LUKS2 feature or an unsupported LUKS1 header size means the requested conversion is not possible for that container. Do not try random options to force it. Restore the original header only if you have a confirmed failure and have checked that the backup belongs to this device.

Verify without activating the data

Inspect the header again and confirm that its reported format matches the target. This does not open the encrypted filesystem:

sudo cryptsetup luksDump /dev/mapper/example-data

You can also ask cryptsetup to recognise the device as LUKS:

sudo cryptsetup isLuks /dev/mapper/example-data
echo "$?"

An exit status of 0 means the device is recognised as LUKS. The header dump is the useful format check; the exit status alone does not distinguish LUKS1 from LUKS2.

Detached headers

If the LUKS header is stored separately, pass the header device or file with --header. The data device remains the final argument. For example:

sudo cryptsetup luksDump --header /secure/headers/example-data.header \
  /dev/mapper/example-data

sudo cryptsetup convert --type luks2 \
  --header /secure/headers/example-data.header \
  /dev/mapper/example-data

The detached header must also be inactive and must be included in your backup and recovery plan. Do not use --disable-locks as a general workaround. The option is intended for restricted environments where the runtime lock directory cannot be used, and the manpage warns against using it otherwise.

Recovery if the conversion fails

First leave the device inactive and preserve the error output. For a diagnostic run, add --debug; debug lines are prefixed with #. Do not publish the output if it contains paths or other operational details that should remain private.

If inspection shows a damaged or unusable header, restore the matching backup while the device remains inactive:

sudo cryptsetup luksHeaderRestore /dev/mapper/example-data \
  --header-backup-file /secure/backup/example-data-luks-header.bin

Restoring replaces the header and keyslots. Only passphrases present in the backup will work afterwards. The backup and device must have compatible volume-key size and data offset, unless the device has no header. Verify the restored header with luksDump before attempting activation, and arrange a controlled maintenance window for any further repair.

Done means

• The installed cryptsetup version and current LUKS format were recorded.
• A header backup exists on separate protected storage.
• The device and any detached header were inactive during conversion.
• The requested --type was either luks1 or luks2.
• luksDump reports the requested format and isLuks exits with status 0.
• The backup is retained until the converted volume has been tested.