---
name: "systemd-cryptsetup"
section: "8"
platform: "linux"
package: "systemd"
version: "262.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/systemd-cryptsetup"
---

# systemd-cryptsetup(8)

Full disk decryption logic

## NAME

systemd-cryptsetup, systemd-cryptsetup@.service - Full disk decryption logic

## SYNOPSIS

**systemd-cryptsetup** \[OPTIONS...\] attach VOLUME SOURCE-DEVICE \[KEY-FILE\] \[CRYPTTAB-OPTIONS\]

**systemd-cryptsetup** \[OPTIONS...\] detach VOLUME

systemd-cryptsetup@.service

system-systemd\\x2dcryptsetup.slice

## DESCRIPTION

**systemd-cryptsetup** is used to set up (with **attach**) and tear down (with **detach**) access to an encrypted block device. It is primarily used via systemd-cryptsetup@.service during early boot, but may also be called manually. The positional arguments *VOLUME*, *SOURCE-DEVICE*, *KEY-FILE*, and *CRYPTTAB-OPTIONS* have the same meaning as the fields in [**crypttab**(5)](/crypttab/5.md).

systemd-cryptsetup@.service is a service responsible for providing access to encrypted block devices. It is instantiated for each device that requires decryption.

systemd-cryptsetup@.service instances are part of the system-systemd\\x2dcryptsetup.slice slice, which is destroyed only very late in the shutdown procedure. This allows the encrypted devices to remain up until filesystems have been unmounted.

systemd-cryptsetup@.service will ask for hard disk passwords via the **password agent logic**\[1\], in order to query the user for the password using the right mechanism at boot and during runtime.

At early boot and when the system manager configuration is reloaded, /etc/crypttab is translated into systemd-cryptsetup@.service units by [**systemd-cryptsetup-generator**(8)](/systemd-cryptsetup-generator/8.md).

In order to unlock a volume a password or binary key is required. systemd-cryptsetup@.service tries to acquire a suitable password or binary key via the following mechanisms, tried in order:

 1\. If a key file is explicitly configured (via the third column in /etc/crypttab), a key read from it is used. If a PKCS#11 token, FIDO2 token or TPM2 device is configured (using the *pkcs11-uri=*, *fido2-device=*, *tpm2-device=* options) the key is decrypted before use.

 2\. If no key file is configured explicitly this way, a key file is automatically loaded from /etc/cryptsetup-keys.d/*volume*.key and /run/cryptsetup-keys.d/*volume*.key, if present. Here too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before use.

 3\. If the *try-empty-password* option is specified then unlocking the volume with an empty password is attempted.

 4\. If the *password-cache=* option is set to "yes" or "read-only", the kernel keyring is then checked for a suitable cached password from previous attempts.

 5\. Finally, the user is queried for a password, possibly multiple times, unless the *headless* option is set.

If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails.

## CREDENTIALS

**systemd-cryptsetup** supports the service credentials logic as implemented by *ImportCredential=*/*LoadCredential=*/*SetCredential=* (see [**systemd.exec**(5)](/systemd.exec/5.md) for details). The following credentials are used by "systemd-crypsetup@root.service" (generated by **systemd-gpt-auto-generator**) when passed in:

*cryptsetup.passphrase*

This credential specifies the passphrase of the LUKS volume.

Added in version 256.

*cryptsetup.tpm2-pin*

This credential specifies the TPM pin.

Added in version 256.

*cryptsetup.fido2-pin*

This credential specifies the FIDO2 token pin.

Added in version 256.

*cryptsetup.pkcs11-pin*

This credential specifies the PKCS11 token pin.

Added in version 256.

*cryptsetup.luks2-pin*

This credential specifies the pin requested by generic LUKS2 token modules.

Added in version 256.

## SEE ALSO

[**systemd**(1)](/systemd/1.md), [**systemd-cryptsetup-generator**(8)](/systemd-cryptsetup-generator/8.md), [**crypttab**(5)](/crypttab/5.md), [**systemd-cryptenroll**(1)](/systemd-cryptenroll/1.md), [**cryptsetup**(8)](/cryptsetup/8.md), **TPM2 PCR Measurements Made by systemd**\[2\]

## NOTES

- 1\.

  password agent logic

  https://systemd.io/PASSWORD\_AGENTS/

- 2\.

  TPM2 PCR Measurements Made by systemd

  https://systemd.io/TPM2\_PCR\_MEASUREMENTS