Set Up a dm-integrity Volume with systemd

You will configure one integrity-protected block device through /etc/integritytab, ask systemd to generate its instance service, and verify the resulting /dev/mapper device. This is a storage change, not a read-only diagnostic: use a disposable test device first and keep a recovery path for the host.

Allow about 20 minutes for an existing system and longer if you need to copy data or schedule a reboot. The examples target systemd 255, which is the installed version on the machine used for this guide. The service and the attach and detach commands have been present since systemd 250, but option availability still depends on the kernel and the installed systemd release.

1. Check the prerequisites

You need root access, a block device whose identity will not change, and a kernel with the device-mapper integrity target. Do not use a mounted filesystem, an active swap device, or a disk containing data you have not backed up. The first load of a new dm-integrity target can initialise its on-disk metadata, so treating an arbitrary disk as a test target can destroy its contents.

Start with non-destructive inventory. Replace the example identifier with the device you have deliberately selected:

lsblk -o NAME,PATH,SIZE,FSTYPE,TYPE,MOUNTPOINTS,PARTUUID
ls -l /dev/disk/by-partuuid/EXAMPLE-PARTUUID
sudo dmsetup targets | grep -w integrity

The last command may print an integrity target with its kernel version. No output means you should stop and resolve kernel or device-mapper support before writing configuration.

2. Choose the integrity format

The first two fields in an integritytab line are the mapper name and the underlying block device. The new device appears as /dev/mapper/ followed by the first field. A PARTUUID=, UUID=, LABEL=, or PARTLABEL= reference is preferable to /dev/sdX, because kernel device names can change between boots.

With no options, this local manpage describes journaled mode and the crc32c integrity algorithm. Journaled mode writes data and tags through a journal, which is safer across crashes but can cost performance. Bitmap mode needs only one data write but is less reliable after a crash. Direct mode disables both journal and bitmap; use it only when you understand the crash-consistency trade-off.

If the device was formatted with a non-default algorithm, specify the same algorithm when attaching it. A mismatch is not a harmless tuning change. The available algorithms in systemd 255's local documentation are crc32c, crc32, sha1, sha256, and hmac-sha256.

3. Add one integritytab entry

Back up the configuration, then add one line. This example uses defaults and a partition identity placeholder. The write requires elevated privileges.

sudo cp -a /etc/integritytab /etc/integritytab.before-example 2>/dev/null || true
sudoedit /etc/integritytab

Add:

securedata PARTUUID=EXAMPLE-PARTUUID

For an explicitly selected format, the fourth field is a comma-separated option list. For example:

securedata PARTUUID=EXAMPLE-PARTUUID - mode=journal,integrity-algorithm=sha256,journal-commit-time=10

A dash in the third field means there is no key file. If you specify an absolute key-file path instead, systemd uses HMAC-SHA256 and derives the key length from the file. Keep that file private and remember that keyed integrity is not encryption.

If you need to keep user data on a separate block device, use the documented data-device=/dev/disk/by-... option rather than guessing how the data and metadata should be laid out. Confirm the exact two devices before proceeding.

Checkpoint: inspect before activation

Read the line back and confirm that the referenced identity resolves to the device you selected. This catches the common distraction of editing the right-looking line with the wrong partition.

sudo sed -n '1,120p' /etc/integritytab
readlink -f /dev/disk/by-partuuid/EXAMPLE-PARTUUID

4. Generate and start the service

Reload the system manager. Entries in integritytab are translated into instantiated [email protected] units at early boot and when the manager configuration is reloaded.

sudo systemctl daemon-reload
systemctl list-unit-files '[email protected]'
sudo systemctl start [email protected]

The final command is the point where the block device is attached and the mapper node is created. Do not run it against a mounted or otherwise active device. If it fails, stop repeating it and inspect the journal:

systemctl status [email protected] --no-pager
sudo journalctl -u [email protected] -b --no-pager

Some installations do not expose the helper on the ordinary PATH. The service calls /usr/lib/systemd/systemd-integritysetup on this system. Its safe syntax check is:

sudo /usr/lib/systemd/systemd-integritysetup help

Do not substitute attach in that check: attach changes block-device state.

5. Verify the mapped device

A successful service should leave the volume available under /dev/mapper/securedata. Check both systemd's result and the mapper inventory:

systemctl is-active [email protected]
ls -l /dev/mapper/securedata
sudo dmsetup info securedata

Expected output from the first command is active. The mapper name and the service instance must agree. Only after this checkpoint should you put a filesystem on a genuinely empty test volume or mount an already prepared one. Formatting a mapper device is destructive, so it is deliberately not included here.

6. Stop and undo the example

Before detaching, unmount filesystems and stop every consumer of the mapped device. Detaching destroys the active mapping and makes anything using it fail. If the entry must not return at the next boot, remove or comment out its line in /etc/integritytab, then reload the manager.

findmnt /dev/mapper/securedata
sudo umount /dev/mapper/securedata
sudo systemctl stop [email protected]
sudo sed -i '\|^securedata[[:space:]]|d' /etc/integritytab
sudo systemctl daemon-reload

Check that the mapping is gone:

systemctl is-active [email protected] || true
test ! -e /dev/mapper/securedata && echo 'mapping removed'

The direct helper also has a detach command, but the service lifecycle is easier to audit when systemd created the mapping. If you use the helper manually, its syntax is detach volume and it still requires the same unmount and consumer checks.

Common failure boundaries

• Wrong device: verify the resolved PARTUUID and compare it with lsblk before starting the unit.
• Algorithm mismatch: match integrity-algorithm to the format already on the device. Do not fix an attach error by trying arbitrary algorithms.
• Discard exposure: allow-discards permits TRIM requests and is available from kernel 5.7; the integritytab option was added in systemd 250. Decide whether that information leak is acceptable for this device.
• HMAC confusion: a key file authenticates tags but does not encrypt the data. Use the appropriate dm-crypt design when confidentiality is also required.
• Service starts during boot: leaving the line in integritytab makes the generator recreate the unit on later boots. Remove the line as part of rollback, not just the current mapping.

Done means

• The selected block device is identified by a stable path and is backed up or disposable.
• The integritytab line matches the device and its on-disk integrity format.
• [email protected] is active and /dev/mapper/securedata exists.
• You know which consumers must stop before detaching and how to remove the boot-time entry.