NAME
integritysetup - manage dm-integrity (block level integrity) volumesSYNOPSIS
integritysetup <action> [<options>] <action args>DESCRIPTION
Integritysetup is used to configure dm-integrity managed device-mapper mappings.BASIC ACTIONS
Integritysetup supports these operations:FORMAT
format <device>OPEN
open <device> <name>CLOSE
close <name>STATUS
status <name>DUMP
dump <device>RESIZE
resize <name>OPTIONS
--progress-frequency <seconds>Print separate line every <seconds> with
wipe progress.
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):
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.
{ "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 }
Do not wipe the device after format. A device
that is not initially wiped will contain invalid checksums.
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.
Size of the journal.
The number of interleaved sectors.
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.
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 in percents. When the size
of the journal exceeds this watermark, the journal flush will be
started.
Commit time in milliseconds. When this time
passes (and no explicit flush operation was issued), the journal is
written.
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.
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 (power of two: 512, 1024, 2048,
4096).
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.
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.
The size of the data integrity key. Maximum is
4096 bytes.
The file with the integrity key.
Disable journal for integrity device.
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.
Number of 512-byte sectors per bitmap bit, the
value must be power of two.
Bitmap flush time in milliseconds.
In case of a crash, it is possible that the
data and integrity tag doesn’t match if the journal is disabled.
Recovery mode (no journal, no tag
checking).
Integrity algorithm for journal area. See
--integrity option for detailed specification.
The size of the journal integrity key. Maximum
is 4096 bytes.
The file with the integrity key.
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.
The size of the journal encryption key.
Maximum is 4096 bytes.
The file with the journal encryption
key.
Allow the use of discard (TRIM) requests for
the device. This option is available since the Linux kernel version 5.7.
Defers device removal in close command
until the last user closes it.
Removes a previously configured deferred
device removal in close command.
Print more information on command
execution.
Run in debug mode with full diagnostic logs.
Debug output lines are always prefixed by #.
Show the program version.
Do not ask for confirmation.
Show short option help.
Show help text and default parameters.
LEGACY COMPATIBILITY OPTIONS
WARNING:Do not use these options until you need
compatibility with specific old kernel.
Use inefficient legacy padding.
Use old flawed HMAC calculation (also does not
protect superblock).
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.NOTES
The dm-integrity target is available since Linux kernel version 4.12.EXAMPLES
Format the device with default standalone mode (CRC32C):DM-INTEGRITY ON-DISK FORMAT
The on-disk format specification available at DMIntegrity <https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity> page.AUTHORS
The integritysetup tool is written by Milan <[email protected]>BrozREPORTING BUGS
Report bugs at cryptsetup <[email protected]>mailing or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.2023-12-18 | integritysetup 2.6.1 |