diff options
Diffstat (limited to '')
| -rw-r--r-- | man/integritysetup.8.adoc | 334 |
1 files changed, 334 insertions, 0 deletions
diff --git a/man/integritysetup.8.adoc b/man/integritysetup.8.adoc new file mode 100644 index 0000000..2aec1a6 --- /dev/null +++ b/man/integritysetup.8.adoc @@ -0,0 +1,334 @@ += integritysetup(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: integritysetup {release-version} +:man-linkstyle: pass:[blue R < >] + +== NAME + +integritysetup - manage dm-integrity (block level integrity) volumes + +== SYNOPSIS + +*integritysetup <action> [<options>] <action args>* + +== DESCRIPTION + +Integritysetup is used to configure dm-integrity managed device-mapper +mappings. + +Device-mapper integrity target provides read-write transparent integrity +checking of block devices. The dm-integrity target emulates an additional +data integrity field per-sector. You can use this additional field +directly with integritysetup utility, or indirectly (for authenticated +encryption) through cryptsetup. + +== BASIC ACTIONS + +Integritysetup supports these operations: + +=== FORMAT +*format <device>* + +Formats <device> (calculates space and dm-integrity superblock and wipes +the device). + +*<options>* can be [--data-device, --batch-mode, --no-wipe, +--journal-size, --interleave-sectors, --tag-size, --integrity, +--integrity-key-size, --integrity-key-file, --sector-size, +--progress-frequency, --progress-json]. + +=== OPEN +*open <device> <name>* + +create <name> <device> (*OBSOLETE syntax*) + +Open a mapping with <name> backed by device <device>. + +*<options>* can be [--data-device, --batch-mode, --journal-watermark, +--journal-commit-time, --buffer-sectors, --integrity, +--integrity-key-size, --integrity-key-file, --integrity-no-journal, +--integrity-recalculate, +--integrity-recalculate-reset,--integrity-recovery-mode, +--allow-discards]. + +=== 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 integrity mapping <name>. + +=== DUMP +*dump <device>* + +Reports parameters from on-disk stored superblock. + +=== RESIZE +*resize <name>* + +Resizes an active mapping <name>. + +If --size (in 512-bytes sectors) or --device-size are not specified, the +size is computed from the underlying device. After resize, the +*recalculating* flag is set. If --wipe flag is set and the size of the +device is increased, the newly added section will be wiped. + +Increasing the size of integrity volumes is available since the Linux +kernel version 5.7, shrinking should work on older kernels too. + +*<options>* can be [--size, --device-size, --wipe]. + +== OPTIONS +*--progress-frequency <seconds>*:: +Print separate line every <seconds> with wipe progress. + +*--progress-json*:: +Prints wipe progress data in json format suitable mostly for machine +processing. It prints separate line every half second (or based on +--progress-frequency value). The JSON output looks as follows during +wipe progress (except it's compact single line): ++ +.... +{ + "device":"/dev/sda" // backing device or file + "device_bytes":"8192", // bytes wiped so far + "device_size":"44040192", // total bytes to wipe + "speed":"126877696", // calculated speed in bytes per second (based on progress so far) + "eta_ms":"2520012" // estimated time to finish wipe in milliseconds + "time_ms":"5561235" // total time spent wiping device in milliseconds +} +.... ++ +Note on numbers in JSON output: Due to JSON parsers limitations all +numbers are represented in a string format due to need of full 64bit +unsigned integers. + +*--no-wipe*:: +Do not wipe the device after format. A device that is not initially +wiped will contain invalid checksums. + +*--wipe*:: +Wipe the newly allocated area after resize to bigger size. If this +flag is not set, checksums will be calculated for the data previously +stored in the newly allocated area. + +*--journal-size, -j BYTES*:: +Size of the journal. + +*--interleave-sectors SECTORS*:: +The number of interleaved sectors. + +*--integrity-recalculate*:: +Automatically recalculate integrity tags in kernel on activation. The +device can be used during automatic integrity recalculation but +becomes fully integrity protected only after the background operation +is finished. This option is available since the Linux kernel version +4.19. + +*--integrity-recalculate-reset*:: +Restart recalculation from the beginning of the device. It can be used +to change the integrity checksum function. Note it does not change the +tag length. This option is available since the Linux kernel version +5.13. + +*--journal-watermark PERCENT*:: +Journal watermark in percents. When the size of the journal exceeds +this watermark, the journal flush will be started. + +*--journal-commit-time MS*:: +Commit time in milliseconds. When this time passes (and no explicit +flush operation was issued), the journal is written. + +*--tag-size, -t BYTES*:: +Size of the integrity tag per-sector (here the integrity function will +store authentication tag). ++ +*NOTE:* The size can be smaller that output size of the hash function, +in that case only part of the hash will be stored. + +*--data-device <data_device>*:: +Specify a separate data device that contains existing data. The +<device> then will contain calculated integrity tags and journal for +data on <data_device>. ++ +*NOTE:* To not wipe the data device after initial format, also specify +--no-wipe option and activate with --integrity-recalculate to +automatically recalculate integrity tags. + +*--sector-size, -s BYTES*:: +Sector size (power of two: 512, 1024, 2048, 4096). + +*--buffer-sectors SECTORS*:: +The number of sectors in one buffer. ++ +The tag area is accessed using buffers, the large buffer size means that +the I/O size will be larger, but there could be less I/Os issued. + +*--integrity, -I ALGORITHM*:: +Use internal integrity calculation (standalone mode). The integrity +algorithm can be CRC (crc32c/crc32), non-cryptographic hash function +(xxhash64) or hash function (sha1, sha256). ++ +For HMAC (hmac-sha256) you have also to specify an integrity key and its +size. + +*--integrity-key-size BYTES*:: +The size of the data integrity key. Maximum is 4096 bytes. + +*--integrity-key-file FILE*:: +The file with the integrity key. + +*--integrity-no-journal, -D*:: +Disable journal for integrity device. + +*--integrity-bitmap-mode. -B*:: +Use alternate bitmap mode (available since Linux kernel 5.2) where +dm-integrity uses bitmap instead of a journal. If a bit in the bitmap +is 1, the corresponding region's data and integrity tags are not +synchronized - if the machine crashes, the unsynchronized regions will +be recalculated. The bitmap mode is faster than the journal mode, +because we don't have to write the data twice, but it is also less +reliable, because if data corruption happens when the machine crashes, +it may not be detected. + +*--bitmap-sectors-per-bit SECTORS*:: +Number of 512-byte sectors per bitmap bit, the value must be power of +two. + +*--bitmap-flush-time MS*:: +Bitmap flush time in milliseconds. ++ +*WARNING:*:: +In case of a crash, it is possible that the data and integrity tag +doesn't match if the journal is disabled. + +*--integrity-recovery-mode. -R*:: +Recovery mode (no journal, no tag checking). + +*NOTE:* The following options are intended for testing purposes only.: +Using journal encryption does not make sense without encryption the +data, these options are internally used in authenticated disk +encryption with *cryptsetup(8)*. + +*--journal-integrity ALGORITHM*:: +Integrity algorithm for journal area. See --integrity option for +detailed specification. + +*--journal-integrity-key-size BYTES*:: +The size of the journal integrity key. Maximum is 4096 bytes. + +*--journal-integrity-key-file FILE*:: +The file with the integrity key. + +*--journal-crypt ALGORITHM*:: +Encryption algorithm for journal data area. You can use a block cipher +here such as cbc-aes or a stream cipher, for example, chacha20 or +ctr-aes. + +*--journal-crypt-key-size BYTES*:: +The size of the journal encryption key. Maximum is 4096 bytes. + +*--journal-crypt-key-file FILE*:: +The file with the journal encryption key. + +*--allow-discards*:: +Allow the use of discard (TRIM) requests for the device. This option +is available since the Linux kernel version 5.7. + +*--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. + +== LEGACY COMPATIBILITY OPTIONS + +*WARNING:*:: +Do not use these options until you need compatibility with specific +old kernel. + +*--integrity-legacy-padding*:: +Use inefficient legacy padding. + +*--integrity-legacy-hmac*:: +Use old flawed HMAC calculation (also does not protect superblock). + +*--integrity-legacy-recalculate*:: +Allow insecure recalculating of volumes with HMAC keys (recalculation +offset in superblock is not protected). + +== RETURN CODES + +Integritysetup 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. + +== NOTES +The dm-integrity target is available since Linux kernel version 4.12. + +Format and activation of an integrity device always require superuser +privilege because the superblock is calculated and handled in +dm-integrity kernel target. + +== EXAMPLES + +Format the device with default standalone mode (CRC32C): + +*integritysetup format <device>* + +Open the device with default parameters: + +*integritysetup open <device> test* + +Format the device in standalone mode for use with HMAC(SHA256): + +*integritysetup format <device> --tag-size 32 --integrity hmac-sha256 +--integrity-key-file <keyfile> --integrity-key-size <key_bytes>* + +Open (activate) the device with HMAC(SHA256) and HMAC key in file: + +*integritysetup open <device> test --integrity hmac-sha256 +--integrity-key-file <keyfile> --integrity-key-size <key_bytes>* + +Dump dm-integrity superblock information: + +*integritysetup dump <device>* + +== DM-INTEGRITY ON-DISK FORMAT + +The on-disk format specification available at +https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[*DMIntegrity*] page. + +== AUTHORS + +The integritysetup tool is written by mailto:gmazyland@gmail.com[Milan Broz]. + +include::man/common_footer.adoc[] |