integritysetup(8)

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

NAME

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

SYNOPSIS

9       integritysetup <options> <action> <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       additional data integrity field per-sector. You can use this additional
18       field  directly with integritysetup utility, or indirectly (for authen‐
19       ticated encryption) through cryptsetup.
20
21       Integritysetup supports these operations:
22
23       format <device>
24
25              Formats <device> (calculates space and  dm-integrity  superblock
26              and wipes the device).
27
28              <options>   can   be  [--data-device,  --batch-mode,  --no-wipe,
29              --journal-size, --interleave-sectors,  --tag-size,  --integrity,
30              --integrity-key-size,    --integrity-key-file,    --sector-size,
31              --progress-frequency]
32
33
34       open <device> <name>
35       create <name> <device> (OBSOLETE syntax)
36
37              Open a mapping with <name> backed by device <device>.
38
39              <options> can be [--data-device, --batch-mode,  --journal-water‐
40              mark,   --journal-commit-time,   --buffer-sectors,  --integrity,
41              --integrity-key-size, --integrity-key-file, --integrity-no-jour‐
42              nal, --integrity-recalculate, --integrity-recovery-mode]
43
44
45       close <name>
46
47              Removes existing mapping <name>.
48
49              For  backward  compatibility,  there is remove command alias for
50              the close command.
51
52       status <name>
53
54              Reports status for the active integrity mapping <name>.
55
56       dump <device>
57
58              Reports parameters from on-disk stored superblock.
59
60

OPTIONS

62       --verbose, -v
63              Print more information on command execution.
64
65       --debug
66              Run in debug mode with full diagnostic logs. Debug output  lines
67              are always prefixed by '#'.
68
69       --version
70              Show the program version.
71
72       --batch-mode
73              Do not ask for confirmation.
74
75       --progress-frequency <seconds>
76              Print separate line every <seconds> with wipe progress.
77
78       --no-wipe
79              Do  not  wipe the device after format. A device that is not ini‐
80              tially wiped will contain invalid checksums.
81
82       --journal-size, -j BYTES
83              Size of the journal.
84
85       --interleave-sectors SECTORS
86              The number of interleaved sectors.
87
88       --integrity-recalculate
89              Automatically recalculate integrity tags in  kernel  on  activa‐
90              tion.   The device can be used during automatic integrity recal‐
91              culation but becomes fully integrity protected  only  after  the
92              background  operation  is  finished.   This  option is available
93              since the Linux kernel version 4.19.
94
95       --journal-watermark PERCENT
96              Journal watermark in percents. When  the  size  of  the  journal
97              exceeds this watermark, the journal flush will be started.
98
99       --journal-commit-time MS
100              Commit  time  in  milliseconds.  When  this  time passes (and no
101              explicit flush operation was issued), the journal is written.
102
103       --tag-size, -t BYTES
104              Size of the integrity tag per-sector (here the  integrity  func‐
105              tion will store authentication tag).
106
107              NOTE: The size can be smaller that output size of the hash func‐
108              tion, in that case only part of the hash will be stored.
109
110       --data-device
111              Specify a separate data device that contains existing data.  The
112              <device> then will contain calculated integrity tags and journal
113              for this data device.
114
115       --sector-size, -s BYTES
116              Sector size (power of two: 512, 1024, 2048, 4096).
117
118       --buffer-sectors SECTORS
119              The number of sectors in one buffer.
120
121              The tag area is accessed using buffers, the  large  buffer  size
122              means  that the I/O size will be larger, but there could be less
123              I/Os issued.
124
125       --integrity, -I ALGORITHM
126              Use  internal  integrity  calculation  (standalone  mode).   The
127              integrity  algorithm  can be CRC (crc32c/crc32) or hash function
128              (sha1, sha256).
129
130              For HMAC (hmac-sha256) you have also to specify an integrity key
131              and its size.
132
133       --integrity-key-size BYTES
134              The size of the data integrity key.
135
136       --integrity-key-file FILE
137              The file with the integrity key.
138
139       --integrity-no-journal, -D
140              Disable journal for integrity device.
141
142       --integrity-bitmap-mode. -B
143              Use  alternate  bitmap  mode  (available since Linux kernel 5.2)
144              where dm-integrity uses bitmap instead of a journal. If a bit in
145              the  bitmap  is 1, the corresponding region's data and integrity
146              tags are not synchronized - if the machine crashes,  the  unsyn‐
147              chronized  regions  will  be  recalculated.   The bitmap mode is
148              faster than the journal mode, because we don't have to write the
149              data  twice,  but it is also less reliable, because if data cor‐
150              ruption  happens  when  the  machine  crashes,  it  may  not  be
151              detected.
152
153       --bitmap-sectors-per-bit SECTORS
154              Number  of  512-byte  sectors  per bitmap bit, the value must be
155              power of two.
156
157       --bitmap-flush-time MS
158              Bitmap flush time in milliseconds.
159
160
161       WARNING:
162              In case of a crash, it is possible that the data  and  integrity
163              tag doesn't match if the journal is disabled.
164
165       --integrity-recovery-mode. -R
166              Recovery mode (no journal, no tag checking).
167
168
169       NOTE: The following options are intended for testing purposes only.
170              Using  journal encryption does not make sense without encryption
171              the data, these options are  internally  used  in  authenticated
172              disk encryption with cryptsetup(8).
173
174       --journal-integrity ALGORITHM
175              Integrity  algorithm  for  journal area.  See --integrity option
176              for detailed specification.
177
178       --journal-integrity-key-size BYTES
179              The size of the journal integrity key.
180
181       --journal-integrity-key-file FILE
182              The file with the integrity key.
183
184       --journal-crypt ALGORITHM
185              Encryption algorithm for journal data area.  You can use a block
186              cipher  here  such  as  cbc-aes or a stream cipher, for example,
187              chacha20 or ctr-aes.
188
189       --journal-crypt-key-size BYTES
190              The size of the journal encryption key.
191
192       --journal-crypt-key-file FILE
193              The file with the journal encryption key.
194
195       The dm-integrity target is available since Linux kernel version 4.12.
196
197       NOTE:  Format and activation of  an  integrity  device  always  require
198              superuser  privilege  because  the  superblock is calculated and
199              handled in dm-integrity kernel target.
200
201

RETURN CODES

203       Integritysetup returns 0 on success and a non-zero value on error.
204
205       Error codes are:
206           1 wrong parameters
207           2 no permission
208           3 out of memory
209           4 wrong device specified
210           5 device already exists, or device is busy.
211
212

EXAMPLES

214       Format the device with default standalone mode (CRC32C):
215
216       integritysetup format <device>
217
218       Open the device with default parameters:
219
220       integritysetup open <device> test
221
222       Format the device in standalone mode for use with HMAC(SHA256):
223
224       integritysetup format <device> --tag-size  32  --integrity  hmac-sha256
225       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
226
227       Open (activate) the device with HMAC(SHA256) and HMAC key in file:
228
229       integritysetup    open    <device>    test    --integrity   hmac-sha256
230       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
231
232       Dump dm-integrity superblock information:
233
234       integritysetup dump <device>
235
236

REPORTING BUGS

238       Report bugs, including ones in the  documentation,  on  the  cryptsetup
239       mailing  list at <dm-crypt@saout.de> or in the 'Issues' section on LUKS
240       website.  Please attach the output  of  the  failed  command  with  the
241       --debug option added.
242

AUTHORS

244       The  integritysetup tool is written by Milan Broz <gmazyland@gmail.com>
245       and is part of the cryptsetup project.
246

COPYRIGHT

248       Copyright © 2016-2020 Red Hat, Inc.
249       Copyright © 2016-2020 Milan Broz
250
251       This is free software; see the source for copying conditions.  There is
252       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
253       PURPOSE.
254