In modern Linux security architectures, ensuring the absolute integrity of the operating system root filesystem and immutable container images is paramount. Standard read-only filesystem mounts (such as mount -o ro) prevent accidental file modifications in user space, but they provide zero cryptographic protection against offline block tampering, rootkits, or malicious hardware attacks. The Linux kernel’s device-mapper verity (dm-verity) subsystem solves this by dividing storage into blocks, computing a cryptographic Merkle tree of hashes, and verifying every single 4KB block against a single trusted root hash as it is read from disk.
In Ubuntu and systemd-based distributions, early-boot orchestration of dm-verity targets is handled automatically by systemd-veritysetup-generator. Executing during initramfs initialization and early startup, this generator evaluates kernel command line parameters (such as systemd.verity= and roothash=) or static configuration files, dynamically instantiating native [email protected] units before filesystems are mounted. This guide covers how the verity generator works, how to pass kernel command line hashes, how to generate and test units in user space, and how to troubleshoot verification failures.
Understanding the dm-verity Boot Pipeline and Generator Workflow
The systemd-veritysetup-generator binary executes in the earliest stages of boot to establish an authenticated block device mapper before user-space initialization begins:
- Configuration Inputs: The generator checks the kernel command line parameters passed by UEFI bootloaders (such as UKI or GRUB), as well as configuration files located in
/etc/veritytab. - Dynamic Unit Synthesis: For each declared verity mapping, the generator creates a runtime service unit named
systemd-veritysetup@<volume>.serviceinside/run/systemd/generator/. - Dependency Wiring: It establishes strict order dependencies:
- Units order themselves
Before=local-fs-pre.targetandAfter=cryptsetup-pre.target. - Mount units expecting the authenticated filesystem gain
Requires=systemd-veritysetup@<name>.serviceandAfter=systemd-veritysetup@<name>.service.
- Units order themselves
- Kernel Device-Mapper Activation: The synthesized unit runs
/lib/systemd/systemd-veritysetup attach, loading the Merkle hash tree and binding the underlying block partition to/dev/mapper/<name>under strict cryptographic enforcement.
Configuring Authenticated Partitions in /etc/veritytab
Similar to how /etc/crypttab manages encrypted volumes, /etc/veritytab defines static dm-verity mappings for read-only secondary partitions, immutable system overlays, or software appliances:
# Structure: <volume-name> <data-device> <hash-device> <roothash> <options>
usr_verified /dev/disk/by-uuid/1111-2222 /dev/disk/by-uuid/3333-4444 a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890 restart-on-corruption,ignore-zero-blocks
Key parameters include:
data-device: The source partition containing the immutable filesystem payload (e.g., ext4 or squashfs).hash-device: The dedicated partition or offset containing the precomputed SHA-256 Merkle hash tree.roothash: The top-level 64-character hexadecimal SHA-256 root hash representing the immutable state of the entire volume.restart-on-corruption: Instructs the Linux kernel to immediately reboot or panic if any block fails cryptographic hash validation during a read operation, preventing execution of tampered binaries.panic-on-corruption: Triggers an instantaneous kernel panic upon detecting data corruption.
Configuring Root Filesystem Verity via Kernel Command Line
When protecting the entire root filesystem of an immutable OS image (such as an embedded appliance or Unified Kernel Image), the verity generator parses parameters directly from /proc/cmdline:
# Example kernel command line parameters for root verity
systemd.verity=1 \
roothash=a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890 \
systemd.verity_root_data=PARTUUID=12345678-01 \
systemd.verity_root_hash=PARTUUID=12345678-02 \
systemd.verity_root_options=restart-on-corruption
When these flags are present, systemd-veritysetup-generator automatically instantiates [email protected], ensuring the root device mapper /dev/mapper/root is authenticated before the root mount pivot occurs.
Testing Generator Output in User Space
You can execute systemd-veritysetup-generator manually from an elevated terminal to verify that configuration files in /etc/veritytab parse cleanly without rebooting:
# Create temporary directory for generator simulation
mkdir -p /tmp/verity-generator-test
# Run the generator in simulation mode
sudo /lib/systemd/system-generators/systemd-veritysetup-generator /tmp/verity-generator-test /tmp/verity-generator-test /tmp/verity-generator-test
Inspect the synthesized unit files generated inside the test directory:
# Inspect synthesized verity service unit
cat /tmp/verity-generator-test/systemd-veritysetup@usr_verified.service
The resulting unit confirms the exact parameters passed to systemd-veritysetup attach:
[Unit]
Description=Integrity Setup for usr_verified
Documentation=man:systemd-veritysetup-generator(8) man:[email protected](8)
DefaultDependencies=no
Conflicts=umount.target
Before=local-fs-pre.target umount.target
After=cryptsetup-pre.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/lib/systemd/systemd-veritysetup attach usr_verified /dev/disk/by-uuid/1111-2222 /dev/disk/by-uuid/3333-4444 a1b2c3d4... restart-on-corruption
ExecStop=/lib/systemd/systemd-veritysetup detach usr_verified
Auditing Active dm-verity Devices on Ubuntu
To inspect active authenticated verity block mappings on a running system:
# Check active device-mapper verity status
sudo veritysetup status usr_verified
The output reports corruption counts and active cryptographic modes:
/dev/mapper/usr_verified is active and is in use.
type: VERITY
status: verified
algorithm: sha256
data device: /dev/sda2
hash device: /dev/sda3
root hash: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890
flags: restart-on-corruption
Troubleshooting dm-verity Generation and Mount Failures
When deploying dm-verity with systemd, keep these troubleshooting guidelines in mind:
- Root Hash Mismatch (I/O Errors): If even a single byte on the data partition is modified after the hash tree is calculated, the kernel immediately halts the read request with an
EIO(Input/output error). Inspectdmesg | grep -i verityto confirm whether a block hash mismatch occurred. - Kernel Initramfs Hook Requirements: For the verity generator to protect the root partition, the
systemd-veritysetupbinary and generator must be included in the initramfs image. Ensure thesystemdinitramfs hook is active and regenerate the initramfs usingsudo update-initramfs -u -k all. - Missing Partition UUIDs: Always reference partitions in
/etc/veritytabusing persistentUUID=orPARTUUID=identifiers rather than transient device nodes like/dev/sdb1, as drive enumeration orders can shift between boots.
Using systemd-veritysetup-generator ensures that immutable Linux systems and protected partitions initialize automatically with hardware-backed cryptographic integrity enforcement.