dm-crypt/System configuration
mkinitcpio
When encrypting a system it is necessary to regenerate the initial ramdisk after properly configuring mkinitcpio. Depending on the particular scenarios, a subset of the following 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.
|
keyboard
|
Needed to make keyboards work in early userspace. | |
keymap
|
sd-vconsole
|
Provides support for non-US keymaps for typing encryption passwords; it must come before the encrypt hook. Set your keymap in /etc/vconsole.conf .
|
consolefont
|
Loads an alternative console font in early userspace. Set your font in /etc/vconsole.conf .
|
Other hooks needed should be clear from other manual steps followed during the installation of the system.
Examples
A typical /etc/mkinitcpio.conf
configuration using encrypt
hook:
/etc/mkinitcpio.conf
... HOOKS=(base udev autodetect keyboard keymap consolefont modconf block encrypt lvm2 filesystems fsck) ...
A configuration with systemd-based initramfs using sd-encrypt
hook:
/etc/mkinitcpio.conf
... HOOKS=(base systemd autodetect keyboard sd-vconsole modconf block sd-encrypt sd-lvm2 filesystems fsck) ...
Boot loader
In order to enable booting an encrypted root partition, a subset of the following kernel parameters need to be set. See kernel parameters for instructions specific to your boot loader.
For example using GRUB the relevant parameters are best added to /etc/default/grub
before generating the boot configuration. 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 sd-encrypt
hook.
Kernel parameters
Kernel parameters like root
and resume
are specified the same way for both encrypt
and sd-encrypt
hooks.
root
The root=
parameter specifies the device
of the actual (decrypted) root file system:
root=device
- If the file system is formatted directly on the decrypted device file this will be
/dev/mapper/dmname
. - 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
root=/dev/mapper/volumegroup-logicalvolume
.
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
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:
cryptdevice=device:dmname
-
device
is the path to the device backing the encrypted device. Usage of Persistent block device naming is advisable. -
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/mapper/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 ofdevice
(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 is in bytes and the size in bits. Example: cryptkey=/dev/sdZ:0:512
reads a 512 bit keyfile starting at the beginning of the device.
:
, you have to escape it with three 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 file included in the initramfs the format is[1]:
cryptkey=rootfs:path
Example: cryptkey=rootfs:/secretkey
Also note that if cryptkey
is not specified, it defaults to /crypto_keyfile.bin
(in the initramfs).[2]
See also dm-crypt/Device encryption#Keyfiles.
crypto
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 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 rd.luks
can be replaced with luks
. rd.luks
parameters are only honored by the initrd. 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.
- 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(5). -
/etc/crypttab.initramfs
is not limited to using only UUID likerd.luks
. You can use any of the persistent block device naming methods.
/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
rd.luks.uuid=UUID
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.
rd.luks.name
rd.luks.name=UUID=name
Specify the name of the mapped device after the LUKS partition is open. For example, specifying UUID=cryptroot
causes the unlocked device to be located at /dev/mapper/cryptroot
. If this is not specified the mapped device will be located at /dev/mapper/luks-UUID
where UUID is the UUID of the LUKS partition.
This is equivalent to the second parameter of encrypt
's cryptdevice
.
rd.luks.options
rd.luks.options=UUID=options
or
rd.luks.options=options
Specify options for the device listed after 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
rd.luks.key=UUID=mykeyfile
or
rd.luks.key=mykeyfile
Specify the location of a password file used to decrypt the device specified in rd.luks.UUID
. There is no default location like there is with the encrypt
hook parameter cryptkey
.
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 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 systemd-cryptsetup-generator
automatically.
See crypttab(5) 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.
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.crypttab
entries for dm-crypt plain mode (--type plain
) devices:
- For
--type plain
devices with a keyfile, it is necessary to add thehash=plain
option to crypttab due to a systemd incompatibility. Do not usesystemd-cryptsetup
manually for device creation to work around it.
- It may be further required to add the
plain
option explicitly to forcesystemd-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:
/etc/crypttab
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.
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:
/etc/fstab
/dev/mapper/externaldrive /mnt/backup ext4 defaults,errors=remount-ro 0 2
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.
Mounting a stacked blockdevice
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:
$ 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/mapper/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.
Troubleshooting
System stuck on boot/password prompt does not show
If you are using Plymouth, make sure to use the correct modules (see: Plymouth#The plymouth hook) or disable it. Otherwise Plymouth will swallow the password prompt, making a system boot impossible.