- If in need to remotely unlock root or other early-boot filesystems (headless machine, distant servers...), follow the specific instructions from dm-crypt/Specialties#Remote unlocking of the root (or other) partition.
- To ease inputting UUIDs, PARTUUIDs, etc. in configuration files, you can install and use a text editor that supports inserting command output (e.g. nano with
Ctrl+t, Vim or Neovim with
:reador mcedit with
Alt+u) and pass it the apropriate lsblk or blkid command. Alternatively, you can install a terminal multiplexer and use its copy and paste functionality.
- 1 mkinitcpio
- 2 Boot loader
- 3 crypttab
- 4 Troubleshooting
Depending on the particular scenarios, a subset of the following mkinitcpio hooks will have to be enabled:
||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 |
||Needed to make keyboards work in early userspace.|
||Provides support for non-US keymaps for typing encryption passwords; it must come before the |
||Loads an alternative console font in early userspace. Set your font in |
Other hooks needed should be clear from other manual steps followed during the installation of the system.
Remember to regenerate the initramfs after saving the changes.
/etc/mkinitcpio.conf configuration using
... HOOKS=(base udev autodetect keyboard keymap consolefont modconf block encrypt lvm2 filesystems fsck) ...
A configuration with systemd-based initramfs using
... HOOKS=(base systemd autodetect keyboard sd-vconsole modconf block sd-encrypt sd-lvm2 filesystems fsck) ...
For example, if using GRUB, the relevant parameters are added to
/etc/default/grub 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 kernel parameters you need to specify depend on whether or not you are using the
encrypt hook or the
Kernel parameters like
resume are specified the same way for both
root= parameter specifies the
device of the actual (decrypted) root file system:
- 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
grub.cfgwith 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
deviceis 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
encrypthook does not support:
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:
deviceis the path to the device backing the encrypted device. Usage of persistent block device naming is strongly recommended.
dmnameis the device-mapper name given to the device after decryption, which will be available as
- 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
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:
deviceis the raw block device where the key exists. Usage of persistent block device naming is strongly recommended.
fstypeis the filesystem type of
pathis the absolute path of the keyfile within the device.
For a bitstream on a device the key's location is specified with the following:
where the offset and size are in bytes. For example,
cryptkey=UUID=ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ:0:512 reads a 512 byte keyfile starting at the beginning of the device.
:, 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:512for a usb key with the id
Also note that if
cryptkey is not specified, it defaults to
/crypto_keyfile.bin (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
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
crypto arguments must be specified, but each entry can be left blank:
A specific example of arguments is
Using sd-encrypt hook
In all of the following a
rd.luks can be replaced with a
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 for more options and more details.
- If the file
/etc/crypttab.initramfsexists, 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 .
/etc/crypttab.initramfsis not limited to using only UUID like
rd.luks. You can use any of the persistent block device naming methods.
- Passwords entered during boot are cached in the kernel keyring by crypttab that are unlocked after boot), then you will only need to input each password once. , so if multiple devices can be unlocked with the same password (this includes devices in
- All of the
rd.luksparameters can be specified multiple times to unlock multiple LUKS encrypted volumes.
rd.luksparameters 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.
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/crypttabdo not specify any
luks.*parameters and use
rd.luks.*. To activate all devices in
/etc/crypttab.initramfsdo not specify any
rd.luks.uuidcan be omitted when using
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 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.
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
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
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
Follows a similar format to options in crypttab - options are separated by commas, options with values are specified using
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.keyparameter can be omitted if the keyfile is included as
If the keyfile is on another device:
UUID=ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ with the identifier of the device on which the keyfile is located. If the type of file system is different than your root file system, you must include the kernel module for it in the initramfs.
rd.luks.keywith a keyfile on another device by default does not fallback to asking for a password if the device is not available. To fallback to a password prompt, specify the
rd.luks.options. E.g. for a 10 second timeout:
There are two options that affect the timeout for entering the password during boot:
rd.luks.options=timeout=mytimeoutspecifies the timeout for querying for a password
rootflags=x-systemd.device-timeout=mytimeoutspecifies 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:
/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 before
fstab, 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
See #Mounting at boot time section for instructions on how to use UUIDs to mount an encrypted device.for details, read below for some examples, and the
- 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
crypttabentries for dm-crypt plain mode (
--type plain) devices:
--type plaindevices with a keyfile, it is necessary to add the
hash=plainoption to crypttab due to a systemd incompatibility. Do not use
systemd-cryptsetupmanually for device creation to work around it.
- It may be further required to add the
plainoption explicitly to force
systemd-cryptsetupto recognize a
--type plain) device at boot. See systemd issue 442.
# 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
To test your crypttab immediately after editing it, reload the systemd manager configuration with:
# systemctl 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
email@example.com, see #Mounting on demand.
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:
externaldrive UUID=2f9a8428-ac69-478a-88a2-4aa458565431 none luks,timeout=180
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.
crypttabuses a previously entered password, the third parameter can be set to
noneand the cached password will be automatically used.
crypttabonly 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
crypttabis 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 ) can be set in fstab for said device. It is probably desired, then, that the amount of time of the
crypttabis equal to the amount of time of the
fstabfor each device mounted at boot time.
Unlocking with a keyfile
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:
home-crypt UUID=UUID-identifier /etc/cryptsetup-keys.d/home-crypt.key
- If a keyfile is not specified,
will automatically try to load it from
- If you prefer to use a
--plainmode blockdevice, the encryption options necessary to unlock it are specified in
/etc/crypttab. Take care to apply the systemd workaround mentioned in crypttab in this case.
Then use the device mapper's name (defined in
/etc/crypttab) to make an entry in
/dev/mapper/home-crypt /home ext4 defaults 0 2
/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.
Mounting a stacked blockdevice
The systemd generators also automatically process stacked block devices at boot.
$ lsblk -f
─sdXX linux_raid_member │ └─md0 crypto_LUKS │ └─cryptedbackup LVM2_member │ └─vgraid-lvraid ext4 /mnt/backup └─sdYY linux_raid_member └─md0 crypto_LUKS └─cryptedbackup LVM2_member └─vgraid-lvraid ext4 /mnt/backup
will ask for the passphrase and mount automatically at boot.
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
Instead of using
# cryptsetup luksOpen UUID=... externaldrive
you can start
firstname.lastname@example.org when you have an entry as follows in your
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.
The corresponding unit file is generated automatically by. You can list all generated unit files using:
$ systemctl list-unit-files | grep systemd-cryptsetup