# dm-crypt/System configuration

Back to Dm-crypt.

Tip: 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 encrypted root.

## 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:

- `encrypt`: always needed when encrypting the root partition, or a partition that needs to be mounted before root; it must come before the `filesystems` hook; it is not needed in all the other cases, as system initialization scripts like `/etc/crypttab` take care of unencrypting any other partitions.
- `shutdown`: recommended before mkinitcpio 0.16 to ensure controlled unmounting during system shutdown. It is still functional, but not deemed necessary anymore.
- `keymap`: provides support for foreign keymaps for typing encryption passwords; it must come before the `encrypt` hook.
- `keyboard`: needed to make USB keyboards work in early userspace.
  - `usbinput`: deprecated, but can be given a try in case `keyboard` does not work.

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

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

### 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 raw 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 the encrypted device contains a LVM, the name of the volume group (`vgname`) containing the logical volume of the root partition serves as dmname. The parameter then takes the form of `cryptdevice=device:vgname`.

### root

This parameter is needed when not using GRUB. The reason GRUB does not require this is because the auto-generated `grub.cfg` is meant to handle specifying the root for you.

    root=device

- `device` is the device file of the actual (decrypted) root file system. If the file system is formatted directly on the decrypted device file this will be `/dev/mapper/dmname`.
- If the root file system is contained in a logical volume of an encrypted LVM, the device mapper for it will be in the general form of `root=/dev/mapper/volumegroup-logicalvolume`.

### resume

    resume=device

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

### cryptkey

This parameter is required by the encrypt hook for reading a keyfile to unlock the cryptdevice. It can have two parameter sets, depending on whether the keyfile exists as a file or a bitstream starting on a specific location.

For a file 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

Example: `cryptkey=/dev/sdZ:0:512` reads a 512 bit keyfile starting at the beginning of the device.

See also Dm-crypt/Device encryption#Cryptsetup and 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:

## crypttab

The `/etc/crypttab` (or, encrypted device table) file contains a list of encrypted devices that are to be unlocked when the system boots, similar to fstab. This file can be used for automatically mounting encrypted swap devices or secondary filesystems.

It is read before fstab, so that dm-crypt containers can be unlocked before the filesystem inside is mounted. Note that crypttab is read after the system has booted, so it is not a replacement for unlocking via mkinitcpio hooks and boot loader options in the case of an encrypted root scenario. The boot time processing of crypttab is done by the `systemd-cryptsetup-generator` automatically, i. e. there is no need to activate it.

See the crypttab man page for details, below for further examples and #Mounting at boot time for setup steps using a device's UUID.

    /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, just enter the device's UUID in `/etc/crypttab`. You get the UUID (partition) by using the command `lsblk -f` and adding it to

    /etc/crypttab

     externaldrive         UUID=2f9a8428-ac69-478a-88a2-4aa458565431        none    luks,timeout=180

The first parameter is your preferred device mapper's name for your encrypted drive. The option `none` will trigger a prompt during boot to type the passphrase for unlocking the partition. The `timeout` option defines the timeout in seconds for entering the decryption password while booting. 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've defined in `/etc/crypttab` in `/etc/fstab` as shown here:

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

Categories:

- Security
- File systems