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]

systemd-cryptsetup (invoked indirectly during system boot, usually through systemd target dependencies)

--early
    Handle the root file system decryption. This parameter is mainly for usage in the initrd environment, it is rarely useful in the main system.

--ask-password
    Prompt the user for a password on the console.

--tty tty
    Read password from the specified TTY.

The systemd-cryptsetup service is a crucial component within the systemd ecosystem, specifically designed for managing LUKS-encrypted volumes during system startup.

It automates the process of unlocking encrypted partitions and logical volumes, making them accessible to the operating system. This involves prompting the user for the passphrase (if required), authenticating it, and then mapping the decrypted volume to a device node in /dev/mapper/. The configuration for which partitions should be automatically unlocked during boot is typically handled via /etc/crypttab (for traditional setups) or through systemd's generator mechanism that parses files in locations like /etc/systemd/system-generators/.

By integrating with systemd, it benefits from systemd's dependency management, parallelization, and journal logging. The service ensures that the decrypted volumes are available before services that depend on them start, leading to a smoother and more reliable boot process.

Directly invoking systemd-cryptsetup is uncommon. The service is normally managed automatically by systemd based on configuration files like /etc/crypttab. Misconfiguration can lead to boot failures.

While not directly invoked from the command line, systemd-cryptsetup is crucial for systems employing full-disk encryption or encrypted partitions. To configure an encrypted volume, you would typically use tools like cryptsetup to create the encrypted container and then configure /etc/crypttab or equivalent configuration files for automatic unlocking during boot. systemd then uses these configurations to start systemd-cryptsetup at boot time.

If decryption fails during boot, the system will usually drop you into an emergency shell. You can examine the system journal using journalctl -b to diagnose the problem. Common issues include incorrect passphrases, misconfigured /etc/crypttab entries, or missing dependencies.

The systemd-cryptsetup service evolved as part of the broader transition to systemd as the init system for many Linux distributions. Its purpose is to provide a standardized, robust, and integrated method for managing encrypted volumes within the systemd framework. Prior to systemd, manual scripts and other init systems were used, often leading to inconsistencies and complexities.

cryptsetup(8), crypttab(5), systemd(1), systemctl(1)