Rootfs encryption

From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.
Other languages:

Encrypting the root filesystem can enhance privacy, and prevent unauthorized access.



cryptsetup is included in the Gentoo Minimal installation CD.
root #emerge --ask sys-fs/cryptsetup

System preparation

The kernel must be configured according to: Dm-crypt: Kernel Configuration.

This guide is designed to be followed as part of a fresh Gentoo install, the install procedure can be followed until the following step: AMD64 Handbook: Designing a partition scheme

Disk preparation

Partitioning typically does not involve modification of any of the data in partitions. If a drive is re-partitioned then encrypted, old data may remain in an unencrypted form until it is overwritten.
Modern storage devices may not be securely erased with something like dd if=/dev/urandom of=/dev/sdX. See Secure wipe for more information.

This example will use GPT as disk partition schema. fdisk will be used as the partitioning tool though any partitioning utility will work.

See also
For more information about GPT and EFI, see Disks (AMD64 Handbook).

Create disk partitions

A common setup for a basic system with a single drive may contain a partition for the boot files, and a partition for the system root.

CODE Partition layout with boot partition
 ├── /dev/nvme0n1p1 [EFI]       /efi       1 GB         fat32       Bootloader
 ├── /dev/nvme0n1p2 [BOOTX]     /boot      1 GB         ext4        Bootloader support files, kernel, initramfs
 └── /dev/nvme0n1p3 [ROOT]      (root)     ->END        luks        encrypted root partition
      └──  rootfs               /          ->END        btrfs       root partition

Configure GPT label

To create a partition layout using fdisk, start by creating a fresh partition table on the root disk:

root #fdisk /dev/nvme0n1
Welcome to fdisk (util-linux 2.38.1).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
Device does not contain a recognized partition table.
Created a new DOS disklabel with disk identifier 0x81391dbc.
Command (m for help):g
Created a new GPT disklabel (GUID: 8D91A3C1-8661-2940-9076-65B815B36906).

Create the ESP

With a GPT partition table created, the EFI System Partition (ESP) can be added using n:

Command (m for help):n
Partition number (1-128, default 1): 
First sector (2048-134217694, default 2048): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-134217694, default 134215679): +1G
Created a new partition 1 of type 'Linux filesystem' and of size 1 GiB.

The ESP property can be set using t:

Command (m for help):t
Selected partition 1
Partition type or alias (type L to list all): 1
Changed type of partition 'Linux filesystem' to 'EFI System'.

Create the Extended Boot partition

The boot partition can be created with:

Command (m for help):n
Partition number (2-128, default 2): 
First sector (2099200-134217694, default 2099200): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2099200-134217694, default 134215679): +1G
Created a new partition 2 of type 'Linux filesystem' and of size 1 GiB.

The Linux Extended Boot property can be set using t:

Setting this property is optional, but if set, should match the architecture of the system.
Command (m for help):t
Partition number (1-2, default 2):
Partition type or alias (type L to list all): 136
Changed type of partition 'Linux filesystem' to 'Linux Extended Boot'.

Create the Root partition

The root partition can be created with:

Command (m for help):n
Partition number (3-128, default 3): 
First sector (4196352-134217694, default 4196352): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (4196352-134217694, default 134215679):
Created a new partition 3 of type 'Linux filesystem' and of size 62 GiB.

The Linux Root (x86-64) property can be set using t:

Command (m for help):t
Partition number (1-3, default 3):
Partition type or alias (type L to list all): 23
Changed type of partition 'Linux filesystem' to 'Linux Root (x86-64)'.

Apply changes

Finally, the changes can be written with w:

Command (m for help):w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.

Create the LUKS encrypted partition

To prepare the encrypted filesystem, dm-crypt can be used:

To ensure the dm_crypt module is loaded, the following command can be used:
root #modprobe dm_crypt

The status of the module can be checked with:

user $lsmod | grep dm_crypt

To format the root partition using LUKS, secured with a passphrase:

root #cryptsetup luksFormat --key-size 512 /dev/nvme0n1p3
This will overwrite data on /dev/nvme0n1p3 irrevocably.
Are you sure? (Type 'yes' in capital letters): 
Enter passphrase for /dev/nvme0n1p3:

LUKS Header Backup

Do not forget this step, keys/passwords are used to decrypt the LUKS header, if it is destroyed for some reason, the remaining data will only be recoverable with the header file.

The headers can be backed up with:

root #cryptsetup luksHeaderBackup /dev/nvme0n1p3 --header-backup-file root_headers.img

Open the LUKS volume

The encrypted device must be opened and mapped before it can be used, this can be done with:

root #cryptsetup luksOpen /dev/nvme0n1p3 root
In this example, the volume is opened and mapped to /dev/mapper/root, as suggested by the Discoverable Partitions Specification.

Format the Filesystems

Create a filesystem for /dev/nvme0n1p1, the efi system partition which will contain the bootloader. This partition is read by UEFI. Most motherboards can read only a FAT32 filesystem:

root #mkfs.vfat -F32 /dev/nvme0n1p1

Next, format the extended boot partition. This partition must be readable by the bootloader, so ext4 can be used:

root #mkfs.ext4 -L boot /dev/nvme0n1p2

Finally, create root filesystem on the mapped LUKS volume (in this example btrfs is used):

root #mkfs.btrfs -L rootfs /dev/mapper/root

Gentoo installation

If this procedure is being followed during a Gentoo install (in place of Designing a partition scheme through Mounting the root partition), the install can be completed using the handbook with a few important considerations:

* sys-fs/cryptsetup and sys-fs/btrfs-progs must be installed within the chroot, before the initramfs is created.
  • An initial RAM filesystem must be built with support for decrypting and mounting the root partition.
  • If a bootloader is being used, it must be configured and installed on unencrypted volumes.

The root file system can be mounted at /mnt/gentoo to continue the install with:

root #mount --label rootfs /mnt/gentoo

At this point, the Gentoo install can be continued: Installing a stage tarball.

Initramfs configuration

See also
For additional configuration including GPG keys, refer to Full_Disk_Encryption_From_Scratch.

An initramfs must be used to decrypt and mount the root partition. This can be accomplished using an image generated by a tool such as UGRD or Dracut.

This configuration should be done while chrooted, or in the system which the initramfs is being built for.


UGRD should automatically detect most LUKS configurations. Once installed, it is automatically called by installkernel, generating a new image every time a kernel is installed.

UGRD is currently in the Guru repos and can be installed with:

root #emerge dev-vcs/git app-eselect/eselect-repository
root #eselect repository enable guru
root #emaint sync -r guru
root #emerge --ask sys-kernel/ugrd


In order to properly decrypt LUKS volumes, Dracut must be configured to use the crypt module, and cmdline parameters specifying the LUKS information must be configured:

The following modules must be added to the add_dracutmodules directive in /etc/dracut.conf.d/luks.conf:

Module configuration

FILE /etc/dracut.conf.d/luks.confMinimum required component to decrypt LUKS volumes using dracut
add_dracutmodules+=" crypt "
The spacing for Dracut configuration directives is very important. Ensure there are no spaces between add_dracutmodules and +=", parameters in add_dracutmodules must be padded with spaces.

LUKS target configuration

Dracut can be configured to build with configuration for LUKS hardcoded, first disk information must be obtained:

root #lsblk -o name,uuid
NAME        UUID
├─nvme0n1p1 BDF2-0139
├─nvme0n1p2 b0e86bef-30f8-4e3b-ae35-3fa2c6ae705b
└─nvme0n1p3 4bb45bd6-9ed9-44b3-b547-b411079f043b
  └─root    cb070f9e-da0e-4bc5-825c-b01bb2707704
FILE /etc/dracut.conf.d/luks.confEmbed cmdline parameters for rootfs decryption
kernel_cmdline+=" root=UUID=cb070f9e-da0e-4bc5-825c-b01bb2707704 rd.luks.uuid=4bb45bd6-9ed9-44b3-b547-b411079f043b "
If using GRUB, the root= parameter, "root=" included, should be added to the GRUB_CMDLINE_LINUX_DEFAULT option in /etc/default/grub.
On some setups it may be necessary to specify the rd.luks.uuid parameters in GRUB_CMDLINE_LINUX_DEFAULT and use for the encrypted root partition.
Embedding the root= option into the kernel commandline is required when using sys-boot/systemd-boot, but redundant when using GRUB's grub-mkconfig, which will automatically add that parameter.


When using systemd, rebuild it with the USE-flag cryptsetup:

FILE /etc/portage/package.use/systemd
sys-apps/systemd cryptsetup
root #emerge --ask sys-apps/systemd

Building the image

By default, Dracut writes to /boot which must be mounted.
Dracut uses the running kernel version by default, which will likely differ from the installed kernel.

Once Dracut is configured, the new initramfs is generated by:

root #dracut --kver 6.1.28-gentoo
Find possible kernel versions using:
user $ls /lib/modules

Booting with initramfs


Extensible Firmware Interface systems may boot an EFI stub kernel with initramfs using efibootmgr. A page relevant example is provided:

root #efibootmgr --create --disk /dev/nvme0n1 --label "Gentoo" --loader "vmlinuz-6.1.28-gentoo" --unicode "initrd=initramfs-6.1.28-gentoo"
If the ESP is on any partition but the first partition, the --part number must be specified.

See also