diff options
Diffstat (limited to '')
| -rw-r--r-- | man/integritysetup.8.adoc | 240 |
1 files changed, 119 insertions, 121 deletions
diff --git a/man/integritysetup.8.adoc b/man/integritysetup.8.adoc index e89b0f7..26b957c 100644 --- a/man/integritysetup.8.adoc +++ b/man/integritysetup.8.adoc @@ -89,72 +89,33 @@ 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. +*--allow-discards*:: +Allow the use of discard (TRIM) requests for the device. This option +is available since the Linux kernel version 5.7. -*--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. +*--batch-mode, -q*:: +Do not ask for confirmation. -*--journal-watermark PERCENT*:: -Journal watermark in percents. When the size of the journal exceeds -this watermark, the journal flush will be started. +*--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. -*--journal-commit-time MS*:: -Commit time in milliseconds. When this time passes (and no explicit -flush operation was issued), the journal is written. +*--bitmap-sectors-per-bit SECTORS*:: +Number of 512-byte sectors per bitmap bit, the value must be power of +two. -*--tag-size, -t BYTES*:: -Size of the integrity tag per-sector (here the integrity function will -store authentication tag). +*--buffer-sectors SECTORS*:: +The number of sectors in one buffer. + -*NOTE:* The size can be smaller that output size of the hash function, -in that case only part of the hash will be stored. +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. + +*--cancel-deferred*:: +Removes a previously configured deferred device removal in *close* +command. *--data-device <data_device>*:: Specify a separate data device that contains existing data. The @@ -165,14 +126,16 @@ data on <data_device>. --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). +*--debug*:: +Run in debug mode with full diagnostic logs. Debug output lines are +always prefixed by *#*. -*--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. +*--deferred*:: +Defers device removal in *close* command until the last user closes +it. + +*--help, -?*:: +Show help text and default parameters. *--integrity, -I ALGORITHM*:: Use internal integrity calculation (standalone mode). The integrity @@ -182,15 +145,6 @@ algorithm can be CRC (crc32c/crc32), non-cryptographic hash function 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 @@ -201,76 +155,120 @@ 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. +*--integrity-key-file FILE*:: +The file with the integrity key. -*--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-key-size BYTES*:: +The size of the data integrity key. Maximum is 4096 bytes. -*--integrity-recovery-mode. -R*:: -Recovery mode (no journal, no tag checking). +*--integrity-no-journal, -D*:: +Disable journal for integrity device. -*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)*. +*--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. -*--journal-integrity ALGORITHM*:: -Integrity algorithm for journal area. See --integrity option for -detailed specification. +*--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-integrity-key-size BYTES*:: -The size of the journal integrity key. Maximum is 4096 bytes. +*--integrity-recovery-mode. -R*:: +Recovery mode (no journal, no tag checking). -*--journal-integrity-key-file FILE*:: -The file with the integrity key. +*--interleave-sectors SECTORS*:: +The number of interleaved sectors. + +*--journal-commit-time MS*:: +Commit time in milliseconds. When this time passes (and no explicit +flush operation was issued), the journal is written. *--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. ++ +*NOTE:* The journal encryption options are only intended for testing. +Using journal encryption does not make sense without encryption of the data. + +*--journal-crypt-key-file FILE*:: +The file with the journal encryption key. *--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. +*--journal-integrity ALGORITHM*:: +Integrity algorithm for journal area. See --integrity option for +detailed specification. -*--allow-discards*:: -Allow the use of discard (TRIM) requests for the device. This option -is available since the Linux kernel version 5.7. +*--journal-integrity-key-file FILE*:: +The file with the integrity key. -*--deferred*:: -Defers device removal in *close* command until the last user closes -it. +*--journal-integrity-key-size BYTES*:: +The size of the journal integrity key. Maximum is 4096 bytes. -*--cancel-deferred*:: -Removes a previously configured deferred device removal in *close* -command. +*--journal-size, -j BYTES*:: +Size of the journal. -*--verbose, -v*:: -Print more information on command execution. +*--journal-watermark PERCENT*:: +Journal watermark in percents. When the size of the journal exceeds +this watermark, the journal flush will be started. -*--debug*:: -Run in debug mode with full diagnostic logs. Debug output lines are -always prefixed by *#*. +*--no-wipe*:: +Do not wipe the device after format. A device that is not initially +wiped will contain invalid checksums. -*--version, -V*:: -Show the program version. +*--progress-frequency <seconds>*:: +Print separate line every <seconds> with wipe progress. -*--batch-mode, -q*:: -Do not ask for confirmation. +*--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. + +*--sector-size, -s BYTES*:: +Sector size (power of two: 512, 1024, 2048, 4096). + +*--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. *--usage*:: Show short option help. -*--help, -?*:: -Show help text and default parameters. +*--verbose, -v*:: +Print more information on command execution. + +*--version, -V*:: +Show the program version. + +*--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. == LEGACY COMPATIBILITY OPTIONS |