How to Configure Cryptographic dm-integrity Devices in Ubuntu Using systemd-integritysetup-generator

In high-assurance enterprise environments, protecting persistent storage requires defending not only against unauthorized data inspection via encryption, but also against silent data corruption, hardware bit-rot, and unauthorized block modification. While LUKS and dm-crypt provide robust confidentiality, traditional block-level encryption does not authenticate data integrity—leaving systems vulnerable to replay attacks or storage medium decay. The Linux kernel provides dm-integrity, a device-mapper target that calculates and stores per-sector cryptographic HMAC or CRC checksums. In modern Ubuntu releases, systemd automatically discovers and configures these integrity-protected block devices during early boot via systemd-integritysetup-generator. By understanding how this generator translates /etc/integritytab into native systemd units, system engineers can automate cryptographically verified storage tiers.

Understanding dm-integrity and systemd Integration

The dm-integrity subsystem operates beneath the filesystem layer, maintaining an internal metadata area alongside user data to store cryptographic digests. Key architectural characteristics include:

• Per-Sector Digest Validation: Each read request triggers the kernel to recompute the sector’s hash or authentication tag. If bit rot or unauthorized sector modifications have occurred, the read request immediately returns an I/O error (-EIO), preventing corrupted data from entering page cache.
• Layering with dm-crypt: In authenticated disk setups, dm-integrity is typically layered beneath LUKS2 (or directly managed via LUKS2 authenticated encryption), ensuring data authentication precedes decryption.
• systemd Generator Execution: During early boot in the initramfs and early system startup, systemd-integritysetup-generator parses /etc/integritytab. For every configured entry, it dynamically synthesizes a [email protected] unit, mapping device dependencies into local-fs.target.
• Deterministic Teardown: During system shutdown, the generator-created service coordinates clean cache flushes and device-mapper unbinding before storage controllers power down.

Configuring Underlying Block Devices for dm-integrity

Before defining entries in /etc/integritytab, the target storage partition must be initialized with the integritysetup user-space utility. Ensure you have administrative root access and backup all existing data, as formatting overwrites partition content.

Install the required cryptsetup and device-mapper user tools on Ubuntu:

sudo apt update
sudo apt install cryptsetup-bin util-linux

Identify the target block device or partition using lsblk:

lsblk -o NAME,SIZE,TYPE,FSTYPE,UUID /dev/sdb1

Format the partition with dm-integrity using a standard SHA-256 cryptographic digest algorithm:

sudo integritysetup format /dev/sdb1 --integrity sha256

To test manual activation and verify device-mapper creation before committing to automated boot configuration:

sudo integritysetup open /dev/sdb1 int_data --integrity sha256
ls -l /dev/mapper/int_data
sudo integritysetup status int_data
sudo integritysetup close int_data

Defining Entries in /etc/integritytab

To ensure systemd-integritysetup-generator automatically activates the integrity volume at boot, define the device mapping in /etc/integritytab. The file uses whitespace-delimited columns matching the specification: volume name, device identifier, key file or passphrase specification, and configuration options.

Retrieve the persistent filesystem or partition UUID to avoid relying on unstable kernel device names (such as /dev/sdb1):

sudo blkid -s UUID -o value /dev/sdb1

Open /etc/integritytab in an editor and append the device entry:

# <volume-name>   <device>                                   <key-file>  <options>
int_storage       UUID=12345678-1234-1234-1234-123456789abc  none        integrity=sha256

For HMAC-based authentication (which requires a secret key to prevent intentional data tampering by attackers with physical drive access), specify the key file path:

int_secure        UUID=12345678-1234-1234-1234-123456789abc  /etc/keys/integrity.key  integrity=hmac-sha256

Simulating and Inspecting Generator Unit Synthesis

You can execute systemd-integritysetup-generator in dry-run mode to inspect the exact service units synthesized by systemd without rebooting the server.

Execute the generator against a temporary output directory:

sudo /lib/systemd/system-generators/systemd-integritysetup-generator /tmp/generator-test /tmp/generator-test /tmp/generator-test

Inspect the generated systemd unit files:

ls -la /tmp/generator-test/
cat /tmp/generator-test/systemd-integritysetup@int_storage.service

Notice the generated unit structure, which binds device prerequisites via BindsTo=dev-disk-by\x2duuid-...device and orders execution prior to blockdev@dev-mapper-int_storage.target.

To reload systemd and activate the synthesized units on a live system:

sudo systemctl daemon-reload
sudo systemctl start systemd-integritysetup@int_storage.service

Provisioning Filesystems and Mount Configuration

Once the authenticated block device is exposed under /dev/mapper/int_storage, format the exposed block layer with a standard Linux filesystem (such as ext4 or XFS) and configure /etc/fstab.

Format the verified block device:

sudo mkfs.ext4 -L IntegrityData /dev/mapper/int_storage

Obtain the UUID of the newly formatted filesystem layer:

sudo blkid -s UUID -o value /dev/mapper/int_storage

Add the filesystem mount to /etc/fstab with appropriate dependency flags:

UUID=abcdef12-3456-7890-abcd-ef1234567890 /mnt/integrity ext4 defaults,nofail,x-systemd.requires=systemd-integritysetup@int_storage.service 0 2

Test the mount configuration immediately:

sudo mount -a
df -hT /mnt/integrity

Monitoring Integrity Health and Troubleshooting Failures

Because dm-integrity actively reports integrity failures as kernel I/O errors, system administrators must monitor kernel rings and systemd service logs for hardware degradation.

Check the status of the integrity service unit:

systemctl status systemd-integritysetup@int_storage.service

Query device-mapper runtime statistics using dmsetup:

sudo dmsetup status int_storage

If silent bit corruption occurs, the kernel logs messages indicating checksum mismatches:

sudo dmesg | grep -E "device-mapper integrity|checksum error"

When bad sectors are detected, dm-integrity prevents corrupted blocks from being read, allowing system administrators to restore pristine copies from backup snapshots before filesystem corruption spreads.