Home / Alt manpages / cryptsetup-reencrypt(8)

  • cryptsetup-reencrypt(8)
  • Admin command
  • linux

Re-Encrypt a LUKS Volume Live with cryptsetup reencrypt

cryptsetup reencrypt rewrites the encryption on a live LUKS volume, and picking the wrong mode halfway through is not something you undo with Ctrl-Z. Used carefully, it can refresh a LUKS2 volume key without touching the passphrase, change the cipher or sector size, encrypt a plaintext device, or strip LUKS2 encryption off entirely. This guide covers the safe operational path on the installed cryptsetup 2.7.0.

The route

Jump straight to the step you need, or tick off Done means at the end.

Budget at least the time it takes to read the whole device end to end, plus time for a backup and a controlled recovery test. Root access is needed for ordinary block devices.

  • Backup: a tested, restorable copy of the data, not just a header export.
  • Access: root on the box, and console access in case SSH drops mid-migration.
  • Space: enough free space if you plan to use a data-shifting mode.

1. Identify the volume and back it up

Set a shell variable to the real block device rather than copying the example path blindly. The inspection commands below are read-only and work without sudo if your account can read the device:

DEVICE=/dev/mapper/cryptdata
sudo cryptsetup status "$DEVICE"
sudo cryptsetup luksDump "$DEVICE"
sudo cryptsetup luksHeaderBackup "$DEVICE" --header-backup-file /secure/backup/cryptdata-luks-header.img

For a mapped device, point the re-encryption command at the underlying LUKS device, not an arbitrary filesystem path. A header backup helps recover keyslot metadata, but it is not a substitute for a data copy and it does not make a destructive operation reversible.

Checkpoint

You know the exact source device, have a readable header backup stored away from that device, and have verified the data backup can actually be restored.

2. Choose the operation

Plain reencrypt starts LUKS2 re-encryption. With no data-changing option added, the common case is a volume-key refresh while existing encryption stays in use. An active LUKS2 mapping runs online; an inactive device is processed offline. LUKS1 is stricter: the mapping and filesystem must both be offline, and the local manpage warns that hardware or kernel failure during the process can lose data.

# LUKS2: refresh the effective volume key and keep the existing cipher.
sudo cryptsetup reencrypt --type luks2 "$DEVICE"

# LUKS2: resume an operation already recorded in the header.
sudo cryptsetup reencrypt --resume-only "$DEVICE"

Tip

--resume-only is a handy trap detector: it refuses to start a new operation when no re-encryption is pending. Without it, simply running the command again is the documented way to resume an initialised or interrupted LUKS2 job.

3. Stop everything before offline work

For offline LUKS2 work, unmount filesystems and stop every process using the volume. For LUKS1 this is mandatory, not optional. Check for open users first:

sudo findmnt --source "$DEVICE"
sudo lsblk -o NAME,TYPE,FSTYPE,MOUNTPOINTS "$DEVICE"
sudo fuser -vm "$DEVICE"

Warning

Do not add --force-offline-reencrypt just to get past active-device detection. It bypasses that safety check and can destroy data if the volume is active or in use. It exists mainly for LUKS2 images in files, or a known detection failure, after you have independently proved nothing can access the data.

4. Watch progress and let interruptions recover

Progress reporting can be tuned, or emitted as JSON for a supervisor process:

sudo cryptsetup reencrypt --progress-frequency 10 "$DEVICE"
sudo cryptsetup reencrypt --progress-json "$DEVICE"

Interruption protection depends on the resilience mode:

  • Default: checksum resilience is used unless you choose otherwise.
  • Safer but slower: journal mode writes the hotzone twice, costing more I/O.
  • No protection: none is a performance mode unsuitable for a normal maintenance job.

A deliberate Ctrl-C is safe according to the manpage, as is termination during an orderly system shutdown. If the process crashes or the system loses power, activate the volume again so cryptsetup can run automatic recovery, or repair explicitly:

sudo cryptsetup repair "$DEVICE"
sudo cryptsetup open "$DEVICE" cryptdata

A clean interruption is not permission to reboot repeatedly. Keep the machine powered and stable, and resume against the same device. Resilience and hotzone settings can be changed on resume, except for operations using implicit data-shift resilience.

5. Treat encryption and decryption as migrations

In-place encryption begins with plaintext on the device. During the operation the whole device must be treated as unencrypted: that is a confidentiality boundary, not just a progress detail. A new header can be written to a detached file:

sudo cryptsetup reencrypt --encrypt --type luks2 \
  --header /secure/cryptdata-luks2.header /dev/mapper/plaindata

The command may ask for a new passphrase and processes the data in place. If you use --reduce-device-size 32M for LUKS2 encryption, the final 32 MiB is sacrificed to make room for the metadata. That loss is destructive and permanent: check the device layout and confirm the area is disposable before you use it.

LUKS2 decryption is equally destructive from a confidentiality angle. If the header sits at the head of the data device, export it to a file kept off that device:

sudo cryptsetup reencrypt --decrypt \
  --header /secure/exported-original-luks2.header /dev/mapper/cryptdata

Warning

The destination header file must not already exist when decryption starts. Never put it on a filesystem backed by the device being decrypted, because that can deadlock the migration. The optional new mapping name for encryption only activates after encryption initialisation, not after the whole data area has finished.

6. Verify the result

After the command reports completion, inspect the metadata and open the volume with the intended passphrase. Check the filesystem separately, then compare representative files against the backup. A successful cryptsetup exit proves the metadata operation completed; it does not prove an application-level backup is complete.

sudo cryptsetup luksDump "$DEVICE"
sudo cryptsetup status cryptdata
sudo cryptsetup open "$DEVICE" cryptdata-check
sudo mount -o ro /dev/mapper/cryptdata-check /mnt/cryptdata-check
sudo umount /mnt/cryptdata-check
sudo cryptsetup close cryptdata-check

With a detached header, supply --header /secure/cryptdata-luks2.header to both the inspection and open commands. Store that header backup separately and lock down its permissions: it holds the metadata needed to attack or restore the volume.

Done means

  • Device and mode confirmed: the device, LUKS version and intended mode were checked before writing.
  • Backups exist: a tested data backup and a separate LUKS header backup, both verified.
  • Nothing else touched it: no filesystem or process used the device during offline work.
  • Operation finished clean: it completed or resumed cleanly, with recovery handled if needed.
  • Result verified: luksDump, a read-only mount, and representative file checks all match the plan.