CRYPTSETUP-REFRESH(8)

✨ CRYPTSETUP-REFRESH ✨

okay bestie, welcome to the cryptsetup-refresh manual page 💅 this is one of the Maintenance Commands in the cryptsetup fam, and honestly? she's a glow-up queen. let's get into it 🫶

---

🌸 NAME 🌸

cryptsetup-refresh — refresh parameters of an active mapping

---

🎀 SYNOPSIS 🎀

cryptsetup refresh [<options>] <name>

---

💖 DESCRIPTION 💖

So basically, this refreshes parameters of an active mapping <name>. Iconic behaviour, no notes.

Update parameters of active device <name> without the need to deactivate the device (and unmount the filesystem). Like, you don't have to take her off the air, she just gets a lil tune-up mid-performance. Currently, it supports parameter refresh on the following devices: LUKS1, LUKS2 (including authenticated encryption), plain crypt and loop-AES. Ate. 💅

Mandatory parameters are identical to those of an open action for the respective device type. fr fr.

You may change the following parameters on all devices: --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue and --allow-discards. ✨

Refreshing the device without any optional parameter will refresh the device with the default setting (respective to device type). i.e. she resets to factory settings, main character energy.

LUKS2 only:

The --integrity-no-journal parameter affects only LUKS2 devices with the underlying dm-integrity device. 🦋

Adding option --persistent stores any combination of device parameters above in LUKS2 metadata (only after successful refresh operation). no cap.

The --disable-keyring parameter refreshes a device with the volume key passed in the dm-crypt driver.

<options> can be [--allow-discards, --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue, --header, --disable-keyring, --disable-locks, --persistent, --integrity-no-journal].

---

🧚 OPTIONS 🧚

• --allow-discards — Allow the use of discard (TRIM) requests for the device. This is also not supported for LUKS2 devices with data integrity protection.

⚠️ WARNING: This command can have a negative security impact because it can make filesystem-level operations visible on the physical device. For example, information leaking filesystem type, used space, etc., may be extractable from the physical device if the discarded blocks can be located later. If in doubt, do not use it. 💀 like, seriously, if you're unsure, just don't.

A kernel version of 3.1 or later is needed. For earlier kernels, this option is ignored.

• --batch-mode, -q — Suppresses all confirmation questions. Use with care! 😭

If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

• --debug or --debug-json — Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by #. 👑

If --debug-json is used, additional LUKS2 JSON data structures are printed. fancyyy.

• --disable-keyring — Do not load the volume key in the kernel keyring; store it directly in the dm-crypt target instead. This option is supported only for the LUKS2 type.
• --disable-locks — Disable lock protection for metadata on disk. This option is valid only for LUKS2 and is ignored for other formats.

⚠️ WARNING: Do not use this option unless you run cryptsetup in a restricted environment where locking is impossible to perform (where /run directory cannot be used).

• --header <device or file storing the LUKS header> — Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. separation slay ✨

For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

• --help, -? — Show help text and default parameters. 🫶
• --integrity-no-journal — Activate device with integrity protection without using data journal (direct write of data and integrity tags). Note that without a journal, a power failure can cause non-atomic writes and data corruption. Use only if journaling is performed on a different storage layer. 🫠 yeah that's a real one, be careful bestie.
• --perf-high_priority — Set dm-crypt workqueues and the writer thread to high priority. This improves throughput and latency of dm-crypt while degrading the general responsiveness of the system.

This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. Needs kernel 6.10 or later.

• --perf-no_read_workqueue, --perf-no_write_workqueue — Bypass dm-crypt internal workqueue and process read or write requests synchronously.

These options are available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. Needs kernel 5.9 or later.

• --perf-same_cpu_crypt — Perform encryption using the same CPU on which that IO was submitted. The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs. balance, periodt 💅

This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.

• --perf-submit_from_crypt_cpus — Disable offloading writes to a separate thread after encryption. There are some situations where offloading write bios from the encryption threads to a single thread degrades performance significantly. The default is to offload write bios to the same thread.

This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.

• --persistent — If used with LUKS2 devices and activation commands like open or refresh, the specified activation flags are persistently written into metadata and used next time automatically, even for normal activation. (No need to use cryptab or other system configuration files.) set it and forget it, queen 👑

If you need to remove a persistent flag, use --persistent without the flag you want to remove (e.g., to disable the persistently stored discard flag, use --persistent without --allow-discards).

Only --allow-discards, --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue and --integrity-no-journal can be stored persistently.

• --usage — Show short option help.
• --version, -V — Show the program version.

---

🙈 REPORTING BUGS 🙈

Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added. (yes literally add --debug, it helps so much, iykyk 💜)

---

🌈 SEE ALSO 🌈

Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

---

👑 CRYPTSETUP 👑

Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.

---

and that's the whole page bestie, you ate that 💅✨ this was cryptsetup version 2.8.8, dated 2026-09-07 — go forth and refresh ur mappings responsibly 🎀🦋💖