Unlock an Encrypted Volume with systemd-cryptsetup

You will configure one encrypted volume in /etc/crypttab, ask systemd to create its cryptsetup service, and verify the resulting mapping at /dev/mapper/cryptdata. The examples match systemd 255, installed here as package version 255.4-1ubuntu8.17.

Allow about 15 minutes. You need root access, a known LUKS volume, and a recovery path to the machine if the volume is needed for boot. Do not use these examples with a device you have not positively identified. An incorrect source device can make data unavailable, and an incorrect key-file setting can leave a volume locked.

1. Check the installed command

First confirm the binary and its local interface. These are ordinary, read-only commands:

$ command -v systemd-cryptsetup
/usr/bin/systemd-cryptsetup
$ systemd-cryptsetup --version
systemd 255.4-1ubuntu8.17
$ systemd-cryptsetup --help
systemd-cryptsetup attach VOLUME SOURCE-DEVICE [KEY-FILE] [CONFIG]
systemd-cryptsetup detach VOLUME

The command attaches an encrypted source under a volume name, or detaches that name. In normal operation you rarely call it directly. systemd-cryptsetup-generator reads /etc/crypttab and creates a [email protected] instance for each configured volume.

2. Identify the volume before changing configuration

Inspect block devices and filesystem signatures without opening anything:

$ lsblk --fs
$ sudo cryptsetup luksUUID /dev/REPLACE_WITH_SOURCE_DEVICE
REPLACE_WITH_LUKS_UUID

Replace the device placeholder only after checking the lsblk output. Prefer the printed LUKS UUID in crypttab, because device names such as /dev/sdb2 can change when hardware order changes. If cryptsetup luksUUID reports that the device is not a LUKS volume, stop and reassess the device.

Checkpoint: you should have an exact UUID and know which data will become available after the mapping is opened. If the volume contains a filesystem, record its expected mount point separately; unlocking a mapping does not mount it.

3. Add one crypttab entry

Back up the existing file, then edit it with elevated privileges:

$ sudo cp -p /etc/crypttab /etc/crypttab.before-cryptdata
$ sudoedit /etc/crypttab

Add one line, replacing the UUID with the value you verified:

cryptdata UUID=REPLACE_WITH_LUKS_UUID none luks

The first field is the mapping name. The second identifies the encrypted source. none in the key-file field means that a passphrase is requested interactively, and luks selects the LUKS format. Fields are separated by spaces or tabs. Keep the mapping name free of directory components, because the resulting device is /dev/mapper/cryptdata.

Do not put a passphrase directly into this file. If you use a key file instead, the entire file is used as key material, including any accidental trailing newline. Protect it as a secret and test recovery before depending on it for unattended boot.

4. Regenerate and inspect the service

Tell the running system manager to reload its configuration. This command requires elevated privileges and may create the generated service instance, but it does not itself unlock the volume:

$ sudo systemctl daemon-reload
$ systemctl status [email protected] --no-pager

The status output is host-specific. It may show an inactive generated unit before the first start, or an already active mapping if the volume was previously configured and unlocked. If systemd says the unit is not found, check the spelling of the mapping name and the syntax of /etc/crypttab before trying to start anything.

For a closer look at the generated unit and its dependencies, use:

$ systemctl cat [email protected]

Generated unit text is diagnostic output, not a file to edit. Change /etc/crypttab, then run systemctl daemon-reload again.

5. Start the mapping and verify it

Starting the service changes device state and may prompt for the passphrase, so do this only when you are ready to open the volume:

$ sudo systemctl start [email protected]
$ systemctl is-active [email protected]
active
$ ls -l /dev/mapper/cryptdata
lrwxrwxrwx ... /dev/mapper/cryptdata -> ../dm-N

A successful active result means the service is active. The device-mapper suffix is allocated by the kernel and can differ. Confirm the mapping and its backing device with:

$ lsblk --fs /dev/mapper/cryptdata
$ sudo cryptsetup status cryptdata

Do not treat an unlocked mapping as a mounted filesystem. Mount it only according to the filesystem and mount policy already used by your host. If this is a boot dependency, test the complete boot path during a maintenance window rather than relying on a manual start.

6. Investigate a failed unlock

Read the service journal without exposing the passphrase:

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

Common causes are a wrong UUID, a non-LUKS source, a mistyped mapping name, or a passphrase that does not match an available key slot. A failed prompt does not prove that the device is damaged. Recheck the source with lsblk and cryptsetup luksUUID, then compare the service name with the first field in /etc/crypttab.

systemd asks for passwords through its password-agent mechanism. At boot, Plymouth or a console agent may display the request; a manual systemctl start can use a terminal prompt. A headless configuration, or the headless option, suppresses the interactive fallback, so it needs a working non-interactive key method such as a correctly configured key file or hardware-backed setup.

7. Stop and undo the test

Unmount any filesystem on the mapping before closing it. Then stop the service:

$ sudo systemctl stop [email protected]
$ systemctl is-active [email protected]
inactive

Stopping the service closes the mapping. Do not do this while processes still use the filesystem. If the configuration should no longer be active, restore the backup and reload systemd:

$ sudo cp -p /etc/crypttab.before-cryptdata /etc/crypttab
$ sudo systemctl daemon-reload

The backup command restores the file as it was before this guide. It does not reopen or close a mapping that is already active, so handle the service state separately.