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

NAME

6       veritysetup - manage dm-verity (block level verification) volumes
7

SYNOPSIS

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

DESCRIPTION

12       Veritysetup is used to configure dm-verity managed device-mapper
13       mappings.
14
15       Device-mapper verity target provides read-only transparent integrity
16       checking of block devices using kernel crypto API.
17
18       The dm-verity devices are always read-only.
19

BASIC ACTIONS

21       Veritysetup supports these operations:
22
23   FORMAT
24       format <data_device> <hash_device>
25
26       Calculates and permanently stores hash verification data for
27       data_device. Hash area can be located on the same device after data if
28       specified by --hash-offset option.
29
30       Note you need to provide root hash string for device verification or
31       activation. Root hash must be trusted.
32
33       The data or hash device argument can be block device or file image. If
34       hash device path doesn’t exist, it will be created as file.
35
36       <options> can be [--hash, --no-superblock, --format, --data-block-size,
37       --hash-block-size, --data-blocks, --hash-offset, --salt, --uuid,
38       --root-hash-file].
39
40       If option --root-hash-file is used, the root hash is stored in
41       hex-encoded text format in <path>.
42
43   OPEN
44       open <data_device> <name> <hash_device> <root_hash>
45       open <data_device> <name> <hash_device> --root-hash-file <path>
46       create <name> <data_device> <hash_device> <root_hash> (OBSOLETE syntax)
47
48       Creates a mapping with <name> backed by device <data_device> and using
49       <hash_device> for in-kernel verification.
50
51       The <root_hash> is a hexadecimal string.
52
53       <options> can be [--hash-offset, --no-superblock, --ignore-corruption
54       or --restart-on-corruption, --panic-on-corruption,
55       --ignore-zero-blocks, --check-at-most-once, --root-hash-signature,
56       --root-hash-file, --use-tasklets].
57
58       If option --root-hash-file is used, the root hash is read from <path>
59       instead of from the command line parameter. Expects hex-encoded text,
60       without terminating newline.
61
62       If option --no-superblock is used, you have to use as the same options
63       as in initial format operation.
64
65   VERIFY
66       verify <data_device> <hash_device> <root_hash>
67       verify <data_device> <hash_device> --root-hash-file <path>
68
69       Verifies data on data_device with use of hash blocks stored on
70       hash_device.
71
72       This command performs userspace verification, no kernel device is
73       created.
74
75       The <root_hash> is a hexadecimal string.
76
77       If option --root-hash-file is used, the root hash is read from <path>
78       instead of from the command line parameter. Expects hex-encoded text,
79       without terminating newline.
80
81       <options> can be [--hash-offset, --no-superblock, --root-hash-file].
82
83       If option --no-superblock is used, you have to use as the same options
84       as in initial format operation.
85
86   CLOSE
87       close <name>
88       remove <name> (OBSOLETE syntax)
89
90       Removes existing mapping <name>.
91
92       <options> can be [--deferred] or [--cancel-deferred].
93
94   STATUS
95       status <name>
96
97       Reports status for the active verity mapping <name>.
98
99   DUMP
100       dump <hash_device>
101
102       Reports parameters of verity device from on-disk stored superblock.
103
104       <options> can be [--hash-offset].
105

OPTIONS

107       --no-superblock
108           Create or use dm-verity without permanent on-disk superblock.
109
110       --format=number
111           Specifies the hash version type. Format type 0 is original Chrome
112           OS version. Format type 1 is current version.
113
114       --data-block-size=bytes
115           Used block size for the data device. (Note kernel supports only
116           page-size as maximum here.)
117
118       --hash-block-size=bytes
119           Used block size for the hash device. (Note kernel supports only
120           page-size as maximum here.)
121
122       --data-blocks=blocks
123           Size of data device used in verification. If not specified, the
124           whole device is used.
125
126       --hash-offset=bytes
127           Offset of hash area/superblock on hash_device. Value must be
128           aligned to disk sector offset.
129
130       --salt=hex string
131           Salt used for format or verification. Format is a hexadecimal
132           string.
133
134       --uuid=UUID
135           Use the provided UUID for format command instead of generating new
136           one.
137
138           The UUID must be provided in standard UUID format, e.g.
139           12345678-1234-1234-1234-123456789abc. *--ignore-corruption ,
140           --restart-on-corruption ,
141
142       --panic-on-corruption*
143           Defines what to do if data integrity problem is detected (data
144           corruption).
145
146           Without these options kernel fails the IO operation with I/O error.
147           With --ignore-corruption option the corruption is only logged. With
148           --restart-on-corruption or --panic-on-corruption the kernel is
149           restarted (panicked) immediately. (You have to provide way how to
150           avoid restart loops.)
151
152           WARNING: Use these options only for very specific cases. These
153           options are available since Linux kernel version 4.1.
154
155       --ignore-zero-blocks
156           Instruct kernel to not verify blocks that are expected to contain
157           zeroes and always directly return zeroes instead.
158
159           WARNING: Use this option only in very specific cases. This option
160           is available since Linux kernel version 4.5.
161
162       --check-at-most-once
163           Instruct kernel to verify blocks only the first time they are read
164           from the data device, rather than every time.
165
166           WARNING: It provides a reduced level of security because only
167           offline tampering of the data device’s content will be detected,
168           not online tampering. This option is available since Linux kernel
169           version 4.17.
170
171       --hash=hash
172           Hash algorithm for dm-verity. For default see --help option.
173
174       --fec-device=fec_device
175           Use forward error correction (FEC) to recover from corruption if
176           hash verification fails. Use encoding data from the specified
177           device.
178
179           The fec device argument can be block device or file image. For
180           format, if fec device path doesn’t exist, it will be created as
181           file.
182
183           Block sizes for data and hash devices must match. Also, if the
184           verity data_device is encrypted the fec_device should be too.
185
186           FEC calculation covers data, hash area, and optional foreign
187           metadata stored on the same device with the hash tree (additional
188           space after hash area). Size of this optional additional area
189           protected by FEC is calculated from image sizes, so you must be
190           sure that you use the same images for activation.
191
192           If the hash device is in a separate image, metadata covers the
193           whole rest of the image after the hash area.
194
195           If hash and FEC device is in the image, metadata ends on the FEC
196           area offset.
197
198       --fec-offset=bytes
199           This is the offset, in bytes, from the start of the FEC device to
200           the beginning of the encoding data.
201
202       --fec-roots=num
203           Number of generator roots. This equals to the number of parity
204           bytes in the encoding data. In RS(M, N) encoding, the number of
205           roots is M-N. M is 255 and M-N is between 2 and 24 (including).
206
207       --root-hash-file=FILE
208           Path to file with stored root hash in hex-encoded text.
209
210       --root-hash-signature=FILE
211           Path to root hash signature file used to verify the root hash (in
212           kernel). This feature requires Linux kernel version 5.4 or more
213           recent.
214
215       --use-tasklets
216           Try to use kernel tasklets in dm-verity driver for performance
217           reasons. This option is available since Linux kernel version 6.0.
218
219       --deferred
220           Defers device removal in close command until the last user closes
221           it.
222
223       --cancel-deferred
224           Removes a previously configured deferred device removal in close
225           command.
226
227       --verbose, -v
228           Print more information on command execution.
229
230       --debug
231           Run in debug mode with full diagnostic logs. Debug output lines are
232           always prefixed by #.
233
234       --version, -V
235           Show the program version.
236
237       --batch-mode, -q
238           Do not ask for confirmation.
239
240       --usage
241           Show short option help.
242
243       --help, -?
244           Show help text and default parameters.
245

RETURN CODES

247       Veritysetup returns 0 on success and a non-zero value on error.
248
249       Error codes are: 1 wrong parameters, 2 no permission, 3 out of memory,
250       4 wrong device specified, 5 device already exists or device is busy.
251

EXAMPLES

253       veritysetup --data-blocks=256 format <data_device> <hash_device>
254
255       Calculates and stores verification data on hash_device for the first
256       256 blocks (of block-size). If hash_device does not exist, it is
257       created (as file image).
258
259       veritysetup format --root-hash-file <path> <data_device> <hash_device>
260
261       Calculates and stores verification data on hash_device for the whole
262       data_device, and store the root hash as hex-encoded text in <path>.
263
264       veritysetup --data-blocks=256 --hash-offset=1052672 format <device>
265       <device>
266
267       Verification data (hashes) is stored on the same device as data
268       (starting at hash-offset). Hash-offset must be greater than number of
269       blocks in data-area.
270
271       veritysetup --data-blocks=256 --hash-offset=1052672 create test-device
272       <device> <device> <root_hash>
273
274       Activates the verity device named test-device. Options --data-blocks
275       and --hash-offset are the same as in the format command. The
276       <root_hash> was calculated in format command.
277
278       veritysetup --data-blocks=256 --hash-offset=1052672 verify
279       <data_device> <hash_device> <root_hash>
280
281       Verifies device without activation (in userspace).
282
283       veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file
284       <path> verify <data_device> <hash_device>
285
286       Verifies device without activation (in userspace). Root hash passed via
287       a file rather than inline.
288
289       veritysetup --fec-device=<fec_device> --fec-roots=10 format
290       <data_device> <hash_device>
291
292       Calculates and stores verification and encoding data for data_device.
293

DM-VERITY ON-DISK SPECIFICATION

295       The on-disk format specification is available at DMVerity
296       <https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity> page.
297

AUTHORS

299       The first implementation of veritysetup was written by Chrome OS
300       authors.
301
302       This version is based on verification code written by Mikulas Patocka
303       <mpatocka@redhat.com> and rewritten for libcryptsetup by Milan Broz
304       <gmazyland@gmail.com>.
305

REPORTING BUGS

307       Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
308       in Issues project section
309       <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
310
311       Please attach output of the failed command with --debug option added.
312

SEE ALSO

314       Cryptsetup FAQ
315       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
316
317       cryptsetup(8), integritysetup(8) and veritysetup(8)
318

CRYPTSETUP

320       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
321
322
323
324veritysetup 2.6.1                 2023-07-19                    VERITYSETUP(8)
Impressum