Create and Check a dm-integrity Volume with integritysetup

You will format a disposable block device, activate a dm-integrity mapping, inspect what was stored on disk, and close the mapping cleanly. The examples use integritysetup 2.7.0 from cryptsetup-bin 2:2.7.0-1ubuntu4.2. Allow 15 minutes for a small test device, plus time for the initial wipe.

This is an administrative operation. You need a Linux kernel with the dm-integrity target and root privileges for formatting and activation. Test with a loop device or spare block device first. Do not substitute a disk, partition or logical volume containing data: format calculates a superblock and wipes the target by default.

1. Confirm the installed tool

Check the version before relying on an option. The installed manual describes cryptsetup 2.7.0 and lists dm-integrity as available from Linux kernel 4.12. Some options have newer kernel requirements, so the program version alone is not a compatibility guarantee.

$ integritysetup --version
integritysetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL

The exact feature flags can differ between builds. The useful checkpoint is the version line. If the command is missing, install the distribution package that provides it rather than copying a binary from an unrelated host.

2. Choose a disposable device

Use a real block device that you have identified, or create a loop device from a file. The device below is deliberately a placeholder:

DEVICE=/dev/loop7
sudo lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS "$DEVICE"

Read the output before continuing. It must not be mounted and must not contain data you need. A device that is busy or already has a filesystem is a stop signal, not a prompt to add --batch-mode.

3. Format the device

Run the following as root. The default standalone mode uses CRC32C, and the normal journal mode is retained:

sudo integritysetup format "$DEVICE"

You should see a successful completion after the wipe. The duration depends on the device. To make progress easier to monitor on a larger target, add --progress-frequency 10. For machine processing, --progress-json emits one compact JSON record at a time; its numeric values are represented as strings.

Do not add --no-wipe merely to make a test faster. The manual says an initially unwiped device will contain invalid checksums. That option is for a deliberate workflow, such as pairing an existing data device with --data-device and later using --integrity-recalculate.

4. Inspect the on-disk parameters

Dump the stored superblock before activation:

sudo integritysetup dump "$DEVICE"

The output is the configuration recorded for the integrity device. It is the right place to check the algorithm, tag size, sector size and journal-related values instead of relying on memory. Keep this output with the device documentation if the volume matters.

A non-default integrity algorithm is not detected automatically when opening a device. If you later format with --integrity sha256, for example, the matching --integrity sha256 must be supplied to open. The default CRC32C example does not need that extra option.

5. Open and verify the mapping

Choose a short mapping name. The command creates a device-mapper path under /dev/mapper:

NAME=integrity-test
sudo integritysetup open "$DEVICE" "$NAME"
sudo integritysetup status "$NAME"
ls -l "/dev/mapper/$NAME"

The status command reports the active integrity mapping. The final command should show the mapper node. This does not create a filesystem; it creates the integrity layer on which a filesystem or another consumer could be placed.

If opening fails with a message about device-mapper, check the kernel and permissions before changing options. This operation needs superuser access, and the kernel must provide dm-integrity. A command that cannot initialise device-mapper cannot be repaired by changing the mapping name.

6. Close it safely

Stop every reader and writer using the mapper, then remove the mapping:

sudo integritysetup close "$NAME"
sudo test ! -e "/dev/mapper/$NAME" && echo "mapping closed"

The expected checkpoint is mapping closed. If the mapping is busy, find and stop its users before retrying. --deferred can defer removal until the last user closes the device, but it changes the timing of removal and should be used only when that behaviour is intentional. --cancel-deferred cancels a previously configured deferred removal.

7. Pick options deliberately

Keep the default journal for a first deployment. --integrity-no-journal disables it and carries a crash warning: data and tags may no longer match after a crash. Bitmap mode, selected with --integrity-bitmap-mode, can reduce writes but is less reliable during a crash according to the manual. These are durability trade-offs, not performance switches to apply casually.

For authenticated tags, use an HMAC algorithm with an appropriately protected key file and specify both --integrity-key-size and --integrity-key-file during format and open. Treat the key file as sensitive. The manual marks journal integrity and journal encryption options as testing-oriented and intended internally for authenticated disk encryption; do not use them as a substitute for understanding cryptsetup.

Resizing is a separate change. integritysetup resize NAME can infer the underlying size, or accept --size in 512-byte sectors or --device-size. Increasing an integrity volume needs Linux kernel 5.7 or newer. After a resize, recalculation is set; use --wipe when newly added space must be wiped rather than checksummed in its previous state.

Common traps

• Formatting the wrong path: verify with lsblk and stop if the target is mounted or valuable.
• Assuming open detects the algorithm: it does not detect a non-default algorithm. Repeat the format-time algorithm option when opening.
• Skipping the wipe without a plan: --no-wipe leaves invalid checksums until a controlled recalculation workflow repairs them.
• Confusing a mapping with a filesystem: create and mount a filesystem only after the integrity mapping is verified, and unmount it before closing.
• Using recovery mode in production: --integrity-recovery-mode disables the journal and tag checking. The manual describes it as a recovery mode.