CRYPTSETUP-REFRESH(8)	     Maintenance Commands	 CRYPTSETUP-REFRESH(8)

NAME
       cryptsetup-refresh - refresh parameters of an active mapping

SYNOPSIS
       cryptsetup refresh [<options>] <name>

DESCRIPTION
       Refreshes parameters of active mapping <name>.

       Update parameters of active device <name> without the need to
       deactivate the device (and unmount the filesystem).  Currently, it
       supports parameter refresh on the following devices: LUKS1, LUKS2
       (including authenticated encryption), plain crypt and loop-AES.

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

       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).

       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).

       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.

	   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.

       --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.

	   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.

       --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.

	   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.)

	   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.

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/>.

cryptsetup 2.8.1		  2025-08-13		 CRYPTSETUP-REFRESH(8)