From Gentoo Wiki
Jump to:navigation Jump to:search

Personal reminders about installation specifics that I might otherwise forget.


Generally, this follows the Full Disk Encryption From Scratch Simplified, with a fallback to the standard installation guide and some spicing from Sakaki's installation guide. Some personal changes include a kernel that is more tailored to the specific hardware that I am installing Gentoo on. As I dig deeper into Gentoo, this guide will change. Finally, this is not the way, but a way, the target is to have a better understanding and have fun.

Some choices that I have made about the system:

  • OpenRC
  • Wayland
  • Minimal profile (nomultilib)
  • GPG Symmetrically encrypted key file with non standard algorithms
  • No swap - the laptop does not hibernate and has enough RAM.

This guide is written with a Dell Latitude 7480 as reference hardware. Some specs:

  • CPU: i7-7600U
  • RAM: 16GB
  • SSD: 256GB


1. Add dvorak layout to boot password.

2. Add kernel update section.


Get a Gentoo Minimal Installation CD burned on a USB flash disk. Plug it in the target laptop and boot into it. I am accustomed to a Dvorak keyboard - in the current iteration of the CD it is number 14 in the selection menu. If you are a happy qwerty user, press Enter and move on.

Configuring the network

This chapter is the parallel of the Network page in the official Handbook or the similar page from Sakaki's guide.

Network is required for downloading the Stage 3 tarballs as well as syncing portage and more. If the laptop has an Ethernet jack, and there is a cable around, great - plug it and try pinging Gentoo:

livecd ~ #ping -c3

If the ping is successful, you are in luck and can move to the next section.

If you are a lucky owner of a laptop without an Ethernet jack (I feel you...) or you do not have the cable around, then use wpa_supplicant to connect to the WiFi.

Figure out which one of the interfaces can connect to the WiFi (yours might have different names):

livecd ~ #ifconfig -s
lo                    ... further output suppressed ...
wlp2s0                ... further output suppressed ...
wwp0s20f0u2i12        ... further output suppressed ...

Create the configuration file for the network adapter:

livecd ~ #vi /etc/wpa_supplicant/wpa_supplicant-wlp2s0.conf

Add the following:

FILE /etc/wpa_supplicant/wpa_supplicant-wlp2s0.conf

To add the network details you will need the WiFi name and the password:

livecd ~ #wpa_passphrase NETWORK_SSID NETWORK_PASSWORD >> /etc/wpa_supplicant/wpa_supplicant-wlp2s0.conf
If your network SSID or password contain spaces - embrace it with quotes.

If the password has special characters, you might be better off omitting the NETWORK_PASSWORD argument in the command:

livecd ~ #wpa_passphrase NETWORK_SSID >> /etc/wpa_supplicant/wpa_supplicant-wlp2s0.conf
As it will prompt you to type in the password. Note that the password will be displayed in the terminal in plain text as you type.

At this point the wpa_supplicant config file will have the following appended:

FILE /etc/wpa_supplicant/wpa_supplicant-wlp2s0.confwpa_supplicant with network information.
Since the NETWORK_PASSWORD is not required (it is commented out) and is saved in plain text, you might want to get rid of it.

With that done, initialize the wpa_supplicant with the configuration file:

livecd ~ #wpa_supplicant -B -i wlp2s0 -c /etc/wpa_supplicant/wpa_supplicant-wlp2s0.conf
Successfully initialized wpa_supplicant

With that, test the network by pinging (or any other website of your choice):

livecd ~ #ping -c3
PING ( 56(84) bytes of data.
64 bytes from ... ( icmp_seq=1 ttl=57 time=202 ms
... further output supressed ...

Disk partitioning

For proper full disk encryption, using a separate boot drive the following partition scheme will be used:

CODE Partition layout with a separate boot drive.
Using an external storage device, such as a USB drive, may make sense to use as a boot drive.
Since we are using the btrfs file system (as well as fat32 and luks), be sure to install the relevant modules in the kernel (TODO: Link to section).
Since there are 3 devices at play - the Gentoo Live CD, the USB boot stick and the HDD/SDD, during the installation process, it is most likely that the order will be as follows:
  • sda: HDD/SDD
  • sdb: the Gentoo Live CD
  • sdc: the USB boot stick.
Be sure to notice which one is which, as this may differ on different machines.

In the case of this laptop, there is no NVME device.

Partitioning the main storage device

livecd ~ #fdisk /dev/sda

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

Command (m for help): g
Created a new GPT disklabel (GUID: <some ID>).

With a partition table crated, a new partition spanning the drive can be created by using n and then accepting the defaults:

Command (m for help):n
Partition number (1-128, default 1): 
First sector (2048-<size of media>, default 2048): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-<size of media>, default <size of media>): 

Created a new partition 1 of type 'Linux filesystem' and of size <size of media> GiB.

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.

Partitioning the boot USB stick

The boot disk can be setup using a similar process, the main difference is the boot flags will be set as a final step:

livecd ~ #fdisk /dev/sdc

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

Command (m for help): g

Created a new GPT disklabel (GUID: <some id>).

With a fresh partition table, a 512mb partition can be created using:

Command (m for help):n
Partition number (1-128, default 1): 
First sector (2048-<usb device size>, default 2048): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-<usb device size>, default <usb device size>): +512M

Created a new partition 1 of type 'Linux filesystem' and of size 512 MiB.

Finally, the ESP properties 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'.

Changes can be written with w:

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

Create the GPG key for the LUKS encrypted partition

livecd ~ #export GPG_TTY=$(tty)
livecd ~ #dd if=/dev/urandom bs=8388607 count=1 | gpg --symmetric --cipher-algo AES256 --output /tmp/crypt_key.luks.gpg
Enter passphrase
Passphrase <your new passphrase>
Please re-enter this passhprase
Passphrase <your new passphrase again>
... further output suppressed ...

Format the LUKS encrypted partition with the GPG key

livecd ~ #gpg --decrypt /tmp/crypt_key.luks.gpg | cryptsetup --cipher serpent-xts-plain64 --key-size 512 --key-file=- luksFormat /dev/sda1

Open the LUKS volume

Before you can work with the encrypted volume, it must be unlocked:

livecd ~ #gpg --decrypt /tmp/crypt_key.luks.gpg | cryptsetup --key-file=- open /dev/sda1 crypt

This maps the encrypted drive to /dev/mapper/crypt.

Backup the header file

livecd ~ #cryptsetup luksHeaderBackup /dev/sda1 --header-backup-file /tmp/crypt_header.img
Shall the LUKS header get damaged, the encrypted data will be lost forever, even if the GPG key and/or passphrase are intact.

Therefore, make a backup of the header file on a separate device for that case.

Consult with LUKS FAQ for more information.

Configure LVM inside of the LUKS volume

To create the LVM structure used in this example, with logical volumes for (/root, /var, and /home):

The physical volume can be created on the opened LUKS volume with:

livecd ~ #lvm pvcreate /dev/mapper/crypt

The volume group vg0 can be created wtih:

livecd ~ #vgcreate vg0 /dev/mapper/crypt

The logical volumes for /root, /var, and /home can be created with:

livecd ~ #lvcreate -L 64G -n root vg0
livecd ~ #lvcreate -L 64G -n var vg0
livecd ~ #lvcreate -l 100%FREE -n home vg0

Format the Filesystems

Create a filesystem for /dev/sdc1 (the USB boot stick), the boot partition which will contain GRUB and kernel files. This partition is read by UEFI. Most motherboards can read only a FAT32 filesystem:

livecd ~ #mkfs.vfat -F32 /dev/sdc1

If LVM is being used, to format each logical volume with the btrfs filesystem:

livecd ~ #mkfs.btrfs -L rootfs /dev/mapper/vg0-root
livecd ~ #mkfs.btrfs -L var /dev/mapper/vg0-var
livecd ~ #mkfs.btrfs -L homedir /dev/mapper/vg0-home
The labels are optional, but helpful. They allow for easy mounting without a UUID.

Mount the freshly formatted USB stick

At this point, the USB stick can be mounted to save the GPG key and the LUKS header file from the next session.

Find which device is the USB stick:

livecd ~ #lsblk

Create the mounting point:

livecd ~ #mkdir /mnt/stick

Mount it:

livecd ~ #mount /dev/sdc1 /mnt/stick

Finally, copy the GPG key and the header file over to the USB boot stick's new partition:

livecd ~ #cp /tmp/{crypt_key.luks.gpg,crypt_header.img} /mnt/stick/

Mounting the partitions

Mounting the root partition

At this point the device mapping should look like something along the lines of:

livecd ~ #lsblk
NAME                                          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
loop0                                           7:0    0 427,8M  0 loop  /mnt/livecd
sda                                             8:0    0 238,5G  0 disk
└─sda1                                          8:1    0 238,5G  0 part
  └─crypt                                     253:0    0 238,5G  0 crypt
    └─vg0-root                                253:1    0    64G  0 lvm
    └─vg0-var                                 253:2    0    64G  0 lvm
    └─vg0-home                                253:3    0 110,5G  0 lvm
... Gentoo Live CD ...
sdc                                             8:32   0  57,3G  0 disk
└─sdc1                                          8:33   0   512M  0 part  /mnt/stick

Create the mounting point for the root partition:

livecd ~ #mkdir /mnt/gentoo/

Mount the root partition:

livecd ~ #mount /dev/mapper/vg0-root /mnt/gentoo

Mount home and var partitions

Similarly, mount the home and var partitions:

livecd ~ #mkdir /mnt/gentoo/home
livecd ~ #mount /dev/mapper/vg0-home /mnt/gentoo/home
livecd ~ #mkdir /mnt/gentoo/var
livecd ~ #mount /dev/mapper/vg0-var /mnt/gentoo/var

You device tree will look like: TODO: Insert filesystem mounting point scheme.

Installing a stage3 tarball

This chapter is the parallel of the Stage page in the official Handbook or the similar page from Sakaki's guide.

Setting correct date and time

Ensure that the target machine has the correct time and date, as without it, you will have random weird issues and errors that are hard to debug:

livecd ~ #date

If necessary, set the date and time, in MMDDhhmmYYYY format (Month, Day, hour, minute, year):

livecd ~ #date MMDDhhmmYYYY
Substitute MMDDhhmmYYYY in the above with the correct datetime string.

For example, to set the UTC date and time to 12:00 on May 31st 2023, you would issue the following command:

livecd ~ #date 053112002023

Getting the Stage 3 tarballs

As mentioned before, here I will choose the OpenRC, no multilib (no desktop profile) tarball. With vg0-root mounted to /mnt/gentoo, switch to the latter directory:

livecd ~ #cd /mnt/gentoo
If willing to go nomultilib, consult with this package.mask in case you need any of these. If you do - do not go no multilib.

Download the tarball from the Gentoo Downloads page:

How to verify the stage3 file is described in detail in the Handbook's Verifying and validating section and here.

Unpacking the Stage 3 tarballs

Make sure that the /var directory from the USB key is mounted, as this is where the /var/db/pkg/ data will go - if abscent, Portage will later complain about circular dependencies, as it will need to install everything, including things that are already come in with the Stage3 tarball. Thus, if you see that in the Installing the up-to-date Portage tree section everything needs to be rebuilt - this is the issue.

Unpack the tarballs into the /mnt/gentoo directory:

livecd ~ #tar xvJpf stage3-amd64-*.tar.xz --xattrs-include='*.*' --numeric-owner

After it is done unpacking, you should see a familiar file structure. The stage3 tarball is no longer necessary, and you may wish to remove it now or at a later stage.

Configuring compile options

Information about compile options are described in great detail in the Handbook and in Sakaki's guide. Be sure to read it.

For this laptop I will use the following /etc/portage/make.conf file:

FILE /etc/portage/make.confDell Latitude 7480's make.conf file.
# These settings were set by the catalyst build script that automatically
# built this stage.
# Please consult /usr/share/portage/config/make.conf.example for a more
# detailed example.
MAKEOPTS="-j4 -l4"
USE="elogind wayland sway swaybg swayidle swaylock swaymsg swaynag wallpapers \
    alsa flac sound-server vulkan \
    networkmanager -ppp -wext \
    -doc -npm -systemd -gnome -kde -handbook -neon -gtk -gtk-doc -plasma -X
    -pulseaudio -coreaudio \
    -bluetooth -aac -aptx -geolocation -geoip -dvd -ipv6 \
    -smartcard -quicktime -3df -3dfx -cups \
    -nvidia -ibm -ios -ipod"


COMMON_FLAGS="-march=skylake -O2 -pipe"


# NOTE: This stage was built with the bindist Use flag enabled

# This sets the language of build output to English.
# Please keep this setting intact when reporting bugs.

CPU_FLAGS_X86="aes avx avx2 f16c fma3 mmx mmxext pclmul popcnt rdrand sse sse2 sse3 sse4_1 sse4_2 ssse3"

    rsync:// \ \
    ... additional output suppressed ... \"

Some notes:

  • MAKEOPTS="-j4 -l4" and EMERGE_DEFAULT_OPTS="-j4 -l3.6" are due to the laptop having 4 cores.
  • COMMON_FLAGS="-march=skylake -O2 -pipe" is due to the CPU architecture.
  • LLVM_TARGETS="ARM RISCV" is for Rust on embedded.
  • The list of GENTOO_MIRRORS can be obtained by mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf
This configuration file (with slight variations) can be be downloaded by
livecd ~ #cd /mnt/gentoo/etc/portage
livecd ~ #mv make.conf.1 make.conf
The raw text is a snapshot, and might be out of date, and cannot be andjusted for all targets and purposes, so feel free to edit it to your liking.

Later on more configuration files will be downloaded from the configs repository, which may not fit exactly, but with a minor variation of parameters should be OK. More configurations of Portage will be described in the relevant section.

Gentoo ebuild repository

You can get it from the configs repository or from what comes in default. So, either:

livecd ~ #mkdir --parents /mnt/gentoo/etc/portage/repos.conf
livecd ~ #cd /mnt/gentoo/etc/portage/repos.conf


livecd ~ #mkdir --parents /mnt/gentoo/etc/portage/repos.conf
livecd ~ #cd /mnt/gentoo/etc/portage/repos.conf
livecd ~ #cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

Copy DNS information

livecd ~ #cp --dereference /etc/resolv.conf /mnt/gentoo/etc/

Copy wpa_supplicant information

If installing via WiFi, copy the /etc/wpa_supplicant/wpa_supplicant-wlp2s0.conf:

livecd ~ #mkdir /mnt/gentoo/etc/wpa_supplicant
livecd ~ #cp /etc/wpa_supplicant/wpa_supplicant-wlp2s0.conf /mnt/gentoo/etc/wpa_supplicant/


Get the hardware information

It is useful to know ahead of time what hardware the system is running on, as well as which drivers are being used. This will help a lot with the kernel configuration.

To do so:

livecd ~ #lsmod > /mnt/gentoo/modules
livecd ~ #lspci -nnk > /mnt/gentoo/lspci
livecd ~ #grep -i codec /proc/asound/*/codec* > /mnt/gentoo/sound

Mounting the necessary filesystems

livecd ~ #mount --types proc /proc /mnt/gentoo/proc
livecd ~ #mount --rbind /sys /mnt/gentoo/sys
livecd ~ #mount --make-rslave /mnt/gentoo/sys
livecd ~ #mount --rbind /dev /mnt/gentoo/dev
livecd ~ #mount --make-rslave /mnt/gentoo/dev
livecd ~ #mount --bind /run /mnt/gentoo/run
livecd ~ #mount --make-slave /mnt/gentoo/run

Entering the new environment

Go to the mounting point:

livecd ~ #cd /mnt/gentoo

Chroot in:

livecd /mnt/gentoo #chroot /mnt/gentoo /bin/bash

Source the profile:

livecd / #source /etc/profile
livecd / #export PS1="(chroot) $PS1"
If the unspeakable happens, and the Gentoo installation is interrupted from this point, it _should_ be possible to resume the installation from this point again. Start from mounting the partitions, along with the DNS/WiFi information and re-enter chroot environment. This is also useful for fixing bootloader or kernel issues. See chroot for more information.

Mounting the /boot partition from the USB stick

It is necessary to mount the /boot partition while in /chroot so that when compiling the kernel and installing the bootloader, they will be saved there.


(chroot) livecd / #mount /dev/sdc1 /boot

Configuring Portage

Installing an up-to-date Portage tree

Check that you still have a network connection while in chroot:

(chroot) livecd / #ping -c3

With that, to have a baseline snapshot of Portage we will sync it twice - once to get the baseline with the webrsync protocol, and once more with the more effective rsync protocol (note that there is no vi/vim/nvim in chroot, only nano:

(chroot) livecd / #nano -w /etc/portage/repos.conf/gentoo.conf

And choose the webrsync protocol:

FILE /etc/portage/repos.conf/gentoo.confSwitching to rsync
sync-type = webrsync
# sync-type = rsync

And sync Portage:

(chroot) livecd / #emaint sync --auto
>>> Syncing repository 'gentoo' into '/var/db/repos/gentoo'...
 * Using keys from /usr/share/openpgp-keys/gentoo-release.asc
 * Refreshing keys from keyserver ...                                    [ ok ]
Fetching most recent snapshot ...
... further output suppressed ...
The above command will update all repositories whose auto-sync value (in /etc/portage/repos.conf/<reponame>.conf) has been set to yes — at this point in the install, that refers only to the gentoo repo.

Now, edit the gentoo.conf file again to use the more efficient rsync protocol:

(chroot) livecd / #nano -w /etc/portage/repos.conf/gentoo.conf

And choose the webrsync protocol:

FILE /etc/portage/repos.conf/gentoo.confSwitching to rsync
# sync-type = webrsync
sync-type = rsync

Issue (again):

(chroot) livecd / #emaint sync --auto
Please heed the request that is displayed when syncing - do not do too frequent syncs (as in more than once a day) to avoid putting stress on the servers.
Notice that there are news entries - we will deal with those later.

Setting the Profile

To see which profiles are available:

(chroot) livecd / #eselect profile list
  [1]   default/linux/amd64/17.1 (stable)
  [2]   default/linux/amd64/17.1/selinux (stable)
... additional output suppressed ...
  [15]  default/linux/amd64/17.1/no-multilib (stable) *
  [16]  default/linux/amd64/17.1 (stable)
... additional output suppressed ...
  [21]  default/linux/amd64/17.1/desktop/gnome (stable)
  [22]  default/linux/amd64/17.1/desktop/gnome/systemd (stable)
... furnther output suppressed ...

Note that the asterisk (*) denotes the selected profile. Note that the no-multilib profile is already selected. Do note, that changing profiles after the fact is a very tedious and complex task, so it is better to choose the correct version and stick with it.

If the no-multilib profile is not selected, choose the no-multilib profile:

(chroot) livecd / #eselect profile set N

Where n is the number of the profile.

Set up the correct timezone

(chroot) livecd / #echo Europe/Vienna > /etc/timezone
(chroot) livecd / #emerge --config sys-libs/timezone-data

Generating the correct locale

(chroot) livecd / #nano -w /etc/locale.gen
FILE /etc/locale.genAppend the following locales to the file (example only, adjust as needed)
en_US.UTF-8 UTF-8
It is strongly recommended to have at least one UTF-8 locale in the list.

Next, we must run locale-gen to create the locales, based on the information in the /etc/locale.gen file:

(chroot) livecd / #locale-gen

Assuming that completes successfully, you then must then specify the default locale to use. Find the system list with:

(chroot) livecd / #eselect locale list
  [1]   C
  [2]   C.utf8
  [3]   POSIX
  [4]   en_US.utf8
  [5]   C.UTF8 *
  [ ]   (free form)


(chroot) livecd / #eselect locale set N

Where n is the index of en_US.utf8.

Now, reload your environment:

(chroot) livecd / #env-update && source /etc/profile && export PS1="(chroot) $PS1"

Setting up the Post-boot keymap (optional)

This applies only if you want to have a different keymap (Dvorak) in my case for use post-boot, so that you will be able to type commands correctly when typing directly at your machine's keyboard.

(chroot) livecd / #nano -w /etc/conf.d/keymaps

and edit the keymap=... line, to cite the string you just found. For example, in my case:

FILE /etc/conf.d/keymapsSet the keymap as required
The virtual console keymap here does not replace that which we will subsequently set up for early-boot use in the initramfs (which is necessary to allow correct entry of the LUKS password); see the following section (TODO: Write and link).

Informing Portage of Processor-Specific features (optional)

If your processor differs from the one that I use through this tutorial, you might want to edit the CPU_FLAGS_X86 in /etc/portage/make.conf.

This is strictly optional: setting CPU_FLAGS_X86 can result in more efficient code in many cases, but, if you wish to build code for redistribution to others in binary form, you should skip this step, and leave it as-is (since, unless those users also have a machine with exactly the same processor feature set as you, your distributed binaries may crash on execution).

If you do want to set CPU_FLAGS_X86, first emerge the /proc/cpuinfo query tool (we'll use --oneshot here, to avoid adding it to your @world set):

(chroot) livecd / #emerge --verbose --oneshot app-portage/cpuid2cpuflags

Now, run the tool and note its output (yours may well differ from the below, which is taken from the Panasonic CF-AX3):

(chroot) livecd / #cpuid2cpuflags
CPU_FLAGS_X86: aes avx avx2 fma3 mmx mmxext popcnt sse sse2 sse3 sse4_1 sse4_2 ssse3


(chroot) livecd / #nano -w /etc/portage/make.conf

Then copy the flags output by cpuid2cpuflags-x86 into the existing CPU_FLAGS_X86="mmx mmxext sse sse2" definition (replacing mmx mmxext sse sse2); for our example:

FILE /etc/portage/make.confModifying the CPU_FLAGS_X86 for more efficient compiled code
CPU_FLAGS_X86="aes avx avx2 fma3 mmx mmxext popcnt sse sse2 sse3 sse4_1 sse4_2 ssse3"

(Your values will most likely differ) Leave the rest of the file as-is. Save and exit nano.

Updating the @world set

More information about the @world set.

At this point, it is wise to update the system's @world set so that a base can be established.

This following step is necessary so the system can apply any updates or USE flag changes which have appeared since the stage3 was built and from any profile selection:

(chroot) livecd / #emerge --ask --verbose --update --deep --newuse --with-bdeps=y @world

This long command can be shortened to (and with the t switch:

(chroot) livecd / #emerge -atvuDN --with-bdeps=y @world

If there are no issues, apply the suggested update with y.

This will likely take a long time, so it is good to make sure that the laptop is plugged.

Install vi/vim/nvim/helix


(chroot) livecd / #emerge -avt neovim helix
helix will require the Rust packages with it as dependecies, which take a while to compile. Make sure to have the laptop plugged.

Update configurations with dispatch-conf

Whether or not emerge warns you that you have configuration files that need updating as a result of the above update, it is good hygiene to run:

(chroot) livecd / #dispatch-conf

If the keymap was set to Dvorak, dispatch conf will try to revert it to "us". Don't accept this change by pressing z for zap-new.

Kernel configuration and compilation

This chapter is the analogue of the Handbook's "Configuring the Linux kernel" page and Sakaki's "Configuring and Building the Kernel" page. Go read them for a good understanding of what is up.

Allow necessary licenses for linux-firmware

(chroot) livecd / #mkdir /etc/portage/package.license
(chroot) livecd / #echo "sys-kernel/linux-firmware linux-fw-redistributable no-source-code" >> /etc/portage/package.license/linux-firmware

Emerge tools hardware discovery and kernel configuration

Here we will emerge a number of packages which will help us to compile the kernel: linux-firmware, gentoo-sources, pciutils and usbutils.

(chroot) livecd / #emerge -avt linux-firmware gentoo-sources pciutils usbutils lshw installkernel

eselecting the kernel

To see if the kernel from the previous section was installed run

(chroot) livecd / #eselect kernel list
Available kernel symlink targets:
  [1]   linux-6.3.5-gentoo

Select it:

(chroot) livecd / #eselect kernel set 1
Available kernel symlink targets:
  [1]   linux-6.3.5-gentoo *

Check that the symlink is correct:

(chroot) livecd / #readlink -v /usr/src/linux

Configuring the kernel

Configuring the kernel depends very much on the hardware, therefore take a look at the auxilliary files that were created before. Therefore, read them, and take note of the relevant drivers.

In the case of this laptop, some of the drivers of interest are:

Device Make/model Vendor/Product ID Status Driver Baked in/module
Ethernet Intel Corporation Ethernet Connection (4) I219-LM (rev 21) 8086:15d7 Works e1000e [*]
Wireless Intel Corporation Wireless 8265 / 8275 (rev 78) 8086:24fi Works iwlwifi [M]
Keyboard ... ... Works i8042, atkbd [M]

TODO: Add these ones (and additional hardware) to the chart as well.

  • rtsx_pci
  • i2c_i801 (i801_smbus)
  • snd_hda_intel
  • pcieport
  • ahci
  • intel_lpss_pci (intel_lpss)
  • xhci_pci
  • kvm_intel
  • hwmon

Some of these are hardware specific to this laptop, some are generic.

The kernel's configuration file is located in /usr/src/linux, so make sure you are in the correct repository:

(chroot) livecd / #cd /usr/src/linux

Grab the latest available .config_<kernel_version> that is in the configs repository:

(chroot) livecd /usr/src/linux #mv .config_6.3.4 .config

And use the menuconfig utility to breath life into the kernel configuration file:

(chroot) livecd /usr/src/linux #make menuconfig
Aleternatively, you can use
(chroot) livecd /usr/src/linux #make nconfig

This should load all the settings from the kernel configuration file into neatly packed, sorted menus and entries. To make sure that the necessary drivers are included in the kernel, not in order, and may be doubles, follow the following pages:

Misc. stuff:

  • As it is a no-multilib setup:
KERNEL Binary emulations
Binary Emulations --->
  [ ] IA32 Emulation

Make sure to include the ciphers into the kernel compilation. In this case Serpent. Also you need to enable `CONFIG_CRYPTO_USER_API_SKCIPHER`.


Make sure that the booting USB stick is mounted at /boot, as this is where the kernel files will go. If not mounted, they will appear in the regular filesystem's /boot directory:

(chroot) livecd /usr/src/linux #mount /dev/sdc1 /boot

One last thing before compiling - to compress the image lz4 is required. It may or may not be present in the installed packages, therefore, to install it:

(chroot) livecd /usr/src/linux #emerge -avt app-arch/lz4

Then compile the kernel:

(chroot) livecd /usr/src/linux #make -j4 && make modules_install -j4

To copy the kernel image to /boot/ issue:

(chroot) livecd /usr/src/linux #make install
When changing mode from built-in to modular or vice-versa, make clean is required.

Make sure that the kernel files are present in /boot (only kernel relevant files are displayed):

(chroot) livecd /usr/src/linux #ls -ahl /boot
drwxr-xr-x  2 root root 4.0K May 21 14:20 ./
drwxr-xr-x 22 root root 4.0K May 21 13:34 ../
-rw-r--r--  1 root root 123K May 21 14:20 config-6.3.5-gentoo
-rw-r--r--  1 root root 5.7M May 21 14:20
-rw-r--r--  1 root root  14M May 21 14:20 vmlinuz-6.3.5-gentoo

Initramfs configuration

An initramfs must be used to decrypt and mount the root partition. This can be done in a number of ways, here dracut will be used.

Emerge dracut and its auxilliary packages.

(chroot) livecd /usr/src/linux #echo "sys-fs/lvm2 lvm" >> /etc/portage/package.use/lvm2
(chroot) livecd /usr/src/linux #emerge -avt dracut btrfs-progs lvm2 cryptsetup app-crypt/gnupg dosfstools
In the first command, lvm2 has a specific USE key enabled.

Make sure that the booting USB stick is mounted at /boot, as this is where the initramfs will go. If not mounted, they will appear in the regular filesystem's /boot directory:

(chroot) livecd /usr/src/linux #mount /dev/sdc1 /boot

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

FILE /etc/dracut.confMinimum required components to decrypt LUKS volumes using dracut
add_dracutmodules+=" crypt crypt-gpg dm rootfs-block "
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.

Once Dracut is configured, a new initramfs can be generated by running:

(chroot) livecd /usr/src/linux #dracut
Dracut writes the file to /boot by default, therefore be sure that the USB drive is mounted.

If the initramfs is being generated for a kernel other than the currently active one, --kver must be used:

(chroot) livecd /usr/src/linux #dracut --kver 6.1.28-gentoo

This can happen in a situation when the kernel version in the Gentoo Live CD differs from the emerged sys-kernel/gentoo-sources in the kernel compilation process.

Possible kernel versions can be found by using
(chroot) livecd /usr/src/linux #ls -ahl /lib/modules

Make sure that the relevant files appeared in /boot:

(chroot) livecd /usr/src/linux #ls -ahl /boot
drwxr-xr-x  2 root root 4.0K May 21 14:20 ./
drwxr-xr-x 22 root root 4.0K May 21 13:34 ../
-rw-r--r--  1 root root  14M May 21 14:40 initramfs-6.3.5-gentoo

Configuring the system

This section is pararllel to the Configuring the system from the Gentoo Handbook and the following page from Sakaki's guide.

fstab configuration

For consistent volume mounting, labels and UUIDs must be used. Recall:

(chroot) livecd /usr/src/linux #lsblk -o name,uuid
NAME           UUID
└─sda1         <long_string_sda1>
  └─crypt      < ... additional output supressed ... >
    ├─vg0-root < ... additional output supressed ... >
    ├─vg0-var  < ... additional output supressed ... >
    └─vg0-home < ... additional output supressed ... >
└─sdc1         <short_string_boot_usb>

From here only the UUID of sdc1 (bootable USB stick) is required, as the other filesystems use a label (which was defined earlier).

To avoid typing their UUIDs, append the lsblk -o name,uuid to /etc/fstab:

(chroot) livecd /usr/src/linux #lsblk -o name,uuid >> /etc/fstab

Edit the file accordingly:

FILE /etc/fstab

GRUB configuration

Emerge grub with the device-mapper USE flag.

(chroot) livecd /usr/src/linux #echo "sys-boot/grub device-mapper" >> /etc/portage/package.use/grub
(chroot) livecd /usr/src/linux #emerge -avt grub

Edit the grub configuration file's line (no quotes needed on the UUIDs):

FILE /etc/default/grubEncrypted root with dracut initramfs and a GPG encrypted key file crypt_key.luks.gpg on /dev/sdc1

With that done issue:

(chroot) livecd /usr/src/linux #mkdir -p /boot/grub
(chroot) livecd /usr/src/linux #grub-mkconfig --output /boot/grub/grub.cfg
(chroot) livecd /usr/src/linux #grub-install --target=x86_64-efi --efi-directory=/boot --removable

Networking information

Create the hostname:

(chroot) livecd /usr/src/linux #echo <fancy_name> > /etc/hostname

Emerge wpa_supplicant:

(chroot) livecd /usr/src/linux #emerge -avt wpa_supplicant

Root password

Create a password for root:

(chroot) livecd /usr/src/linux #passwd

User account

Create a new user, add it to groups and set its password:

(chroot) livecd /usr/src/linux #useradd -m -G users,wheel,audio -s /bin/bash <username>
(chroot) livecd /usr/src/linux #passwd <username>

Removing the stage3 tarball

Once the system boots and working, the stage3 tarball can be removed:

(chroot) livecd / #rm /stage3-*.tar.*


At this stage a working (and minimal) system that can work by itself is built. To test it out exit the chroot environment, reboot the machine, and unplug the Gentoo Live UBS stick.


If things go wrong - worry not. It is possible to continue from the middle and troubleshoot through the Gentoo Live CD - mount the USB boot stick (as it contains the crypt_key), unlock the encrypted device, mount the partitions, chroot into it, and continue from the problematic point.