Suspend and Resume a LUKS Mapping with cryptsetup

cryptsetup luksSuspend freezes an active LUKS device and wipes its encryption key from kernel memory, ready to bring back with luksResume. The examples use cryptsetup 2.7.0 from the installed cryptsetup-bin package, version 2:2.7.0-1ubuntu4.2.

Allow about fifteen minutes for the command sequence, plus enough time to identify the correct mapping. You need root privileges, an already-open LUKS mapping, a working recovery path, and a maintenance window. This is a service-disrupting operation. Do not practise it on a live root, boot, database or remote-only system.

1. Confirm the installed tool

First check the binary and version. This is read-only and does not need elevated privileges:

$ 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 subcommand is written as cryptsetup luksSuspend NAME. NAME is the device-mapper name, not the filesystem path and not the LUKS header device. For a mapping shown as /dev/mapper/secure_data, the name is secure_data.

Checkpoint: Write down the exact mapping name and the command you will use to resume it. If you cannot identify both, stop here.

2. Select a mapping that can safely be frozen

List the mapper nodes and inspect the host's service dependencies before changing state:

$ ls -l /dev/mapper
$ findmnt -rn -S /dev/mapper/NAME
$ systemctl list-dependencies --reverse dev-mapper-NAME.device

Replace NAME in each command with the mapping you identified. The first command shows candidates. The second shows filesystems mounted from that mapping. The third can reveal services that depend on the device; its output varies by system.

Never suspend the mapping containing the cryptsetup executable. The local manpage calls this out because the command can deadlock when its own binary or required runtime files are on the frozen device. Treat a mapping used by your current shell, SSH session, logging, name service or recovery tools as unsafe too. The safe choice is normally a non-root data mapping during a planned maintenance window.

A detached LUKS header does not change which mapping is suspended. The optional --header HEADER argument points to the device or file holding that header, while NAME still identifies the active mapping. Use it only when the mapping was opened with a detached header and you know the exact header path.

3. Prepare the recovery command

Open a root shell or arrange an approved privileged execution path before suspending anything:

$ sudo -i
# NAME='secure_data'
# cryptsetup status "$NAME"
# printf 'resume command: cryptsetup luksResume %s\n' "$NAME"
resume command: cryptsetup luksResume secure_data

The status output is host-specific. It should describe the mapping you intend to touch. Keep the resume command available in the same root shell or on a separate administration console. If the mapping uses a detached header, record the corresponding header argument for the resume command as well.

Do not use --batch-mode to make this safer. That option suppresses confirmation questions, and the manpage warns that it must be used with care. There is no useful confirmation prompt that can compensate for choosing the wrong mapping.

4. Suspend the mapping

Warning: This command changes live device state. All I/O to the mapping blocks and accesses wait indefinitely until you resume or close it. Run it only as root, after stopping or quiescing services that use the mapping:

# cryptsetup luksSuspend "$NAME"

A successful command normally returns to the prompt without a success message. The operation freezes I/O and wipes the encryption key from kernel memory. It does not erase plaintext that may still be present in filesystem caches or in-kernel filesystem metadata. Suspending is therefore a narrow key-removal measure, not a guarantee that no readable data remains in memory.

Checkpoint: Do not run ordinary commands that read or write the suspended filesystem. They can hang, and a hung shell or service is not evidence that the command failed. Keep the recovery console usable.

5. Resume and verify access

When the maintenance action is complete, restore the key and unblock the mapping. This command is also privileged:

# cryptsetup luksResume "$NAME"
# cryptsetup status "$NAME"
# findmnt -rn -S "/dev/mapper/$NAME"

luksResume reinstates the key and unblocks the device. It may ask for the passphrase, depending on the available tokens and the options used when the mapping was created. A successful cryptsetup status result and a normal findmnt result are useful checkpoints, but also check the application that owns the data before declaring the maintenance complete.

If you used a detached header, supply the same --header HEADER value when resuming:

# cryptsetup luksResume --header /path/to/HEADER "$NAME"

Use a real absolute path in place of /path/to/HEADER. Do not put a passphrase directly in the command line. A key file, if your approved recovery design uses one, should be handled according to that design rather than copied into shell history.

6. Close instead of resuming only when you mean to remove the mapping

If the mapping should not return, the documented alternative is cryptsetup close NAME. Closing removes the device-mapper mapping rather than restoring normal I/O:

# cryptsetup close "$NAME"
# cryptsetup status "$NAME"
Device secure_data is inactive.

Only use this branch after stopping users of the mapping and confirming that you intend to unmount or dismantle it. Closing is not an undo for a mistaken target. If you need the mapping again later, you must reopen it using your normal LUKS procedure and credentials.

Common failure traps

Done means