systemd-cryptsetup

Open a LUKS volume and create a decrypted mapping at /dev/mapper/mapping_name

$ systemd-cryptsetup attach [mapping_name] [/dev/sdXY]

$ systemd-cryptsetup attach [mapping_name] [/dev/sdXY] none [crypttab_options]

$ systemd-cryptsetup attach [mapping_name] [/dev/sdXY] [path/to/keyfile] [crypttab_options]

$ systemd-cryptsetup detach [mapping_name]

While primarily managed by systemctl as a service unit, systemd-cryptsetup can be directly invoked for specific operations or debugging.

Service Unit Invocation (common):
systemctl [start|stop|status] systemd-cryptsetup@name.service

Direct Command Invocation:
systemd-cryptsetup [--help|--version]
systemd-cryptsetup attach NAME DEVICE KEY_FILE [OPTIONS]
systemd-cryptsetup detach NAME

-h, --help
    Displays a brief help message and exits.

--version
    Shows version information and exits.

attach
    Operation to attach (open) an encrypted device. It requires specific arguments: NAME, DEVICE, KEY_FILE, and optionally OPTIONS.

detach
    Operation to detach (close) an encrypted device, taking NAME as an argument.

NAME
    The desired device-mapper name for the decrypted volume (e.g., 'root', 'home').

DEVICE
    The path to the encrypted backing block device (e.g., '/dev/sda2', '/dev/disk/by-uuid/...').

KEY_FILE
    The path to a key file used for unlocking the device. Use '-' to prompt for a passphrase interactively.

[OPTIONS]
    A comma-separated list of cryptsetup options, such as 'cipher=aes-xts-plain64', 'hash=sha256', 'keyslot=1', or '_netdev' for network-dependent devices. These are passed directly to cryptsetup.

systemd-cryptsetup is a service manager that handles the activation and deactivation of LUKS-encrypted block devices during the system boot and shutdown processes. It integrates seamlessly with systemd's dependency system, ensuring that encrypted devices are unlocked and available before services requiring them are started, and properly closed before shutdown is complete.

Its primary function is to interpret entries in the crypttab(5) file, which defines encrypted partitions and their unlocking parameters. For each entry, systemd-cryptsetup-generator(8) creates a corresponding systemd-cryptsetup@.service unit. When these units are activated (typically during boot), systemd-cryptsetup invokes cryptsetup(8) to open the specified encrypted device, prompts for a passphrase if necessary (e.g., when a key file is not provided), and creates the decrypted device-mapper mapping.

This command replaces older init-script based methods for managing encrypted volumes, offering improved parallelism, robust error handling, and better integration with the rest of the systemd ecosystem. It is crucial for systems that utilize encrypted root filesystems or other critical encrypted storage.

Debugging issues with systemd-cryptsetup can be challenging, especially during early boot phases, as logs might not be fully accessible or verbose enough. Care must be taken when modifying crypttab(5) entries, as incorrect configurations can lead to unbootable systems. Network-bound encryption devices (_netdev option) require network connectivity, which might not be readily available during very early boot, potentially leading to delays or boot failures if not properly managed (e.g., via initramfs network setup).

The primary configuration source for systemd-cryptsetup is the /etc/crypttab file. Each line in this file describes an encrypted block device, its underlying physical device, a key file or passphrase source, and various options. systemd-cryptsetup-generator(8) reads this file during boot and creates instanced systemd-cryptsetup@.service units dynamically for each entry, which systemd then activates.

systemd-cryptsetup services are typically pulled in very early during the boot process by targets like cryptsetup.target and local-fs.target. This ensures that encrypted file systems are unlocked and mounted before user-space services or applications requiring access to these file systems are started. This early execution requires it to operate effectively even before the full system environment is available.

For each entry in /etc/crypttab, a dedicated systemd-cryptsetup@name.service unit is generated. For example, if you have an entry for a device named data_vol, a service unit systemd-cryptsetup@data_vol.service will be created. These units handle the actual attach and detach operations for the respective encrypted devices, allowing systemctl to manage them individually.

systemd-cryptsetup emerged as part of the systemd project, aiming to modernize and streamline the boot process for Linux systems. Before systemd, encrypted volumes were typically handled by various init scripts (e.g., cryptdisks on Debian/Ubuntu, cryptsys on Red Hat based systems). systemd-cryptsetup (along with systemd-cryptsetup-generator) provides a unified, declarative, and dependency-aware mechanism for managing LUKS volumes, aligning with systemd's principles of parallelization and robust service management. Its development has focused on tighter integration with the kernel's device-mapper and udev subsystems, ensuring reliable device activation and deactivation.

cryptsetup(8), crypttab(5), systemctl(1), systemd(1), systemd-cryptsetup-generator(8), systemd.special(7), udev(7)