Refresh an Active dm-crypt Mapping with cryptsetup

You will change supported parameters on an active dm-crypt mapping without unmounting its filesystem or deactivating the mapping. This is useful for enabling discard or applying a dm-crypt performance setting during maintenance. Allow about 10 minutes for a planned change, plus time to verify the workload afterwards. The examples use cryptsetup 2.7.0 from the Ubuntu cryptsetup-bin package.

1. Confirm the command and target mapping

A refresh operates on a device-mapper name, not on the path of the underlying encrypted device. Find the active mapping and record its exact name before doing anything else:

$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ ls /dev/mapper
cryptdata  my-backup
$ lsblk -o NAME,TYPE,FSTYPE,MOUNTPOINTS

Your output will differ. Choose the name shown under /dev/mapper, such as cryptdata. Do not substitute a LUKS UUID, a mount point or the source block device. A mapped name can be checked without changing it:

$ cryptsetup status cryptdata

Checkpoint: you have an active mapping name and have confirmed which filesystem or service uses it. Stop here if the name is absent or the mapping is not the one you intended.

2. Choose one supported parameter

cryptsetup refresh can change --allow-discards and several low-level dm-crypt performance settings on supported LUKS1, LUKS2, plain crypt and loop-AES mappings. The relevant performance options are --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue and --perf-no_write_workqueue. LUKS2 also has --integrity-no-journal for a mapping using a dm-integrity device.

Start with the smallest change. For example, enabling discard is sometimes used by thin storage or SSD-backed systems:

$ sudo cryptsetup refresh --allow-discards cryptdata

This is a live change. It does not reformat the device and it does not unmount the filesystem, but discard requests can reveal filesystem-level information such as used-space patterns on the physical storage. Do not enable it merely because the backing device is an SSD. Check your threat model first.

The performance flags are tuning controls, not general speed switches. For example, this asks dm-crypt to process reads synchronously rather than through its internal read workqueue:

$ sudo cryptsetup refresh --perf-no_read_workqueue cryptdata

Use such a flag only with a measured reason. The manual records kernel requirements for these controls: kernel 4.0 or later for the first two performance options, and kernel 5.9 or later for the workqueue options.

3. Check the result without guessing from silence

A successful refresh normally produces no useful summary. Check the command status immediately, then inspect the mapping with the device-mapper tools available on your system:

$ sudo cryptsetup refresh --allow-discards cryptdata
$ printf 'refresh exit status: %s\n' "$?"
refresh exit status: 0
$ sudo cryptsetup status cryptdata

The status output is mapping-specific and may not print every dm-crypt flag. For a deeper check, inspect the active device-mapper table if dmsetup is installed:

$ sudo dmsetup table cryptdata

Do not treat a command that returned zero as proof that the workload is healthy. Exercise the affected filesystem or service, watch its logs and compare I/O behaviour with your baseline. If the refresh fails, the mapping should remain in its previous state, but confirm that the service is still healthy before retrying.

4. Make a LUKS2 activation flag persistent only deliberately

For a LUKS2 mapping, add --persistent when you want the selected activation flags written to LUKS2 metadata for later normal activation:

$ sudo cryptsetup refresh --allow-discards --persistent cryptdata

The metadata write happens only after a successful refresh. The persistent set is separate from a one-off live change, so do not add this option just to make today's test convenient. Only the documented activation flags can be stored persistently: discard, the four performance options and --integrity-no-journal.

To remove a persistently stored flag, use --persistent without that flag. For example, this removes the persistent discard setting while refreshing the active mapping with the remaining selected defaults:

$ sudo cryptsetup refresh --persistent cryptdata

That command is not a harmless read-only inspection. It can alter both the live mapping and LUKS2 metadata. Keep a record of the prior setting and verify the next activation in a controlled reboot or service restart plan.

5. Handle detached headers and specialised options carefully

If the mapping uses a detached LUKS header, provide the same header device or file when the refresh operation needs it:

$ sudo cryptsetup refresh --header /path/to/luks-header.img cryptdata

Replace the placeholder with the real header location. Protect it like other LUKS metadata and do not put a secret key or passphrase in the command line. --disable-keyring is a LUKS2-only choice that keeps the volume key in the dm-crypt target rather than loading it into the kernel keyring. --disable-locks is intended only for restricted environments where the normal lock directory cannot be used; it is not a routine workaround for a lock error.

--integrity-no-journal has a narrow boundary. Without the integrity journal, a power failure can cause non-atomic writes and data corruption unless journalling is provided at another storage layer. Do not use it as a performance experiment on an ordinary LUKS2 volume.

6. Recover from a bad result

If a performance setting causes trouble, run another refresh with the setting omitted to return to the device type's default setting:

$ sudo cryptsetup refresh cryptdata

For a persistent flag, omission matters: repeat the refresh with --persistent and leave out the flag you want removed. If the filesystem or service is already unhealthy, stop I/O as safely as your operational procedure allows, preserve diagnostics and use the mapping's normal deactivation and reactivation procedure. Do not force a device removal or reboot simply to make the command disappear.

If the command reports that the mapping is missing, re-check /dev/mapper and the exact name. If it reports a permission or device-mapper error, check root access, kernel support and the system journal. A test against a made-up name may fail before cryptsetup can inspect the mapping, so that failure does not validate a real refresh.