|
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | RETURN CODES | EXAMPLES | REPORTING BUGS | AUTHORS | COPYRIGHT | SEE ALSO | COLOPHON |
INTEGRITYSETUP(8) Maintenance Commands INTEGRITYSETUP(8)
integritysetup - manage dm-integrity (block level integrity) volumes
integritysetup <options> <action> <action args>
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
additional data integrity field per-sector. You can use this
additional field directly with integritysetup utility, or indirectly
(for authenticated encryption) through cryptsetup.
Integritysetup supports these operations:
format <device>
Formats <device> (calculates space and dm-integrity superblock
and wipes the device).
<options> can be [--batch-mode, --no-wipe, --journal-size,
--interleave-sectors, --tag-size, --integrity, --integrity-
key-size, --integrity-key-file, --sector-size]
open <device> <name>
create <name> <device> (OBSOLETE syntax)
Open a mapping with <name> backed by device <device>.
<options> can be [--batch-mode, --journal-watermark,
--journal-commit-time, --buffer-sectors, --integrity,
--integrity-key-size, --integrity-key-file, --integrity-no-
journal, --integrity-recovery-mode]
close <name>
Removes existing mapping <name>.
For backward compatibility there is remove command alias for
close command.
status <name>
Reports status for the active integrity mapping <name>.
dump <device>
Reports parameters from on-disk stored superblock.
--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
Show the program version.
--batch-mode
Do not ask for confirmation.
--no-wipe
Do not wipe device after format. Deviced that is not initially
wiped will contain invalid checksums.
--journal-size=bytes
Size of journal.
--interleave-sectors=SECTORS
Number of interleaved sectors.
--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=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.
--sector-size=bytes
Size of sector (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=algorithm
Use intenal integrity calculation (standalone mode). The
integrity algorithm can be CRC (crc32) or hash function (sha1,
sha256).
For HMAC (hmac-sha256) you have to also specify a integrity
key and its size.
--integrity-key-size=bits
The size of the data integrity key
--integrity-key-file=file
The file with the integrity key.
--integrity-no-journal
Disable journal for integrity device.
--integrity-recovery-mode
Recovery mode (no journal, no tag checking).
The dm-integrity target is available since Linux kernel version 4.12.
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.
Format the device with default standalone mode (CRC32):
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>
Report bugs, including ones in the documentation, on the cryptsetup
mailing list at <dm-crypt@saout.de> or in the 'Issues' section on
LUKS website. Please attach the output of the failed command with
the --debug option added.
The integritysetup tool and code is written by Milan Broz
<gmazyland@gmail.com> and is part of cryptsetup project.
Copyright © 2016-2017 Red Hat, Inc.
Copyright © 2016-2017 Milan Broz
This is free software; see the source for copying conditions. There
is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
The project website at https://gitlab.com/cryptsetup/cryptsetup
The integrity on-disk format specification available at
https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity
This page is part of the Cryptsetup ((open-source disk encryption))
project. Information about the project can be found at
⟨https://gitlab.com/cryptsetup/cryptsetup⟩. If you have a bug report
for this manual page, send it to dm-crypt@saout.de. This page was
obtained from the project's upstream Git repository
⟨https://gitlab.com/cryptsetup/cryptsetup.git⟩ on 2017-07-05. If you
discover any rendering problems in this HTML version of the page, or
you believe there is a better or more up-to-date source for the page,
or you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a mail
to man-pages@man7.org
integritysetup May 2017 INTEGRITYSETUP(8)