systemd-integritysetup-generator turns one line in /etc/integritytab into a real dm-integrity unit at boot. Get that line wrong and it is a storage mistake, not a syntax error you can shrug off. You will finish with a volume described correctly, a clear way to make systemd regenerate its unit, and checks that separate configuration errors from storage or kernel errors. The installed systemd version used for these examples is 255.4-1ubuntu8.17, from the Ubuntu systemd package.
Allow 20 to 30 minutes for a configuration-only review, and longer for a real device because formatting or changing an integrity layout can destroy data. You need root access, a device that has already been planned for dm-integrity, and a recovery path. This guide does not format a device or invent a key.
systemd-integritysetup-generator is an early-boot systemd generator. It reads /etc/integritytab and creates native [email protected] instances as needed. It is not the command that performs the attach operation itself, and it has no user-facing option set in its manual page.
The service it creates calls systemd-integritysetup, which does the actual work for each device. The generator runs at early boot and whenever the system manager reloads its configuration. That distinction explains a common wild goose chase: editing the file and then inspecting the generator binary never shows a mounted or usable volume. Inspect the generated unit and service state instead.
Check the local package and the generator path with ordinary, read-only commands:
$ dpkg-query -W -f='${Package} ${Version}\n' systemd
systemd 255.4-1ubuntu8.17
$ ls -l /usr/lib/systemd/system-generators/systemd-integritysetup-generatorCheckpoint: You should see the package version and an executable under /usr/lib/systemd/system-generators/. If the path is absent, stop and inspect the installed package rather than copying a path from another distribution.
Each non-comment line in /etc/integritytab has a volume name, an underlying block device, an optional key file, and optional comma-separated options. The resulting device appears below /dev/mapper/. Use a stable selector such as UUID=, PARTUUID=, LABEL= or PARTLABEL=, rather than an /dev/sdX name that can change between boots.
Before editing, identify the device and its existing metadata with ordinary commands:
$ lsblk -o NAME,PATH,SIZE,FSTYPE,UUID,PARTUUID,MOUNTPOINTS
$ findmnt --verify
$ ls -l /dev/disk/by-id/Do not guess a UUID or reuse a partition that contains valuable data. dm-integrity stores metadata on the device, so a first-time setup or format is a storage operation, not a harmless test. The kernel documentation describes the target layout and its integrity tags; it does not provide a recovery guarantee for an incorrectly selected device.
Editing /etc/integritytab requires elevated privileges. Save a copy before changing it, and keep the backup somewhere protected because it may contain a key-file path or other operational detail:
# sudo cp -p /etc/integritytab /etc/integritytab.backup.$(date +%Y%m%d%H%M%S)
# sudoedit /etc/integritytabFor a device whose integrity metadata already matches the defaults, the smallest entry is:
archive PARTUUID=REPLACE-WITH-ACTUAL-PARTUUIDOnly two fields are required: the volume name and the block device. A dash in the third or fourth position means no key file or no options, so this line explicitly supplies neither:
archive PARTUUID=REPLACE-WITH-ACTUAL-PARTUUID - -crc32c and journaled mode is the default.hmac-sha256 and must be an absolute path no larger than 4096 bytes.integritytab(5) page.Treat key files as secrets: restrict their permissions and never paste their contents into a ticket or shell history.
Checkpoint: Review the line as data, not as a command:
$ sudo awk 'NF && $1 !~ /^#/ {print NR ":" $0}' /etc/integritytab
3:archive PARTUUID=REPLACE-WITH-ACTUAL-PARTUUIDAfter saving the file, reload the system manager. This is an elevated, state-changing operation:
# sudo systemctl daemon-reloadThe reload makes generators run again. It does not by itself prove the underlying device can be opened, and it does not necessarily attach every new volume immediately. Inspect the generated service name and its status:
$ systemctl list-unit-files '[email protected]'
$ systemctl status '[email protected]' --no-pager
$ systemctl cat '[email protected]'The exact status output depends on the device. A missing instance usually points to a malformed entry, an incorrect unit name, or a generator failure. Read the journal without changing state:
$ journalctl -b -u '[email protected]' --no-pagerWarning: Do not use systemctl start as a first diagnostic on an unknown device. Starting the service can create or attach a mapper device and may affect later mounts. Confirm the backing device and integrity format first.
Once the service has been deliberately started by your normal boot workflow, verify the mapper device and its relationship to the backing device:
$ lsblk -o NAME,TYPE,PATH,FSTYPE,SIZE,MOUNTPOINTS
$ ls -l /dev/mapper/archive
$ systemctl is-active '[email protected]'active is useful evidence that the service completed, but it is not a test of every read or write. Check the filesystem or upper layer separately, and confirm that your intended mount unit uses the mapper path. If the service failed, collect the unit journal, the exact integritytab line, and the device identity. Do not keep changing algorithm, mode or journal options until the format and configuration agree.
If the problem is only an uncommitted configuration change, restore the backup and reload systemd:
# sudo cp -p /etc/integritytab.backup.YYYYMMDDHHMMSS /etc/integritytab
# sudo systemctl daemon-reloadReplace the backup name with the real one.
Warning: If a mapper device is already active, do not remove it, overwrite its backing device, or delete its key file while services or mounts still depend on it. Stop the dependent stack during a planned maintenance window and use the documented detach procedure for your deployment. Data destruction is not an undo operation.