Encrypting the root partition of your Linux system protects your data at rest. Even if an attacker gains physical access to your drive, they cannot read your files without the passphrase.
Caveats and Disclaimers
This guide provides step-by-step instructions for setting up LUKS-based root partition encryption on Gentoo using ugrd, GRUB, and OpenRC. It is intended for educational and informational purposes only and should not be taken as professional security advice.
While the procedures outlined are based on established best practices and aim to improve system security, no guarantee of security, integrity, or reliability is implied.
Several steps—particularly those involving disk partitioning, LUKS formatting, and bootloader configuration—may result in irreversible data loss, even (and especially) when they are performed correctly.
Back up your data before proceeding.
Target Environment and Scope
This guide assumes a new installation of Gentoo Linux from a Minimal Installation CD onto modern UEFI hardware and is designed as a practical, focused alternative to these two official Gentoo resources:
- The Preparing the disks section of the Gentoo AMD64 Handbook.
- The Rootfs encryption wiki page.
This article focuses on a secure and minimal setup for users who want:
- Passphrase-based root partition encryption with cryptsetup and LUKS.
- A straightforward disk partition scheme with a fully LUKS encrypted root. No LVM or separate partitions for
/home, etc. - A distribution kernel.
- ugrd (µgRD) to build the initramfs.
- GRUB as the bootloader.
- OpenRC as the init system.
- UEFI firmware with GUID Partition Table (GPT) disk. (strongly recommended for modern hardware)
If you are planning to use Dracut to build the initramfs with Systemd, this article isn’t for you. Instead, refer to this excellent guide, by Gered King, which covers that configuration in detail.
Partitioning Scheme
| Device Path | Mount Point | Filesystem | Size | Description |
|---|---|---|---|---|
/dev/nvme0n1p1 | /boot | vfat | 1 GiB | EFI system partition (ESP) |
/dev/nvme0n1p2 | / | xfs | Remainder of disk | Root partition |
Notes:
- vfat is the Linux driver used for FAT filesystem variants. The EFI System Partition (ESP) must use a FAT format on UEFI-based systems; otherwise, the system firmware will not detect the bootloader (or Linux kernel), and the system will fail to boot. FAT32 is the recommended format for the ESP.
- xfs is Gentoo’s recommended filesystem for the root partition due to its support for reflinks and Copy-on-Write (CoW) features. That said, Gentoo supports many filesystems (see the handbook), so feel free to choose based on your needs.
- Block devices depend on storage connection type: NVMe SSDs appear as
/dev/nvme0n1, SATA/SAS drives as/dev/sda./dev/nvme0n1p1and/dev/sda1refer to the first partition on each, respectively. Verify your device paths by runninglsblk.
Swap Considerations
For systems with disk encryption, swap should also be encrypted to prevent sensitive data from being written to unencrypted storage. While traditional swap partitions are common, I prefer a swap file in encrypted setups for its simplicity and flexibility. A swap file inherits the filesystem’s encryption when placed on an encrypted volume, eliminating the need for separate encryption; it can be easily resized, added, or removed without repartitioning; however, it does not support hibernation—so if hibernation is required, a separate encrypted swap partition is necessary. The creation of a swap file or partition is outside the scope of this guide.
Disk Preparation
Dependencies
You will need sys-fs/cryptsetup to setup LUKS.
emerge -av sys-fs/cryptsetup
Partitioning
Verify you device paths by running lsblk.
livecd ~ # lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
loop0 7:0 0 669.3M 1 loop /run/rootfsbase
nvme0n1 259:0 0 1.8T 0 disk
sr0 11:0 1 761.7M 0 rom /run/initramfs/live
Use fdisk, or another disk partition tool of your choice to create the partitions outlined in Partitioning Scheme.
livecd ~ # fdisk /dev/nvme0n1
Creating a New GPT disklabel
Remove all existing disk partitions and create a new GPT disklabel with g.
Command (m for help): g
Created a new GPT disklabel (GUID: A418D401-742D-4499-BD9C-DF63D8982685).
Creating the EFI System Partition (ESP)
Create a new partition with n, use Enter to select the first partition (1) and first sector (from 2048), then select the last sector with +1G to create a 1G partition.
Command (m for help): n
Partition number (1-128, default 1):
First sector (2048-3907029134, default 2048):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-3907029134, default 3907028991): +1G
Created a new partition 1 of type 'Linux filesystem' and of size 1 GiB.
Set the partition type to EFI System with t and use type 1.
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'.
Creating the Root Partition
Create a new partition with n, use Enter to select the second partition (2), the next available first sector, and the very last sector to create a partition that uses the remaining disk space.
Command (m for help): n
Partition number (2-128, default 2):
First sector (2099200-3907029134, default 2099200):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2099200-3907029134, default 3907028991):
Created a new partition 2 of type 'Linux filesystem' and of size 1.8 TiB.
Write the New Partition Layout
Save and write the new partition layout with w.
Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.
You should now have two partitions which can be verified by checking:
livecd ~ # fdisk -l /dev/nvme0n1
Disk /dev/nvme0n1: 1.82 TiB, 2000398934016 bytes, 3907029168 sectors
Disk model: Samsung SSD 990 PRO 2TB
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: C00F32B3-9054-42B9-898A-581114BFEA3F
Device Start End Sectors Size Type
/dev/nvme0n1p1 2048 2099199 2097152 1G EFI System
/dev/nvme0n1p2 2099200 3907028991 3904929792 1.8T Linux filesystem
Creating Filesystems
ESP Filesystem
The ESP should be formatted unencrypted FAT32.
livecd ~ # mkfs.vfat -F 32 /dev/nvme0n1p1
Note: Encrypting the boot partition offers limited benefit in most threat models while significantly complicates the boot process. See the Gentoo wiki for Full Disk Encryption for more information.
LUKS Encrypted Root Filesystem
Begin by creating a LUKS encrypted partition:
livecd ~ # cryptsetup luksFormat /dev/nvme0n1p2
WARNING!
========
This will overwrite data on /dev/nvme0n1p2 irrevocably.
Are you sure? (Type 'yes' in capital letters):
YES
Enter passphrase for /dev/nvme0n1p2:
Note: The default options of
cryptsetup luksFormatare considered secure and follow current best practices. It’s not recommended to override the default options unless you understand what you are doing. You can usecryptsetup --helptoo view the default settings.
Next, open the LUKS volume with:
livecd ~ # cryptsetup luksOpen /dev/nvme0n1p2 root
Note: This will open and map the volume to
/dev/mapper/root. This aligns with the Discoverable Partitions Specification.
Finally, create the root filesystem. Here I use xfs, however, as mentioned previously, Gentoo supports many filesystem see the handbook, so feel free to choose based on your needs.
livecd ~ # mkfs.xfs /dev/mapper/root
Mount Partitions
Before installing the stage file, you should mount the partitions.
livecd ~ # mount --mkdir /dev/mapper/root /mnt/gentoo
livecd ~ # mount /dev/nvme0n1p1 /mnt/gentoo/boot
Now, proceed with the rest of your Gentoo install as per the handbook.
After you are done with your installation, you can safely unmount the partitions with:
livecd ~ # umount /dev/nvme0n1p1
livecd ~ # umount /dev/mapper/root
livecd ~ # cryptsetup luksClose root
Configuration
In order to boot into our system successfully we must correctly configure ugrd, GRUB, and /etc/fstab.
/etc/fstab
/etc/fstab is a configuration file in that defines how filesystems and swap space are mounted at boot time.
It’s best practice to use UUIDs when specifying device partitions instead of device paths to avoid boot issue due to device name changes. Systems with multiple storage devices are particularly susceptible to this issue. To view the UUIDs for each device path use:
(chroot) livecd ~ # blkid
/dev/nvme0n1p1: UUID="C876-D34A" BLOCK_SIZE="512" TYPE="vfat" PARTUUID="a4671533-48fa-4bda-accf-1023fb2cda54"
/dev/nvme0n1p2: UUID="deb95beb-fdc5-4b69-ac36-98f432d31bba" TYPE="crypto_LUKS" PARTUUID="36976453-207e-4e8d-a90b-b8e14d36d0a7"
/dev/mapper/root: UUID="8d2c8845-cc71-4d3b-b184-107d5c0f2731" BLOCK_SIZE="512" TYPE="xfs"
For the / mountpoint you should specify the UUID of /dev/mapper/root.
/etc/fstab | |
Bootloader (GRUB)
In /etc/default/grub you must specify the device containing the encrypted root using the cryptdevice parameter.
cryptdevice=device:dmname:optionsdevice is the path to the device backing the encryption.dmname is the device-mapper name given to the device after decryption, e.g. /dev/mapper/dmname.options is optional and can be omitted.
/etc/default/grub | |
Add the GRUB_PLATFORMS="efi-64" variable to your /etc/portage/make.conf, then update and install GRUB.
(chroot) livecd ~ # echo 'GRUB_PLATFORMS="efi-64"' >> /etc/portage/make.conf
(chroot) livecd ~ # emerge -va --update --newuse sys-boot/grub
(chroot) livecd ~ # grub-install --target=x86_64-efi --efi-directory=/boot
(chroot) livecd ~ # grub-mkconfig -o /boot/grub/grub.cfg
Installkernel
To install the GRUB and ugrd hooks for sys-kernel/installkernel, enable the grub and ugrd and USE flags for installkernel in /etc/portage/package.use.
/etc/portage/package.use/installkernel | |
Rebooting
Exit the chrooted environment and unmount all the partitions.
(chroot) livecd ~ # exit
livecd ~ # umount /dev/nvme0n1p1
livecd ~ # umount /dev/mapper/root
livecd ~ # cryptsetup luksClose root
Now reboot for the moment of truth…