/etc/veritytab describes a read-only dm-verity mapping so systemd can generate its service automatically. Think /etc/crypttab, but for integrity checking instead of encryption: dm-verity catches tampering by checking blocks against a signed or otherwise trusted hash tree. It does not encrypt anything, and it will not repair a failed block unless you have also configured a FEC device.
Allow about 20 minutes, not counting the time needed to create and independently verify the data and hash devices. This guide uses the locally installed systemd 255.4 and veritysetup 2.7.0. You need root access, an existing data device, an existing hash device, and a trusted hexadecimal root hash. Do not use the examples against a device containing data you cannot replace.
Checkpoint: This guide configures the systemd integration. It does not format a device, calculate a root hash, sign a root hash, or create a filesystem. Those operations must be completed first, using a workflow you have recorded and can reproduce.
Read the local manual and check the installed package before editing anything. These are read-only commands and do not need elevated privileges:
$ man 5 veritytab
$ dpkg-query -W -f='${Package} ${Version}\n' systemd
systemd 255.4-1ubuntu8.17
$ veritysetup --version
veritysetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPALThe file is read at early boot and when the system manager reloads its configuration. systemd-veritysetup-generator turns each valid line into native units. The installed manual is the authority for this host; options added in other systemd releases might not be available here.
Before using sudo, record the exact identifiers for the data device and hash device and the root hash produced by your image-building process. The first field is the name of the mapped volume. It becomes /dev/mapper/VOLUME_NAME. The next two fields may be paths or UUID=... specifications. The fourth field is a hexadecimal roothash.
Stable identifiers are usually less surprising than paths such as /dev/sdb2. Inspect block devices without changing them:
$ lsblk --fs
$ blkidDo not copy a filesystem UUID when the image-building procedure expects a partition or block-device identifier. A syntactically valid UUID pointing at the wrong bytes still produces a failed or misleading setup.
Security boundary: The root hash is the trust anchor for the data. Obtain it through a trusted channel and compare it with the value recorded by the image publisher or build system. Treat an unexplained root-hash change as a verification failure, not as a prompt to update the configuration.
Back up the file, then edit it with elevated privileges. The backup changes state, so check that the destination is the file you intend to replace:
$ sudo cp --preserve=mode,ownership,timestamps /etc/veritytab /etc/veritytab.before-exampleAdd a line with four mandatory fields and an optional comma-separated option field. This example uses placeholders deliberately. Replace every value, including the root hash, before saving:
# volume-name data-device hash-device roothash options
secure-data UUID=DATA_BLOCK_UUID UUID=HASH_BLOCK_UUID ROOT_HASH_HEX noauto,nofailThe noauto,nofail pair is a cautious first boot choice. noauto keeps the mapping out of veritysetup.target unless another unit pulls it in. nofail means boot does not fail merely because setup fails, although a filesystem that depends on the mapping can still fail. Remove these options only after you have a recovery path and have tested the mapping.
For a mapping required by a root or early-boot filesystem, the policy is different. Use x-initrd.attach when the protected block device must be set up in the initrd. If the protected filesystem is reached through a network resource, _netdev changes ordering to the remote verity targets. A corresponding network filesystem entry may also need _netdev to avoid a dependency loop.
Do not add check-at-most-once casually. It verifies a data block only on its first read and therefore does not detect later online tampering. Likewise, ignore-corruption turns verification failures into logged events rather than I/O errors. Both options weaken the normal failure response and need a documented threat model.
Ask systemd to regenerate its view of the configuration. This requires elevated privileges because it reloads the system manager:
$ sudo systemctl daemon-reload
$ systemctl list-unit-files 'systemd-veritysetup@*.service'
$ systemctl list-units --all 'systemd-veritysetup@*.service'The list may be empty when the entry is marked noauto and nothing has pulled it in. That is not, by itself, evidence that the line was accepted or rejected. Inspect the unit named after your volume if it appears:
$ systemctl cat [email protected]
$ systemctl status [email protected] --no-pagerUse the exact volume name from the first field. The status output is host-specific. A failed unit should include a useful reason, such as an unavailable device, an invalid root hash, an incompatible option, or a kernel dm-verity error.
Warning: Starting the unit can create a mapped block device and expose data to consumers. Confirm that the data and hash devices are the intended ones and that no existing mount depends on a conflicting mapping. Then start the named unit explicitly:
$ sudo systemctl start [email protected]
$ systemctl status [email protected] --no-pager
$ ls -l /dev/mapper/secure-dataSuccess should leave an active service and a mapper node. If the start fails, read the journal before editing the line:
$ journalctl -u [email protected] -b --no-pagerDo not respond to a root-hash mismatch by replacing the trusted hash with the value from an error message. Re-check the image, device ordering, block sizes, hash offset and the provenance of the root hash.
If the mapping is no longer needed, first stop anything using /dev/mapper/secure-data. Unmount dependent filesystems and stop their consumers before detaching the mapping. Then stop the service and remove or comment out the entry:
$ sudo systemctl stop [email protected]
$ sudoedit /etc/veritytab
$ sudo systemctl daemon-reloadIf the service was configured for automatic boot, leaving the line in place will recreate it later. If the edit made matters worse, restore the backup only after checking it is the backup for this change:
$ sudo cp --preserve=mode,ownership,timestamps /etc/veritytab.before-example /etc/veritytab
$ sudo systemctl daemon-reload