NAME | SYNOPSIS | DESCRIPTION | OPTIONS | RETURN CODES | EXAMPLES | REPORTING BUGS | AUTHORS | COPYRIGHT | SEE ALSO | COLOPHON

INTEGRITYSETUP(8)           Maintenance Commands           INTEGRITYSETUP(8)

NAME         top

       integritysetup - manage dm-integrity (block level integrity) volumes

SYNOPSIS         top

       integritysetup <options> <action> <action args>

DESCRIPTION         top

       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.

OPTIONS         top

       --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 (crc32c/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.

              WARNING: In case of crash, it is possible that the data and
              integrity tag doesn't match if journal is disabled.

       --integrity-recovery-mode
              Recovery mode (no journal, no tag checking).

       The dm-integrity target is available since Linux kernel version 4.12.

RETURN CODES         top

       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.

EXAMPLES         top

       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>

REPORTING BUGS         top

       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.

AUTHORS         top

       The integritysetup tool and code is written by Milan Broz
       <gmazyland@gmail.com> and is part of cryptsetup project.

COPYRIGHT         top

       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.

SEE ALSO         top

       The project website at https://gitlab.com/cryptsetup/cryptsetup 

       The integrity on-disk format specification available at
       https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity 

COLOPHON         top

       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-09-15.  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)