'\" t
.TH "SYSTEMD\-CRYPTSETUP" "8" "" "systemd 255" "systemd-cryptsetup"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-cryptsetup, systemd-cryptsetup@.service \- Full disk decryption logic
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-cryptsetup\fR\ 'u
\fBsystemd\-cryptsetup\fR [OPTIONS...] attach VOLUME SOURCE\-DEVICE [KEY\-FILE] [CONFIG]
.HP \w'\fBsystemd\-cryptsetup\fR\ 'u
\fBsystemd\-cryptsetup\fR [OPTIONS...] detach VOLUME
.PP
systemd\-cryptsetup@\&.service
.PP
system\-systemd\ex2dcryptsetup\&.slice
.SH "DESCRIPTION"
.PP
systemd\-cryptsetup
is used to set up (with
\fBattach\fR) and tear down (with
\fBdetach\fR) access to an encrypted block device\&. It is primarily used via
systemd\-cryptsetup@\&.service
during early boot, but may also be be called manually\&. The positional arguments
\fIVOLUME\fR,
\fISOURCEDEVICE\fR,
\fIKEY\-FILE\fR, and
\fICRYPTTAB\-OPTIONS\fR
have the same meaning as the fields in
\fBcrypttab\fR(5)\&.
.PP
systemd\-cryptsetup@\&.service
is a service responsible for providing access to encrypted block devices\&. It is instantiated for each device that requires decryption\&.
.PP
systemd\-cryptsetup@\&.service
instances are part of the
system\-systemd\ex2dcryptsetup\&.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\&.
.PP
systemd\-cryptsetup@\&.service
will ask for hard disk passwords via the
\m[blue]\fBpassword agent logic\fR\m[]\&\s-2\u[1]\d\s+2, in order to query the user for the password using the right mechanism at boot and during runtime\&.
.PP
At early boot and when the system manager configuration is reloaded,
/etc/crypttab
is translated into
systemd\-cryptsetup@\&.service
units by
\fBsystemd-cryptsetup-generator\fR(8)\&.
.PP
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:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
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
\fIpkcs11\-uri=\fR,
\fIfido2\-device=\fR,
\fItpm2\-device=\fR
options) the key is decrypted before use\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
If no key file is configured explicitly this way, a key file is automatically loaded from
/etc/cryptsetup\-keys\&.d/\fIvolume\fR\&.key
and
/run/cryptsetup\-keys\&.d/\fIvolume\fR\&.key, if present\&. Here too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before use\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
If the
\fItry\-empty\-password\fR
option is specified then unlocking the volume with an empty password is attempted\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
The kernel keyring is then checked for a suitable cached password from previous attempts\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
Finally, the user is queried for a password, possibly multiple times, unless the
\fIheadless\fR
option is set\&.
.RE
.PP
If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsystemd-cryptsetup-generator\fR(8),
\fBcrypttab\fR(5),
\fBsystemd-cryptenroll\fR(1),
\fBcryptsetup\fR(8),
\m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[2]\d\s+2
.SH "NOTES"
.IP " 1." 4
password agent logic
.RS 4
\%https://systemd.io/PASSWORD_AGENTS/
.RE
.IP " 2." 4
TPM2 PCR Measurements Made by systemd
.RS 4
\%https://systemd.io/TPM2_PCR_MEASUREMENTS
.RE