1INTEGRITYSETUP(8)            Maintenance Commands            INTEGRITYSETUP(8)
2
3
4

NAME

6       integritysetup - manage dm-integrity (block level integrity) volumes
7

SYNOPSIS

9       integritysetup <action> [<options>] <action args>
10

DESCRIPTION

12       Integritysetup is used to configure dm-integrity managed device-mapper
13       mappings.
14
15       Device-mapper integrity target provides read-write transparent
16       integrity checking of block devices. The dm-integrity target emulates
17       an additional data integrity field per-sector. You can use this
18       additional field directly with integritysetup utility, or indirectly
19       (for authenticated encryption) through cryptsetup.
20

BASIC ACTIONS

22       Integritysetup supports these operations:
23
24   FORMAT
25       format <device>
26
27       Formats <device> (calculates space and dm-integrity superblock and
28       wipes the device).
29
30       <options> can be [--data-device, --batch-mode, --no-wipe,
31       --journal-size, --interleave-sectors, --tag-size, --integrity,
32       --integrity-key-size, --integrity-key-file, --sector-size,
33       --progress-frequency, --progress-json].
34
35   OPEN
36       open <device> <name>
37       create <name> <device> (OBSOLETE syntax)
38
39       Open a mapping with <name> backed by device <device>.
40
41       <options> can be [--data-device, --batch-mode, --journal-watermark,
42       --journal-commit-time, --buffer-sectors, --integrity,
43       --integrity-key-size, --integrity-key-file, --integrity-no-journal,
44       --integrity-recalculate,
45       --integrity-recalculate-reset,--integrity-recovery-mode,
46       --allow-discards].
47
48   CLOSE
49       close <name>
50       remove <name> (OBSOLETE syntax)
51
52       Removes existing mapping <name>.
53
54       <options> can be [--deferred] or [--cancel-deferred]
55
56   STATUS
57       status <name>
58
59       Reports status for the active integrity mapping <name>.
60
61   DUMP
62       dump <device>
63
64       Reports parameters from on-disk stored superblock.
65
66   RESIZE
67       resize <name>
68
69       Resizes an active mapping <name>.
70
71       If --size (in 512-bytes sectors) or --device-size are not specified,
72       the size is computed from the underlying device. After resize, the
73       recalculating flag is set. If --wipe flag is set and the size of the
74       device is increased, the newly added section will be wiped.
75
76       Increasing the size of integrity volumes is available since the Linux
77       kernel version 5.7, shrinking should work on older kernels too.
78
79       <options> can be [--size, --device-size, --wipe].
80

OPTIONS

82       --progress-frequency <seconds>
83           Print separate line every <seconds> with wipe progress.
84
85       --progress-json
86           Prints wipe progress data in json format suitable mostly for
87           machine processing. It prints separate line every half second (or
88           based on --progress-frequency value). The JSON output looks as
89           follows during wipe progress (except it’s compact single line):
90
91               {
92                 "device":"/dev/sda"       // backing device or file
93                 "device_bytes":"8192",    // bytes wiped so far
94                 "device_size":"44040192", // total bytes to wipe
95                 "speed":"126877696",      // calculated speed in bytes per second (based on progress so far)
96                 "eta_ms":"2520012"        // estimated time to finish wipe in milliseconds
97                 "time_ms":"5561235"       // total time spent wiping device in milliseconds
98               }
99
100           Note on numbers in JSON output: Due to JSON parsers limitations all
101           numbers are represented in a string format due to need of full
102           64bit unsigned integers.
103
104       --no-wipe
105           Do not wipe the device after format. A device that is not initially
106           wiped will contain invalid checksums.
107
108       --wipe
109           Wipe the newly allocated area after resize to bigger size. If this
110           flag is not set, checksums will be calculated for the data
111           previously stored in the newly allocated area.
112
113       --journal-size, -j BYTES
114           Size of the journal.
115
116       --interleave-sectors SECTORS
117           The number of interleaved sectors.
118
119       --integrity-recalculate
120           Automatically recalculate integrity tags in kernel on activation.
121           The device can be used during automatic integrity recalculation but
122           becomes fully integrity protected only after the background
123           operation is finished. This option is available since the Linux
124           kernel version 4.19.
125
126       --integrity-recalculate-reset
127           Restart recalculation from the beginning of the device. It can be
128           used to change the integrity checksum function. Note it does not
129           change the tag length. This option is available since the Linux
130           kernel version 5.13.
131
132       --journal-watermark PERCENT
133           Journal watermark in percents. When the size of the journal exceeds
134           this watermark, the journal flush will be started.
135
136       --journal-commit-time MS
137           Commit time in milliseconds. When this time passes (and no explicit
138           flush operation was issued), the journal is written.
139
140       --tag-size, -t BYTES
141           Size of the integrity tag per-sector (here the integrity function
142           will store authentication tag).
143
144           NOTE: The size can be smaller that output size of the hash
145           function, in that case only part of the hash will be stored.
146
147       --data-device <data_device>
148           Specify a separate data device that contains existing data. The
149           <device> then will contain calculated integrity tags and journal
150           for data on <data_device>.
151
152           NOTE: To not wipe the data device after initial format, also
153           specify --no-wipe option and activate with --integrity-recalculate
154           to automatically recalculate integrity tags.
155
156       --sector-size, -s BYTES
157           Sector size (power of two: 512, 1024, 2048, 4096).
158
159       --buffer-sectors SECTORS
160           The number of sectors in one buffer.
161
162           The tag area is accessed using buffers, the large buffer size means
163           that the I/O size will be larger, but there could be less I/Os
164           issued.
165
166       --integrity, -I ALGORITHM
167           Use internal integrity calculation (standalone mode). The integrity
168           algorithm can be CRC (crc32c/crc32), non-cryptographic hash
169           function (xxhash64) or hash function (sha1, sha256).
170
171           For HMAC (hmac-sha256) you have also to specify an integrity key
172           and its size.
173
174       --integrity-key-size BYTES
175           The size of the data integrity key. Maximum is 4096 bytes.
176
177       --integrity-key-file FILE
178           The file with the integrity key.
179
180       --integrity-no-journal, -D
181           Disable journal for integrity device.
182
183       --integrity-bitmap-mode. -B
184           Use alternate bitmap mode (available since Linux kernel 5.2) where
185           dm-integrity uses bitmap instead of a journal. If a bit in the
186           bitmap is 1, the corresponding region’s data and integrity tags are
187           not synchronized - if the machine crashes, the unsynchronized
188           regions will be recalculated. The bitmap mode is faster than the
189           journal mode, because we don’t have to write the data twice, but it
190           is also less reliable, because if data corruption happens when the
191           machine crashes, it may not be detected.
192
193       --bitmap-sectors-per-bit SECTORS
194           Number of 512-byte sectors per bitmap bit, the value must be power
195           of two.
196
197       --bitmap-flush-time MS
198           Bitmap flush time in milliseconds.
199
200       WARNING:
201           In case of a crash, it is possible that the data and integrity tag
202           doesn’t match if the journal is disabled.
203
204       --integrity-recovery-mode. -R
205           Recovery mode (no journal, no tag checking).
206
207       NOTE: The following options are intended for testing purposes only.:
208       Using journal encryption does not make sense without encryption the
209       data, these options are internally used in authenticated disk
210       encryption with cryptsetup(8).
211
212       --journal-integrity ALGORITHM
213           Integrity algorithm for journal area. See --integrity option for
214           detailed specification.
215
216       --journal-integrity-key-size BYTES
217           The size of the journal integrity key. Maximum is 4096 bytes.
218
219       --journal-integrity-key-file FILE
220           The file with the integrity key.
221
222       --journal-crypt ALGORITHM
223           Encryption algorithm for journal data area. You can use a block
224           cipher here such as cbc-aes or a stream cipher, for example,
225           chacha20 or ctr-aes.
226
227       --journal-crypt-key-size BYTES
228           The size of the journal encryption key. Maximum is 4096 bytes.
229
230       --journal-crypt-key-file FILE
231           The file with the journal encryption key.
232
233       --allow-discards
234           Allow the use of discard (TRIM) requests for the device. This
235           option is available since the Linux kernel version 5.7.
236
237       --deferred
238           Defers device removal in close command until the last user closes
239           it.
240
241       --cancel-deferred
242           Removes a previously configured deferred device removal in close
243           command.
244
245       --verbose, -v
246           Print more information on command execution.
247
248       --debug
249           Run in debug mode with full diagnostic logs. Debug output lines are
250           always prefixed by #.
251
252       --version, -V
253           Show the program version.
254
255       --batch-mode, -q
256           Do not ask for confirmation.
257
258       --usage
259           Show short option help.
260
261       --help, -?
262           Show help text and default parameters.
263

LEGACY COMPATIBILITY OPTIONS

265       WARNING:
266           Do not use these options until you need compatibility with specific
267           old kernel.
268
269       --integrity-legacy-padding
270           Use inefficient legacy padding.
271
272       --integrity-legacy-hmac
273           Use old flawed HMAC calculation (also does not protect superblock).
274
275       --integrity-legacy-recalculate
276           Allow insecure recalculating of volumes with HMAC keys
277           (recalculation offset in superblock is not protected).
278

RETURN CODES

280       Integritysetup returns 0 on success and a non-zero value on error.
281
282       Error codes are: 1 wrong parameters, 2 no permission, 3 out of memory,
283       4 wrong device specified, 5 device already exists or device is busy.
284

NOTES

286       The dm-integrity target is available since Linux kernel version 4.12.
287
288       Format and activation of an integrity device always require superuser
289       privilege because the superblock is calculated and handled in
290       dm-integrity kernel target.
291

EXAMPLES

293       Format the device with default standalone mode (CRC32C):
294
295       integritysetup format <device>
296
297       Open the device with default parameters:
298
299       integritysetup open <device> test
300
301       Format the device in standalone mode for use with HMAC(SHA256):
302
303       integritysetup format <device> --tag-size 32 --integrity hmac-sha256
304       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
305
306       Open (activate) the device with HMAC(SHA256) and HMAC key in file:
307
308       integritysetup open <device> test --integrity hmac-sha256
309       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
310
311       Dump dm-integrity superblock information:
312
313       integritysetup dump <device>
314

DM-INTEGRITY ON-DISK FORMAT

316       The on-disk format specification available at DMIntegrity
317       <https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity> page.
318

AUTHORS

320       The integritysetup tool is written by Milan Broz <gmazyland@gmail.com>.
321

REPORTING BUGS

323       Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
324       in Issues project section
325       <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
326
327       Please attach output of the failed command with --debug option added.
328

SEE ALSO

330       Cryptsetup FAQ
331       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
332
333       cryptsetup(8), integritysetup(8) and veritysetup(8)
334

CRYPTSETUP

336       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
337
338
339
340integritysetup 2.6.1              2023-07-19                 INTEGRITYSETUP(8)
Impressum