Tune a Live Mapping with cryptsetup refresh

cryptsetup refresh changes supported settings on an active dm-crypt mapping without unmounting the filesystem or dropping the mapping. Use it to enable discard or apply a performance tweak mid-maintenance, with no outage needed. 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.

The route

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

1. Confirm the command and target mapping
2. Pick one supported parameter
3. Check the result, do not guess from silence
4. Make an activation flag persistent only on purpose
5. Handle detached headers and specialised options with care
6. Recover from a bad result

Warning

Refreshing an active mapping changes how live I/O is handled. Test the exact option on a non-critical mapping first, and have a maintenance window and a rollback decision before touching production storage. Inspection commands can run unprivileged; the refresh itself normally needs root.

1. Confirm the command and target mapping

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

$ 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. Pick the name shown under /dev/mapper, such as cryptdata, not a LUKS UUID, a mount point or the source block device. Checking it changes nothing:

$ cryptsetup status cryptdata

Checkpoint

You have an active mapping name and know which filesystem or service uses it. Stop here if the name is missing or it is not the mapping you intended.

2. Pick one supported parameter

cryptsetup refresh can change --allow-discards and a handful of low-level dm-crypt performance settings on LUKS1, LUKS2, plain crypt and loop-AES mappings:

CPU affinity: --perf-same_cpu_crypt and --perf-submit_from_crypt_cpus control which CPU handles crypto work.
Workqueue bypass: --perf-no_read_workqueue and --perf-no_write_workqueue skip the internal read or write workqueue.
Integrity journal: --integrity-no-journal is LUKS2-only, for a mapping using a dm-integrity device.

Start with the smallest change. Enabling discard is common on thin storage or SSD-backed systems:

$ sudo cryptsetup refresh --allow-discards cryptdata

This is a live change: it does not reformat the device or unmount the filesystem. But discard requests can reveal filesystem-level information, such as used-space patterns, on the physical storage. Do not flip it on just because the backing device happens to be an SSD; check your threat model first.

The performance flags are tuning controls, not general speed switches. This one asks dm-crypt to process reads synchronously instead of through its internal read workqueue:

$ sudo cryptsetup refresh --perf-no_read_workqueue cryptdata

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

3. Check the result, do not guess from silence

A successful refresh usually prints nothing useful. Check the exit status immediately, then inspect the mapping with device-mapper tools:

$ 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

A zero exit status is not proof 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 stay in its previous state, but confirm the service is still healthy before retrying.

4. Make an activation flag persistent only on purpose

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

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

The metadata write only happens after a successful refresh. Do not add this option merely to make today's test convenient: it is a separate decision from a one-off live change. Only discard, the four performance options and --integrity-no-journal can be stored persistently.

To remove a persisted flag, use --persistent without that flag. This removes the persistent discard setting while refreshing the mapping with the remaining defaults:

$ sudo cryptsetup refresh --persistent cryptdata

Warning

That command is not a harmless read-only check. It can alter both the live mapping and LUKS2 metadata. Record the prior setting, and verify the next activation with a controlled reboot or service restart.

5. Handle detached headers and specialised options with care

If the mapping uses a detached LUKS header, give the refresh the same header device or file:

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

Replace the placeholder with the real header location, and protect it like other LUKS metadata. Never put a secret key or passphrase on the command line.

Key location: --disable-keyring is LUKS2-only, keeping the volume key in the dm-crypt target rather than the kernel keyring.
Restricted environments: --disable-locks is for setups where the normal lock directory is unusable, not a routine fix for a lock error.
Journal trade-off: --integrity-no-journal risks non-atomic writes and corruption on power loss unless another storage layer journals. 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, refresh again with the setting left out to return to the device type's default:

$ sudo cryptsetup refresh cryptdata

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

If cryptsetup reports the mapping is missing, re-check /dev/mapper and the exact name. A permission or device-mapper error means checking root access, kernel support and the system journal. Testing against a made-up name can fail before cryptsetup even inspects the mapping, so that failure proves nothing about a real refresh.

Done means

Correct mapping confirmed: you recorded the active /dev/mapper name and checked it before changing anything.
One parameter, one reason: you picked a single supported parameter for a documented operational reason.
Result checked, not assumed: the refresh returned status 0 and you checked mapping and workload health afterwards.
Security-aware: you treated --allow-discards, --persistent and --integrity-no-journal as security or data-integrity decisions, not defaults.
Rollback understood: you know how to drop a transient flag, and how to remove a persistent one with a separate controlled refresh.