Control LUKS Boot Unlocks with systemd-cryptsetup-generator

You will configure and check the systemd generator that turns /etc/crypttab entries into [email protected] units. The practical result is a predictable LUKS unlock configuration, with clear control over whether it applies in the initrd, the running system, or both.

Allow about twenty minutes, excluding any time needed to recover a forgotten volume password. You need a Linux host using systemd 255 or a compatible release, an existing LUKS volume, and root access for reading or editing /etc/crypttab and reloading the system manager. The examples use placeholders. Do not run them against a production volume until you have checked the device, UUID and key handling.

1. Check the installed generator

First confirm the package and executable. These checks are ordinary read-only commands:

$ systemd --version
systemd 255
$ command -v /usr/lib/systemd/system-generators/systemd-cryptsetup-generator
/usr/lib/systemd/system-generators/systemd-cryptsetup-generator
$ dpkg-query -W -f='${Package} ${Version}\n' systemd
systemd 255.4-1ubuntu8.17

Your package revision will differ. The installed manual page describes systemd 255 and says that the generator translates /etc/crypttab into native units early at boot and when the system manager reloads its configuration. It is not a long-running daemon that you start and leave enabled.

Checkpoint: you should have identified the generator path and the systemd version before copying any kernel command-line example.

2. Identify the LUKS UUID without changing the volume

Use a tool from your normal storage-management workflow to identify the intended encrypted device. For example, lsblk is read-only:

$ lsblk -f
NAME        FSTYPE      FSVER LABEL UUID                                 FSAVAIL FSUSE% MOUNTPOINTS
nvme0n1
|-nvme0n1p2 crypto_LUKS 2           12345678-90ab-cdef-1234-567890abcdef
`-nvme0n1p3 ext4        1.0         01234567-89ab-cdef-0123-456789abcdef  120G    12% /home

Replace 12345678-90ab-cdef-1234-567890abcdef with the UUID reported for your actual LUKS device. Do not infer it from a partition name. A wrong UUID can leave the intended volume locked, or make you troubleshoot the wrong unit.

3. Add one crypttab entry

Back up the existing file before editing it. This is an elevated, security-sensitive change because it affects the next boot and may reference a key file:

# cp --preserve=mode,ownership,timestamps /etc/crypttab /etc/crypttab.before-generator-guide
# ${EDITOR:-vi} /etc/crypttab

Add an entry in this four-field shape, adjusting every placeholder:

vault UUID=12345678-90ab-cdef-1234-567890abcdef none luks

The first field is the mapped volume name. The second identifies the encrypted device. The example leaves key-file selection as none, so systemd-cryptsetup will use its normal password acquisition behaviour. The fourth field carries crypttab options; luks identifies the device as a LUKS volume. This guide does not put a password in the file or recommend storing one there.

If the volume is already represented by a working entry, edit that entry rather than creating a duplicate. Keep a copy of the original until the unlock has been tested. To undo this step before reloading, restore the backup:

# cp --preserve=mode,ownership,timestamps /etc/crypttab.before-generator-guide /etc/crypttab

4. Regenerate the unit view

Ask systemd to reload its manager configuration. This requires elevated privileges and can cause dependent units to be reconsidered, so do it during a maintenance window on a busy host:

# systemctl daemon-reload

A successful reload normally prints nothing. It does not unlock every volume immediately. It causes generators to run again, including the cryptsetup generator, so the manager can see the units implied by the current configuration.

Inspect the generated unit using the name from the first crypttab field:

$ systemctl cat [email protected]
# /run/systemd/generator/[email protected]
[Unit]
...
[Service]
ExecStart=... systemd-cryptsetup attach vault ...

The exact unit text depends on the host and systemd release. The useful checkpoint is that systemctl cat finds a generated [email protected]. If it says the unit cannot be found, stop and check the spelling, the crypttab syntax and the reload result before rebooting.

5. Test the unlock without rebooting

Starting the generated service can prompt for the volume password and create the mapped device. It changes storage state, so verify the target name before using the command:

# systemctl start [email protected]
$ systemctl is-active [email protected]
active
$ ls -l /dev/mapper/vault
lrwxrwxrwx 1 root root ... /dev/mapper/vault -> ../dm-0

Some installations choose a different device-mapper presentation, so use lsblk or findmnt to confirm what appeared. An active service means the attach operation succeeded; it does not by itself mount a filesystem that sits inside the mapped device.

To undo this test, stop the generated service after unmounting anything that depends on the mapping:

# systemctl stop [email protected]

Do not stop a mapping that backs the root filesystem or a live mount. If the password is rejected, inspect the service journal and leave the original crypttab backup untouched while you correct the entry.

6. Understand kernel command-line overrides

The generator also reads kernel parameters. The broad switch luks=no disables the generator entirely. The narrower luks.crypttab=no makes it ignore devices from /etc/crypttab, but UUIDs supplied with luks.uuid= still work. These settings apply to the main system and the initrd; their rd. forms apply only in the initrd.

A UUID can be supplied more than once:

rd.luks.uuid=12345678-90ab-cdef-1234-567890abcdef luks.uuid=fedcba09-8765-4321-fedc-ba0987654321

If /etc/crypttab exists, the manual says that only UUIDs named on the kernel command line are activated in the initrd or real root. That makes a boot-loader edit a filtering decision, not merely an extra volume request. Treat changes to the kernel command line as security-sensitive and keep a known-good boot entry available for recovery.

For less common layouts, systemd 255 also supports per-UUID luks.name=, luks.data=, luks.key= and luks.options= parameters. The manual records luks.data= as available from version 247, luks.key= from version 202, and luks.options= from version 208. Use the matching rd. form when the setting is intended only for the initrd. Detached headers and external key devices are easy to make unbootable, so test them from a recovery path before relying on them.

7. Diagnose before rebooting

Check the unit and recent messages without changing configuration:

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

Look for a wrong UUID, a misspelled mapped name, an inaccessible key file, or a password prompt that was not answered. Check the active mapping and its type with lsblk -f. If you edited /etc/crypttab but the generated unit is unchanged, run systemctl daemon-reload again and verify that the entry is not commented out or duplicated.

Do not reboot merely to discover whether a new crypttab line parses. A successful manual start, a generated unit, and a confirmed mapping give you a safer checkpoint. If the host does not boot after a deliberate kernel-command-line change, use the boot loader's temporary edit facility to remove that parameter, boot the known-good entry, restore /etc/crypttab if needed, and rebuild any initrd only according to your distribution's documented process.