mkinitcpio

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

busybox

systemd

Use case

encrypt

sd-encrypt

Always needed when encrypting the root partition, or a partition that needs to be mounted before root. It is not needed in all the other cases, as system initialization scripts like /etc/crypttab take care of unlocking other encrypted partitions. This hook must be placed after the udev or systemd hook.

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 root=/dev/volumegroup/logicalvolume.

Tip: When using GRUB and generating grub.cfg with grub-mkconfig, this parameter does not need to be specified manually. grub-mkconfig will determine the correct UUID of the decrypted root filesystem and add it to grub.cfg automatically.

resume

resume=device

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.

Using encrypt hook

Note: Compared to the sd-encrypt hook, the encrypt hook has some limitations. It does not support:

cryptdevice

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:

dmname is the device-mapper name given to the device after decryption, which will be available as /dev/mapper/dmname.

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 cryptdevice=/dev/vgname/lvname:dmname.

cryptkey

This parameter specifies the location of a keyfile and is required by the encrypt hook for reading such a keyfile to unlock the cryptdevice (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

device is the raw block device where the key exists.

fstype is the filesystem type of device (or auto).

path is the absolute path of the keyfile within the device.

Example: cryptkey=/dev/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. Example: cryptkey=/dev/sdZ:0:512 reads a 512 byte keyfile starting at the beginning of the device.

Tip: If the device path you want to access contains the character :, you have to escape it with a backslash \. In that case the cryptkey parameter would be as follow: cryptkey=/dev/disk/by-id/usb-123456-0\:0:0:512 for a usb key with the id usb-123456-0:0.

For a disk encrypted with just plain default options, the crypto 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:

Using sd-encrypt hook

In all of the following a rd.luks can be replaced with a luks. The rd.luks parameters are only honored by the initrd, while the luks parameters are honored by both the main system and initrd. Unless you want to control devices which get unlocked after boot from kernel command line, use rd.luks. See systemd-cryptsetup-generator(8) for more options and more details.

Tip:

If the file /etc/crypttab.initramfs exists, mkinitcpio will add it to the initramfs as /etc/crypttab, you can specify devices that need to be unlocked at boot there. Syntax is documented in #crypttab and crypttab(5).

If you get dropped to an emergency shell at boot with systemd release 239.300-2 or later, see FS#60907.

All of the rd.luks parameters can be specified multiple times to unlock multiple LUKS encrypted volumes.

The rd.luks parameters only support unlocking detectable LUKS devices. To unlock a plain dm-crypt device or a LUKS device with a detached header, you must specify it in /etc/crypttab.initramfs. See #crypttab for the syntax.

Warning: If you are using /etc/crypttab or /etc/crypttab.initramfs together with luks.* or rd.luks.* parameters, only those devices specified on the kernel command line will be activated and you will see Not creating device 'devicename' because it was not specified on the kernel command line.. To activate all devices in /etc/crypttab do not specify any luks.* parameters and use rd.luks.*. To activate all devices in /etc/crypttab.initramfs do not specify any luks.* or rd.luks.* parameters.

rd.luks.uuid

Tip:rd.luks.uuid can be omitted when using rd.luks.name.

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

Specify the UUID of the device to be decrypted on boot with this flag. If the UUID is in /etc/crypttab.initramfs, the options listed there will be used. For luks.uuid options from /etc/crypttab.initramfs or /etc/crypttab will be used.

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

rd.luks.name

Tip: When using this parameter you can omit rd.luks.uuid.

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 cryptdevice.

For example, specifying rd.luks.name=12345678-9ABC-DEF0-1234-56789ABCDEF0=cryptroot causes the unlocked LUKS device with UUID 12345678-9ABC-DEF0-1234-56789ABCDEF0 to be located at /dev/mapper/cryptroot.

rd.luks.options

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 is roughly equivalent to the third parameter of encrypt's cryptdevice.

Follows a similar format to options in crypttab - options are separated by commas, options with values are specified using option=value.

For example:

rd.luks.options=timeout=10s,swap,cipher=aes-cbc-essiv:sha256,size=256

rd.luks.key

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 cryptkey.

Warning:rd.luks.key with a keyfile on another device does not fallback to passphrase if the device is not available. See systemd issue 12194.

Timeout

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

rd.luks.options=timeout=mytimeout specifies the timeout for querying for a password

rootflags=x-systemd.device-timeout=mytimeout 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

crypttab

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.

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

Note: When using systemd-boot and the sd-encrypt hook, if a non-root partition's passphrase is the same as root's, there is no need to put that non-root partition in crypttab due to passphrase caching. See this forum thread for more information.

Warning:

If the nofail option is specified, the password entry screen may disappear while typing the password. nofail should therefore only be used together with keyfiles.

There are issues with systemd when processing crypttab entries for dm-cryptplain mode (--type plain) devices:

For --type plain devices with a keyfile, it is necessary to add the hash=plain option to crypttab due to a systemd incompatibility. Do not use systemd-cryptsetup manually for device creation to work around it.

It may be further required to add the plain option explicitly to force systemd-cryptsetup to recognize a --type plain) device at boot. See systemd issue 442.

/etc/crypttab

# Example crypttab file. Fields are: name, underlying device, passphrase, cryptsetup options.
# Mount /dev/lvm/swap re-encrypting it with a fresh key each reboot
swap /dev/lvm/swap /dev/urandom swap,cipher=aes-xts-plain64,size=256
# Mount /dev/lvm/tmp as /dev/mapper/tmp using plain dm-crypt with a random passphrase, making its contents unrecoverable after it is dismounted.
tmp /dev/lvm/tmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256
# Mount /dev/lvm/home as /dev/mapper/home using LUKS, and prompt for the passphrase at boot time.
home /dev/lvm/home
# Mount /dev/sdb1 as /dev/mapper/backup using LUKS, with a passphrase stored in a file.
backup /dev/sdb1 /home/alice/backup.key

Mounting at boot time

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 lsblk -f and adding it to crypttab 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 timeout option defines a timeout in seconds for entering the decryption password during boot.

Note: Keep in mind that the timeout option in crypttab only determines the amount of time allowed for entering the password of the encrypted device. In addition, systemd also has a default timeout which determines the amount of time allowed for the device to be available (defaulting to 90 seconds), which is independent of the password timer. In consequence, even when the timeout option in crypttab is set to a value larger than 90 seconds (or it is at its default value of 0, meaning unlimited time), systemd will still only wait a maximum of 90 seconds for the device to be unlocked. In order to change the time systemd will wait for a device to be available, the option x-systemd.device-timeout (see systemd.mount(5)) can be set in fstab for said device. It is probably desired, then, that the amount of time of the timeout option in crypttab is equal to the amount of time of the x-systemd.device-timeout option in fstab for each device mounted at boot time.

A keyfile can also be set up and referenced instead of none. This results in an automatic unlocking, if the keyfile is accessible during boot. Since LUKS offers the option to have multiple keys, the chosen option can also be changed later.

Use the device mapper's name you have defined in /etc/crypttab in /etc/fstab as follows:

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.

Given you specify the correct corresponding crypttab (e.g. UUID for the crypto_LUKS device) and fstab (/dev/vgraid/lvraid) 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 /etc/madadm.conf and the initramfs need updating to achieve the correct root raid is picked first.

Mounting on demand

You can startsystemd-cryptsetup@externaldrive.service instead of using

# cryptsetup luksOpen UUID=... externaldrive

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

/etc/crypttab

externaldrive UUID=... none noauto

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