Home / Alt manpages / systemd-veritysetup-.service(8)

  • systemd-veritysetup-.service(8)
  • Admin command
  • linux

Attach and Detach a dm-verity Device with systemd

systemd-veritysetup attaches an existing dm-verity hash tree to a data device, hands you a read-only mapped volume, and detaches it again on command. The examples target systemd 255.4-1ubuntu8.17, installed here on Ubuntu, using the command supplied by that package.

The route

Jump straight to the step you need, or tick off Done means at the end.

Allow about 20 minutes, plus the time needed to identify the correct devices and obtain the trusted root hash. You need an existing dm-verity data device, its hash device, and a root hash from a trusted provisioning or verified-boot process. This guide does not create a hash tree or manufacture a root hash.

1. Check the installed interface

Start with a read-only check. It does not need elevated privileges:

$ dpkg-query -W -f='${Package} ${Version}\n' systemd
systemd 255.4-1ubuntu8.17
$ /usr/lib/systemd/systemd-veritysetup help
systemd-veritysetup attach VOLUME DATADEVICE HASHDEVICE ROOTHASH [OPTIONS]
systemd-veritysetup detach VOLUME

Attach or detach a verity protected block device.

See the [email protected](8) man page for details.

The manual describes three commands: attach, detach, and help. Attach and detach were added in systemd version 250, so this installed version has them. The command is normally an implementation detail of [email protected], but invoking it directly is useful for a controlled one-off test.

Checkpoint

If the executable is missing or its help output differs, stop and read the manual installed with your package. Do not copy an interface from a different systemd release into a boot workflow.

2. Identify the three values

  • VOLUME is the name of the device-mapper volume that will be created, not a path to an existing output device.
  • DATADEVICE holds the data whose reads will be checked.
  • HASHDEVICE holds the hash tree.
  • ROOTHASH is the digest at the root of that tree.

Use ordinary, read-only inspection to map device paths to your storage layout:

$ lsblk -o NAME,PATH,SIZE,TYPE,FSTYPE,LABEL,RO
$ readlink -f /dev/disk/by-id/REPLACE_WITH_DATA_DEVICE_ID
/dev/REPLACE_WITH_DATA_DEVICE
$ readlink -f /dev/disk/by-id/REPLACE_WITH_HASH_DEVICE_ID
/dev/REPLACE_WITH_HASH_DEVICE

Replace every REPLACE_WITH_... value with a value you have independently checked. A hash device can look much like an ordinary partition. Never select it by position alone, and never use a production disk as a test device just because its size looks plausible.

The kernel dm-verity documentation describes the data device as the block device being checked and the hash device as the source of the hash tree. dm-verity is read-only. The root digest is the trust anchor: if it is wrong, or came from an untrusted source, a successful attachment does not establish the integrity you intended.

3. Record a safe attachment command

Attachment changes kernel device-mapper state and normally needs root. It also exposes data through a new mapped device. Before running it, compare the data and hash paths with your provisioning record and check the root hash character by character.

# VOLUME='verified-root'
# DATADEVICE='/dev/REPLACE_WITH_DATA_DEVICE'
# HASHDEVICE='/dev/REPLACE_WITH_HASH_DEVICE'
# ROOTHASH='REPLACE_WITH_TRUSTED_ROOT_HASH'
# /usr/lib/systemd/systemd-veritysetup attach "$VOLUME" "$DATADEVICE" "$HASHDEVICE" "$ROOTHASH"

There is no fixed success message promised by the manual. Treat the command's exit status as the first check. A non-zero status means the mapping was not attached; keep the exact error text and investigate the paths, hash, device readiness, and permissions before retrying.

Do not add flags copied from veritysetup or dmsetup. This systemd helper documents an optional [OPTIONS...] position but does not enumerate options in the installed manpage. Its documented positional interface is the part you can rely on here.

4. Verify the mapped device

After a successful attach, inspect device-mapper state without changing it:

$ ls -l /dev/mapper/verified-root
$ lsblk -o NAME,PATH,SIZE,TYPE,RO,MOUNTPOINT /dev/mapper/verified-root
$ dmsetup info verified-root

The device name should match VOLUME. The mapping should be marked read-only. Exact lsblk and dmsetup wording varies, so check the facts rather than matching a sample line exactly. If the path is missing, or it is not read-only, stop before mounting or using it.

Warning

Reading a block through the mapping causes dm-verity to verify blocks as they are read, so an integrity failure can appear during later use rather than during the attach command. Copy only non-sensitive test data first, and keep the original data and hash devices while you validate the result.

5. Use the service model for boot-time setup

[email protected] is an instantiated service intended for each device that needs verity protection. At early boot, and when the system manager reloads its configuration, systemd-veritysetup-generator translates kernel command-line configuration into service units. The service then calls systemd-veritysetup.

This means a persistent boot setup is not the same as enabling an arbitrary hand-written service instance. Keep the kernel command line, the device layout, and the trusted root hash under the same provisioning and review process. Do not edit generated units, and do not assume a manual mapping will survive a reboot.

For a machine already using generated units, inspect what systemd currently knows before changing anything:

$ systemctl list-units 'systemd-veritysetup@*.service' --all
$ systemctl status 'systemd-veritysetup@*.service'

The second command can produce a non-zero result when no matching instance exists. That is a useful checkpoint, not a reason to invent an instance name. The local manpage documents the service's role, but the kernel command-line syntax belongs to the separate generator documentation and sits outside this focused workflow.

6. Detach it when finished

Detaching destroys the mapped device. Before doing it, unmount any filesystem using the mapping and stop processes that have open files there. This is a service-disrupting operation, so check the mountpoint and process list first:

$ findmnt --source /dev/mapper/verified-root
$ lsof /dev/mapper/verified-root

If the output shows an active consumer, stop there and close it cleanly. Once the mapping is unused, run the documented detach command with elevated privileges:

# /usr/lib/systemd/systemd-veritysetup detach verified-root
$ test ! -e /dev/mapper/verified-root && echo 'mapping detached'
mapping detached

Recovery

There is no data-device rollback in this operation, since dm-verity never makes a writable copy of the underlying data. If a detach fails, do not repeatedly force it. Recheck mounts, open descriptors, and the exact volume name. A successful detach removes the mapping while the data and hash devices remain in place.

Common failure traps

  • Wrong device order. The command expects volume, data device, hash device, then root hash. Swapping the two devices can produce an attachment failure or an unusable mapping.
  • Untrusted root hash. A digest copied from an unknown location is not a trust decision. Obtain it from the verified image or provisioning chain for this device.
  • Confusing tools. systemd-veritysetup, veritysetup, and dmsetup are related but do not share every command or option. Check each installed manpage before mixing examples.
  • Assuming attach verifies everything. dm-verity checks blocks as they are read. Exercise the mapped volume and investigate kernel or service errors instead of treating creation alone as a full test.
  • Leaving a stale mapping. An attached mapper device can keep storage busy and alter boot or shutdown behaviour. Detach it after the test, or document why the mapping is intentionally persistent.

Done means

  • You checked the installed systemd version and helper interface locally.
  • You independently confirmed the data device, hash device, volume name, and trusted root hash.
  • The mapped device exists, has the expected name, and is read-only.
  • Any integrity failure is treated as a security or storage incident, not bypassed by guessing options.
  • Test mappings are unmounted and detached, with the underlying data and hash devices left untouched.