1CRYPTSETUP-REFRESH(8)        Maintenance Commands        CRYPTSETUP-REFRESH(8)
2
3
4

NAME

6       cryptsetup-refresh - refresh parameters of an active mapping
7

SYNOPSIS

9       cryptsetup refresh [<options>] <name>
10

DESCRIPTION

12       Refreshes parameters of active mapping <name>.
13
14       Updates parameters of active device <name> without the need to
15       deactivate the device (and umount filesystem). Currently, it supports
16       parameters refresh on following devices: LUKS1, LUKS2 (including
17       authenticated encryption), plain crypt and loop-AES.
18
19       Mandatory parameters are identical to those of an open action for the
20       respective device type.
21
22       You may change following parameters on all devices
23       --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus,
24       --perf-no_read_workqueue, --perf-no_write_workqueue and
25       --allow-discards.
26
27       Refreshing the device without any optional parameter will refresh the
28       device with default setting (respective to device type).
29
30       LUKS2 only:
31
32       The --integrity-no-journal parameter affects only LUKS2 devices with
33       the underlying dm-integrity device.
34
35       Adding option --persistent stores any combination of device parameters
36       above in LUKS2 metadata (only after successful refresh operation).
37
38       The --disable-keyring parameter refreshes a device with volume key
39       passed in dm-crypt driver.
40
41       <options> can be [--allow-discards, --perf-same_cpu_crypt,
42       --perf-submit_from_crypt_cpus, --perf-no_read_workqueue,
43       --perf-no_write_workqueue, --header, --disable-keyring,
44       --disable-locks, --persistent, --integrity-no-journal].
45

OPTIONS

47       --allow-discards
48           Allow the use of discard (TRIM) requests for the device. This is
49           also not supported for LUKS2 devices with data integrity
50           protection.
51
52           WARNING: This command can have a negative security impact because
53           it can make filesystem-level operations visible on the physical
54           device. For example, information leaking filesystem type, used
55           space, etc. may be extractable from the physical device if the
56           discarded blocks can be located later. If in doubt, do not use it.
57
58           A kernel version of 3.1 or later is needed. For earlier kernels,
59           this option is ignored.
60
61       --perf-same_cpu_crypt
62           Perform encryption using the same cpu that IO was submitted on. The
63           default is to use an unbound workqueue so that encryption work is
64           automatically balanced between available CPUs.
65
66           NOTE: This option is available only for low-level dm-crypt
67           performance tuning, use only if you need a change to default
68           dm-crypt behaviour. Needs kernel 4.0 or later.
69
70       --perf-submit_from_crypt_cpus
71           Disable offloading writes to a separate thread after encryption.
72           There are some situations where offloading write bios from the
73           encryption threads to a single thread degrades performance
74           significantly. The default is to offload write bios to the same
75           thread.
76
77           NOTE: This option is available only for low-level dm-crypt
78           performance tuning, use only if you need a change to default
79           dm-crypt behaviour. Needs kernel 4.0 or later.
80
81       --perf-no_read_workqueue, --perf-no_write_workqueue
82           Bypass dm-crypt internal workqueue and process read or write
83           requests synchronously.
84
85           NOTE: These options are available only for low-level dm-crypt
86           performance tuning, use only if you need a change to default
87           dm-crypt behaviour. Needs kernel 5.9 or later.
88
89       --header <device or file storing the LUKS header>
90           Use a detached (separated) metadata device or file where the LUKS
91           header is stored. This option allows one to store ciphertext and
92           LUKS header on different devices.
93
94           For commands that change the LUKS header (e.g. luksAddKey), specify
95           the device or file with the LUKS header directly as the LUKS
96           device.
97
98       --disable-locks
99           Disable lock protection for metadata on disk. This option is valid
100           only for LUKS2 and ignored for other formats.
101
102           WARNING: Do not use this option unless you run cryptsetup in a
103           restricted environment where locking is impossible to perform
104           (where /run directory cannot be used).
105
106       --disable-keyring
107           Do not load volume key in kernel keyring and store it directly in
108           the dm-crypt target instead. This option is supported only for the
109           LUKS2 type.
110
111       --persistent
112           If used with LUKS2 devices and activation commands like open or
113           refresh, the specified activation flags are persistently written
114           into metadata and used next time automatically even for normal
115           activation. (No need to use cryptab or other system configuration
116           files.)
117
118           If you need to remove a persistent flag, use --persistent without
119           the flag you want to remove (e.g. to disable persistently stored
120           discard flag, use --persistent without --allow-discards).
121
122           Only --allow-discards, --perf-same_cpu_crypt,
123           --perf-submit_from_crypt_cpus, --perf-no_read_workqueue,
124           --perf-no_write_workqueue and --integrity-no-journal can be stored
125           persistently.
126
127       --integrity-no-journal
128           Activate device with integrity protection without using data
129           journal (direct write of data and integrity tags). Note that
130           without journal power fail can cause non-atomic write and data
131           corruption. Use only if journalling is performed on a different
132           storage layer.
133
134       --batch-mode, -q
135           Suppresses all confirmation questions. Use with care!
136
137           If the --verify-passphrase option is not specified, this option
138           also switches off the passphrase verification.
139
140       --debug or --debug-json
141           Run in debug mode with full diagnostic logs. Debug output lines are
142           always prefixed by #.
143
144           If --debug-json is used, additional LUKS2 JSON data structures are
145           printed.
146
147       --version, -V
148           Show the program version.
149
150       --usage
151           Show short option help.
152
153       --help, -?
154           Show help text and default parameters.
155

REPORTING BUGS

157       Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
158       in Issues project section
159       <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
160
161       Please attach output of the failed command with --debug option added.
162

SEE ALSO

164       Cryptsetup FAQ
165       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
166
167       cryptsetup(8), integritysetup(8) and veritysetup(8)
168

CRYPTSETUP

170       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
171
172
173
174cryptsetup 2.6.1                  2023-07-19             CRYPTSETUP-REFRESH(8)
Impressum