summaryrefslogtreecommitdiffstats
path: root/man/veritysetup.8.adoc
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man/veritysetup.8.adoc311
1 files changed, 311 insertions, 0 deletions
diff --git a/man/veritysetup.8.adoc b/man/veritysetup.8.adoc
new file mode 100644
index 0000000..36d1501
--- /dev/null
+++ b/man/veritysetup.8.adoc
@@ -0,0 +1,311 @@
+= veritysetup(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: veritysetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+
+== NAME
+
+veritysetup - manage dm-verity (block level verification) volumes
+
+== SYNOPSIS
+
+*veritysetup <action> [<options>] <action args>*
+
+== DESCRIPTION
+
+Veritysetup is used to configure dm-verity managed device-mapper
+mappings.
+
+Device-mapper verity target provides read-only transparent integrity
+checking of block devices using kernel crypto API.
+
+The dm-verity devices are always read-only.
+
+== BASIC ACTIONS
+
+Veritysetup supports these operations:
+
+=== FORMAT
+*format <data_device> <hash_device>*
+
+Calculates and permanently stores hash verification data for
+data_device. Hash area can be located on the same device after data if
+specified by --hash-offset option.
+
+Note you need to provide root hash string for device verification or
+activation. Root hash must be trusted.
+
+The data or hash device argument can be block device or file image. If
+hash device path doesn't exist, it will be created as file.
+
+*<options>* can be [--hash, --no-superblock, --format,
+--data-block-size, --hash-block-size, --data-blocks, --hash-offset,
+--salt, --uuid, --root-hash-file].
+
+If option --root-hash-file is used, the root hash is stored in
+hex-encoded text format in <path>.
+
+=== OPEN
+*open <data_device> <name> <hash_device> <root_hash>* +
+*open <data_device> <name> <hash_device> --root-hash-file <path>* +
+create <name> <data_device> <hash_device> <root_hash> (*OBSOLETE syntax*)
+
+Creates a mapping with <name> backed by device <data_device> and using
+<hash_device> for in-kernel verification.
+
+The <root_hash> is a hexadecimal string.
+
+*<options>* can be [--hash-offset, --no-superblock, --ignore-corruption
+or --restart-on-corruption, --panic-on-corruption, --ignore-zero-blocks,
+--check-at-most-once, --root-hash-signature, --root-hash-file, --use-tasklets].
+
+If option --root-hash-file is used, the root hash is read from <path>
+instead of from the command line parameter. Expects hex-encoded text,
+without terminating newline.
+
+If option --no-superblock is used, you have to use as the same options
+as in initial format operation.
+
+=== VERIFY
+*verify <data_device> <hash_device> <root_hash>* +
+*verify <data_device> <hash_device> --root-hash-file <path>*
+
+Verifies data on data_device with use of hash blocks stored on
+hash_device.
+
+This command performs userspace verification, no kernel device is
+created.
+
+The <root_hash> is a hexadecimal string.
+
+If option --root-hash-file is used, the root hash is read from <path>
+instead of from the command line parameter. Expects hex-encoded text,
+without terminating newline.
+
+*<options>* can be [--hash-offset, --no-superblock, --root-hash-file].
+
+If option --no-superblock is used, you have to use as the same options
+as in initial format operation.
+
+=== CLOSE
+*close <name>* +
+remove <name> (*OBSOLETE syntax*)
+
+Removes existing mapping <name>.
+
+*<options>* can be [--deferred] or [--cancel-deferred].
+
+=== STATUS
+*status <name>*
+
+Reports status for the active verity mapping <name>.
+
+=== DUMP
+*dump <hash_device>*
+
+Reports parameters of verity device from on-disk stored superblock.
+
+*<options>* can be [--hash-offset].
+
+== OPTIONS
+
+*--no-superblock*::
+Create or use dm-verity without permanent on-disk superblock.
+
+*--format=number*::
+Specifies the hash version type. Format type 0 is original Chrome OS
+version. Format type 1 is current version.
+
+*--data-block-size=bytes*::
+Used block size for the data device. (Note kernel supports only
+page-size as maximum here.)
+
+*--hash-block-size=bytes*::
+Used block size for the hash device. (Note kernel supports only
+page-size as maximum here.)
+
+*--data-blocks=blocks*::
+Size of data device used in verification. If not specified, the whole
+device is used.
+
+*--hash-offset=bytes*::
+Offset of hash area/superblock on hash_device. Value must be aligned
+to disk sector offset.
+
+*--salt=hex string*::
+Salt used for format or verification. Format is a hexadecimal string.
+
+*--uuid=UUID*::
+Use the provided UUID for format command instead of generating new
+one.
++
+The UUID must be provided in standard UUID format, e.g.
+12345678-1234-1234-1234-123456789abc.
+*--ignore-corruption , --restart-on-corruption ,
+--panic-on-corruption*::
+Defines what to do if data integrity problem is detected (data
+corruption).
++
+Without these options kernel fails the IO operation with I/O error. With
+--ignore-corruption option the corruption is only logged. With
+--restart-on-corruption or --panic-on-corruption the kernel is restarted
+(panicked) immediately. (You have to provide way how to avoid restart
+loops.)
++
+*WARNING:* Use these options only for very specific cases. These options
+are available since Linux kernel version 4.1.
+
+*--ignore-zero-blocks*::
+Instruct kernel to not verify blocks that are expected to contain
+zeroes and always directly return zeroes instead.
++
+*WARNING:* Use this option only in very specific cases. This option is
+available since Linux kernel version 4.5.
+
+*--check-at-most-once*::
+Instruct kernel to verify blocks only the first time they are read
+from the data device, rather than every time.
++
+*WARNING:* It provides a reduced level of security because only offline
+tampering of the data device's content will be detected, not online
+tampering. This option is available since Linux kernel version 4.17.
+
+*--hash=hash*::
+Hash algorithm for dm-verity. For default see --help option.
+
+*--fec-device=fec_device*::
+Use forward error correction (FEC) to recover from corruption if hash
+verification fails. Use encoding data from the specified device.
++
+The fec device argument can be block device or file image. For format,
+if fec device path doesn't exist, it will be created as file.
++
+Block sizes for data and hash devices must match. Also, if the verity
+data_device is encrypted the fec_device should be too.
++
+FEC calculation covers data, hash area, and optional foreign metadata
+stored on the same device with the hash tree (additional space after
+hash area). Size of this optional additional area protected by FEC is
+calculated from image sizes, so you must be sure that you use the same
+images for activation.
++
+If the hash device is in a separate image, metadata covers the whole
+rest of the image after the hash area.
++
+If hash and FEC device is in the image, metadata ends on the FEC area
+offset.
+
+*--fec-offset=bytes*::
+This is the offset, in bytes, from the start of the FEC device to the
+beginning of the encoding data.
+
+*--fec-roots=num*::
+Number of generator roots. This equals to the number of parity bytes
+in the encoding data. In RS(M, N) encoding, the number of roots is
+M-N. M is 255 and M-N is between 2 and 24 (including).
+
+*--root-hash-file=FILE*::
+Path to file with stored root hash in hex-encoded text.
+
+*--root-hash-signature=FILE*::
+Path to root hash signature file used to verify the root hash (in
+kernel). This feature requires Linux kernel version 5.4 or more
+recent.
+
+*--use-tasklets*::
+Try to use kernel tasklets in dm-verity driver for performance reasons.
+This option is available since Linux kernel version 6.0.
+
+*--deferred*::
+Defers device removal in *close* command until the last user closes
+it.
+
+*--cancel-deferred*::
+Removes a previously configured deferred device removal in *close*
+command.
+
+*--verbose, -v*::
+Print more information on command execution.
+
+*--debug*::
+Run in debug mode with full diagnostic logs. Debug output lines are
+always prefixed by *#*.
+
+*--version, -V*::
+Show the program version.
+
+*--batch-mode, -q*::
+Do not ask for confirmation.
+
+*--usage*::
+Show short option help.
+
+*--help, -?*::
+Show help text and default parameters.
+
+== RETURN CODES
+
+Veritysetup returns *0* on success and a non-zero value on error.
+
+Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory,
+*4* wrong device specified, *5* device already exists or device is busy.
+
+== EXAMPLES
+
+*veritysetup --data-blocks=256 format <data_device> <hash_device>*
+
+Calculates and stores verification data on hash_device for the first 256
+blocks (of block-size). If hash_device does not exist, it is created (as
+file image).
+
+*veritysetup format --root-hash-file <path> <data_device> <hash_device>*
+
+Calculates and stores verification data on hash_device for the whole
+data_device, and store the root hash as hex-encoded text in <path>.
+
+*veritysetup --data-blocks=256 --hash-offset=1052672 format <device>
+<device>*
+
+Verification data (hashes) is stored on the same device as data
+(starting at hash-offset). Hash-offset must be greater than number of
+blocks in data-area.
+
+*veritysetup --data-blocks=256 --hash-offset=1052672 create test-device
+<device> <device> <root_hash>*
+
+Activates the verity device named test-device. Options --data-blocks and
+--hash-offset are the same as in the format command. The <root_hash> was
+calculated in format command.
+
+*veritysetup --data-blocks=256 --hash-offset=1052672 verify
+<data_device> <hash_device> <root_hash>*
+
+Verifies device without activation (in userspace).
+
+*veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file
+<path> verify <data_device> <hash_device>*
+
+Verifies device without activation (in userspace). Root hash passed via
+a file rather than inline.
+
+*veritysetup --fec-device=<fec_device> --fec-roots=10 format
+<data_device> <hash_device>*
+
+Calculates and stores verification and encoding data for data_device.
+
+== DM-VERITY ON-DISK SPECIFICATION
+
+The on-disk format specification is available at
+https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[*DMVerity*] page.
+
+== AUTHORS
+
+The first implementation of veritysetup was written by Chrome OS
+authors.
+
+This version is based on verification code written by
+mailto:mpatocka@redhat.com[Mikulas Patocka] and rewritten for libcryptsetup
+by mailto:gmazyland@gmail.com[Milan Broz].
+
+include::man/common_footer.adoc[]