dm-crypt/System configuration

Depending on the particular scenarios, a subset of the following mkinitcpio hooks will have to be enabled:

Other hooks needed should be clear from other manual steps followed during the installation of the system.

A typical /etc/mkinitcpio.conf configuration using encrypt hook:

/etc/mkinitcpio.conf

...
HOOKS=(base '''udev''' autodetect modconf kms keyboard '''keymap''' '''consolefont''' block '''encrypt''' lvm2 filesystems fsck)
...

A configuration with systemd-based initramfs using sd-encrypt hook:

The kernel parameters you need to specify depend on whether the encrypt hook or the sd-encrypt hook is being used. and are specified the same way for both.

For example, if using GRUB, the relevant parameters are added to before generating the main configuration file. See also GRUB#Warning when installing in chroot as another point to be aware of when installing the GRUB loader.

The root= parameter specifies the of the actual (decrypted) root file system:

root=device

• If the file system is formatted directly on the decrypted device file this will be .
• If a LVM gets activated first and contains an encrypted logical rootvolume, the above form applies as well.
• If the root file system is contained in a logical volume of a fully encrypted LVM, the device mapper for it will be in the general form of .

resume=device

• is the device file of the decrypted (swap) filesystem used for suspend to disk. If swap is on a separate partition, it will be in the form of /dev/mapper/swap. See also dm-crypt/Swap encryption.

This parameter will make the system prompt for the passphrase to unlock the device containing the encrypted root on a cold boot. It is parsed by the encrypt hook to identify which device contains the encrypted system:

cryptdevice=device:dmname:options

• is the path to the device backing the encrypted device. Usage of persistent block device naming is strongly recommended.
• is the device-mapper name given to the device after decryption, which will be available as .
• (optional) are comma separated options, e.g. for TRIM support. If no options are required, omit this parameter (use ).
• If a LVM contains the encrypted root, the LVM gets activated first and the volume group containing the logical volume of the encrypted root serves as device. It is then followed by the respective volume group to be mapped to root. The parameter follows the form of .

This parameter specifies the location of a keyfile and is required by the encrypt hook for reading such a keyfile to unlock the (unless a key is in the default location, see below). It can have three parameter sets, depending on whether the keyfile exists as a file in a particular device, a bitstream starting on a specific location, or a file in the initramfs.

For a file in a device the format is:

cryptkey=device:fstype:path

• is the raw block device where the key exists. Usage of persistent block device naming is strongly recommended.
• is the filesystem type of (or auto).
• is the absolute path of the keyfile within the device.

Example: cryptkey=LABEL=usbstick:vfat:/secretkey

For a bitstream on a device the key's location is specified with the following:

cryptkey=device:offset:size 

where the offset and size are in bytes. For example, reads a 512 byte keyfile starting at the beginning of the device.

For a file included in the initramfs the format is:

cryptkey=rootfs:path

Example:

Also note that if is not specified, it defaults to (in the initramfs).

See also dm-crypt/Device encryption#Keyfiles.

This parameter is specific to pass dm-crypt plain mode options to the encrypt hook.

It takes the form

crypto=hash:cipher:keysize:offset:skip

The arguments relate directly to the cryptsetup options. See dm-crypt/Device encryption#Encryption options for plain mode.

For a disk encrypted with just plain default options, the arguments must be specified, but each entry can be left blank:

crypto=::::

A specific example of arguments is

crypto=sha512:twofish-xts-plain64:512:0:

systemd-cryptsetup-generator is a systemd unit generator that reads a subset of kernel parameters, and /etc/crypttab, for the purpose of unlocking encrypted devices. See the man page for more details about it and all options it supports.

systemd-cryptsetup-generator is run during the initramfs stage when using the sd-encrypt mkinitcpio hook or the systemd dracut module.

In what follows, we describe some of the kernel parameters that systemd-cryptsetup-generator interprets.

rd.luks.uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Specify the UUID of the device to be decrypted on boot with this flag.

By default the mapped device will be located at where XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX is the UUID of the LUKS partition.

rd.luks.name=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX=name

Specify the name of the mapped device after the LUKS partition is open, where XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX is the UUID of the LUKS partition. This is equivalent to the second parameter of encrypt's .

For example, specifying causes the unlocked LUKS device with UUID to be located at .

Specify the location of a password file used to decrypt the device specified by its UUID. There is no default location like there is with the encrypt hook parameter .

If the keyfile is included in the initramfs:

rd.luks.key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX=/path/to/keyfile

or

rd.luks.key=/path/to/keyfile

If the keyfile is on another device:

rd.luks.key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX=/path/to/keyfile:UUID=ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ

Replace UUID=ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ with the identifier of the device on which the keyfile is located.

rd.luks.options=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX=options

or

rd.luks.options=options

Set options for the device specified by it UUID or, if not specified, for all UUIDs not specified elsewhere (e.g., crypttab).

This parameter is the analogue of crypttab's options field. The format is the same—options are separated by commas, options with values are specified using . This is roughly equivalent to the third parameter of encrypt's .

For example:

rd.luks.options=timeout=10s,discard,password-echo=no,tries=1

There are two options that affect the timeout for entering the password during boot:

• specifies the timeout for querying for a password
• specifies how long systemd should wait for the rootfs device to show up before giving up (defaults to 90 seconds)

If you want to disable the timeout altogether, then set both timeouts to zero:

rd.luks.options=timeout=0 rootflags=x-systemd.device-timeout=0

When the user is typing the password, systemd-cryptsetup by default outputs asterisks (*) for each typed character. This is unlike the encrypt hook, which does not output anything. To silence the output, set the option:

rd.luks.options=password-echo=no

If a TPM2 chip is available in your system, you can use it to automatically unlock your volume instead of using a password or a keyfile. Further information and detailed instructions on doing so can be found at Trusted Platform Module#Data-at-rest encryption with LUKS.

When using a detached LUKS header, specify the block device with the encrypted data. Must be used together with to specify the header file location.

See dm-crypt/Specialties#Encrypted system using a detached LUKS header for details and instructions.

The /etc/crypttab (encrypted device table) file is similar to the fstab file and contains a list of encrypted devices to be unlocked during system boot up. This file can be used for automatically mounting encrypted swap devices or secondary file systems.

is read before , so that dm-crypt containers can be unlocked before the file system inside is mounted. Note that  is read after the system has booted up, therefore it is not a replacement for unlocking encrypted partitions by using mkinitcpio hooks and configuring them by using kernel parameters as in the case of encrypting the root partition.  processing at boot time is made by the systemd-cryptsetup-generator automatically.

See for details, read below for some examples, and the #Mounting at boot time section for instructions on how to use UUIDs to mount an encrypted device.

To test your crypttab immediately after editing it, reload the systemd manager configuration with a daemon-reload and start the newly generated .

# cryptsetup status ''name''

/dev/mapper/''name'' is active.
  type:    ...
  cipher:  ...
  keysize: ... bits
  key location: ...
  device:  /dev/sdxN
  sector size:  ...
  offset:  ... sectors
  size:    ... sectors
  mode:    ...
  flags:   ...

For more on , see #Mounting on demand.

If you want to mount an encrypted drive at boot time, enter the device's UUID in /etc/crypttab. You get the UUID (partition) by using the command and adding it to in the form:

The first parameter is your preferred device mapper's name for the encrypted drive. The option none will trigger a prompt during boot to type the passphrase for unlocking the partition. The option defines a timeout in seconds for entering the decryption password during boot.

If the keyfile for a secondary file system is itself stored inside an encrypted root, it is safe while the system is powered off and can be sourced to automatically unlock the mount during with boot via crypttab. For example, unlock a crypt specified by UUID:

Then use the device mapper's name (defined in /etc/crypttab) to make an entry in :

Since /dev/mapper/externaldrive already is the result of a unique partition mapping, there is no need to specify an UUID for it. In any case, the mapper with the filesystem will have a different UUID than the partition it is encrypted in.

The systemd generators also automatically process stacked block devices at boot.

For example, you can create a RAID setup, use cryptsetup on it and create an LVM logical volume with respective filesystem inside the encrypted block device. A resulting:

will ask for the passphrase and mount automatically at boot.

Given you specify the correct corresponding crypttab (e.g. UUID for the device) and fstab () entries, there is no need to add additional mkinitcpio hooks/configuration, because /etc/crypttab processing applies to non-root mounts only. One exception is when the mdadm_udev hook is used already (e.g. for the root device). In this case and the initramfs need updating to achieve the correct root raid is picked first.

Instead of using

# cryptsetup open UUID=... externaldrive

you can start when you have an entry as follows in your /etc/crypttab:

That way you do not need to remember the exact crypttab options. It will prompt you for the passphrase if needed.

The corresponding unit file is generated automatically by . You can list all generated unit files using:

$ systemctl list-unit-files | grep systemd-cryptsetup

If you are using Plymouth, make sure to use the correct modules (see Plymouth#mkinitcpio) or disable it. Otherwise Plymouth will swallow the password prompt, making a system boot impossible.