'\" t
.\"     Title: cryptsetup-refresh
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.12
.\"      Date: 2025-06-04
.\"    Manual: Maintenance Commands
.\"    Source: cryptsetup 2.7.2
.\"  Language: English
.\"
.TH "CRYPTSETUP\-REFRESH" "8" "2025-06-04" "cryptsetup 2.7.2" "Maintenance Commands"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
cryptsetup\-refresh \- refresh parameters of an active mapping
.SH "SYNOPSIS"
.sp
\fBcryptsetup \fIrefresh\fP [<options>] <name>\fP
.SH "DESCRIPTION"
.sp
Refreshes parameters of active mapping <name>.
.sp
Updates parameters of active device <name> without the need to deactivate
the device (and umount filesystem). Currently, it supports parameters
refresh on following devices: LUKS1, LUKS2 (including authenticated
encryption), plain crypt and loop\-AES.
.sp
Mandatory parameters are identical to those of an open action for
the respective device type.
.sp
You may change 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.
.sp
Refreshing the device without any optional parameter will refresh the device
with default setting (respective to device type).
.sp
\fBLUKS2 only:\fP
.sp
The \-\-integrity\-no\-journal parameter affects only LUKS2 devices with
the underlying dm\-integrity device.
.sp
Adding option \-\-persistent stores any combination of device parameters
above in LUKS2 metadata (only after successful refresh operation).
.sp
The \-\-disable\-keyring parameter refreshes a device with volume key passed in
dm\-crypt driver.
.sp
\fB<options>\fP 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].
.SH "OPTIONS"
.sp
\fB\-\-allow\-discards\fP
.RS 4
Allow the use of discard (TRIM) requests for the device. This is also not
supported for LUKS2 devices with data integrity protection.
.sp
\fBWARNING:\fP 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.
.sp
A kernel version of 3.1 or later is needed. For earlier kernels, this
option is ignored.
.RE
.sp
\fB\-\-batch\-mode, \-q\fP
.RS 4
Suppresses all confirmation questions. Use with care!
.sp
If the \-\-verify\-passphrase option is not specified, this option also
switches off the passphrase verification.
.RE
.sp
\fB\-\-debug or \-\-debug\-json\fP
.RS 4
Run in debug mode with full diagnostic logs. Debug output lines are
always prefixed by \fB#\fP.
.sp
If \-\-debug\-json is used, additional LUKS2 JSON data structures are printed.
.RE
.sp
\fB\-\-disable\-keyring\fP
.RS 4
Do not load volume key in kernel keyring and store it directly in the
dm\-crypt target instead. This option is supported only for the LUKS2 type.
.RE
.sp
\fB\-\-disable\-locks\fP
.RS 4
Disable lock protection for metadata on disk. This option is valid
only for LUKS2 and ignored for other formats.
.sp
\fBWARNING:\fP 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).
.RE
.sp
\fB\-\-header <device or file storing the LUKS header>\fP
.RS 4
Use a detached (separated) metadata device or file where the LUKS
header is stored. This option allows one to store ciphertext and LUKS
header on different devices.
.sp
For commands that change the LUKS header (e.g. \fIluksAddKey\fP),
specify the device or file with the LUKS header directly as the LUKS
device.
.RE
.sp
\fB\-\-help, \-?\fP
.RS 4
Show help text and default parameters.
.RE
.sp
\fB\-\-integrity\-no\-journal\fP
.RS 4
Activate device with integrity protection without using data journal
(direct write of data and integrity tags). Note that without journal
power fail can cause non\-atomic write and data corruption. Use only if
journalling is performed on a different storage layer.
.RE
.sp
\fB\-\-perf\-no_read_workqueue, \-\-perf\-no_write_workqueue\fP
.RS 4
Bypass dm\-crypt internal workqueue and process read or write requests
synchronously.
.sp
\fBNOTE:\fP These options are available only for low\-level dm\-crypt
performance tuning, use only if you need a change to default dm\-crypt
behaviour. Needs kernel 5.9 or later.
.RE
.sp
\fB\-\-perf\-same_cpu_crypt\fP
.RS 4
Perform encryption using the same cpu that IO was submitted on. The
default is to use an unbound workqueue so that encryption work is
automatically balanced between available CPUs.
.sp
\fBNOTE:\fP This option is available only for low\-level dm\-crypt performance
tuning, use only if you need a change to default dm\-crypt behaviour.
Needs kernel 4.0 or later.
.RE
.sp
\fB\-\-perf\-submit_from_crypt_cpus\fP
.RS 4
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.
.sp
\fBNOTE:\fP This option is available only for low\-level dm\-crypt performance
tuning, use only if you need a change to default dm\-crypt behaviour.
Needs kernel 4.0 or later.
.RE
.sp
\fB\-\-persistent\fP
.RS 4
If used with LUKS2 devices and activation commands like \fIopen\fP or
\fIrefresh\fP, 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.)
.sp
If you need to remove a persistent flag, use \fI\-\-persistent\fP without the
flag you want to remove (e.g. to disable persistently stored discard
flag, use \fI\-\-persistent\fP without \fI\-\-allow\-discards\fP).
.sp
Only \fI\-\-allow\-discards\fP, \fI\-\-perf\-same_cpu_crypt\fP,
\fI\-\-perf\-submit_from_crypt_cpus\fP, \fI\-\-perf\-no_read_workqueue\fP,
\fI\-\-perf\-no_write_workqueue\fP and \fI\-\-integrity\-no\-journal\fP can be stored
persistently.
.RE
.sp
\fB\-\-usage\fP
.RS 4
Show short option help.
.RE
.sp
\fB\-\-version, \-V\fP
.RS 4
Show the program version.
.RE
.SH "REPORTING BUGS"
.sp
Report bugs at \c
.MTO "cryptsetup\(atlists.linux.dev" "\fBcryptsetup mailing list\fP"
or in \c
.URL "https://gitlab.com/cryptsetup/cryptsetup/\-/issues/new" "\fBIssues project section\fP" "."
.sp
Please attach output of the failed command with \-\-debug option added.
.SH "SEE ALSO"
.sp
.URL "https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions" "\fBCryptsetup FAQ\fP" ""
.sp
\fBcryptsetup\fP(8), \fBintegritysetup\fP(8) and \fBveritysetup\fP(8)
.SH "CRYPTSETUP"
.sp
Part of \c
.URL "https://gitlab.com/cryptsetup/cryptsetup/" "\fBcryptsetup project\fP" "."