User:Dimonade/Installations
Personal reminders about installation specifics that I might otherwise forget.
Introduction
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
TODO
1. Add dvorak layout to boot password.
2. Add kernel update section.
Preparation
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 gentoo.org -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
Iface MTU RX-OK RX-ERR RX-DRP RX-OVR TX-OK TX-ERR TX-DRP TX-OVR Flg 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:
/etc/wpa_supplicant/wpa_supplicant-wlp2s0.confctrl_interface=/run/wpa_supplicant
update_config=1
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
At this point the wpa_supplicant config file will have the following appended:
/etc/wpa_supplicant/wpa_supplicant-wlp2s0.confwpa_supplicant with network information.ctrl_interface=/run/wpa_supplicant
update_config=1
network={
ssid="NETWORK_NAME"
#psk="NETWORK_PASSWORD"
psk=verylongstring
}
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 gentoo.org (or any other website of your choice):
livecd ~ #ping gentoo.org -c3
PING gentoo.org (151.101.213.91) 56(84) bytes of data. 64 bytes from ... (151.101.213.91): 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:
'"`UNIQ--pre-00000007-QINU`"'
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.
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):nPartition 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):wThe 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):nPartition 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):tSelected 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 vg0livecd ~ #lvcreate -L 64G -n var vg0livecd ~ #lvcreate -l 100%FREE -n home vg0Format 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
<TODO>
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
sdb
... 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:
/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"
EMERGE_DEFAULT_OPTS="-j4 -l3.6"
ACCEPT_KEYWORDS="~amd64"
VIDEO_CARDS="intel"
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"
LINGUAS="en_US"
ACCEPT_LICENSE="-* @FREE"
INPUT_DEVICES="libinput"
COMMON_FLAGS="-march=skylake -O2 -pipe"
ABI_X86="64"
LLVM_TARGETS="ARM RISCV"
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
FCFLAGS="${COMMON_FLAGS}"
FFLAGS="${COMMON_FLAGS}"
# NOTE: This stage was built with the bindist Use flag enabled
PORTDIR="/var/db/repos/gentoo"
DISTDIR="/var/cache/distfiles"
PKGDIR="/var/cache/binpkgs"
# This sets the language of build output to English.
# Please keep this setting intact when reporting bugs.
LC_MESSAGES=C
CPU_FLAGS_X86="aes avx avx2 f16c fma3 mmx mmxext pclmul popcnt rdrand sse sse2 sse3 sse4_1 sse4_2 ssse3"
GENTOO_MIRRORS="https://ftp.belnet.be/pub/rsync.gentoo.org/gentoo/ \
http://ftp.belnet.be/pub/rsync.gentoo.org/gentoo/ \
rsync://ftp.belnet.be/gentoo/gentoo/ \
http://ftp.fi.muni.cz/pub/linux/gentoo/ \
... additional output suppressed ...
https://ftp.uni-hannover.de/gentoo/ \
https://mirror.isoc.org.il/pub/gentoo/"
Some notes:
MAKEOPTS="-j4 -l4"andEMERGE_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/portagelivecd ~ #mv make.conf.1 make.confLater 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.conflivecd ~ #cd /mnt/gentoo/etc/portage/repos.confor:
livecd ~ #mkdir --parents /mnt/gentoo/etc/portage/repos.conflivecd ~ #cd /mnt/gentoo/etc/portage/repos.conflivecd ~ #cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.confCopy 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_supplicantlivecd ~ #cp /etc/wpa_supplicant/wpa_supplicant-wlp2s0.conf /mnt/gentoo/etc/wpa_supplicant/Chrooting
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/moduleslivecd ~ #lspci -nnk > /mnt/gentoo/lspcilivecd ~ #grep -i codec /proc/asound/*/codec* > /mnt/gentoo/soundMounting the necessary filesystems
livecd ~ #mount --types proc /proc /mnt/gentoo/proclivecd ~ #mount --rbind /sys /mnt/gentoo/syslivecd ~ #mount --make-rslave /mnt/gentoo/syslivecd ~ #mount --rbind /dev /mnt/gentoo/devlivecd ~ #mount --make-rslave /mnt/gentoo/devlivecd ~ #mount --bind /run /mnt/gentoo/runlivecd ~ #mount --make-slave /mnt/gentoo/runEntering 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.
then:
(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 gentoo.org -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:
/etc/portage/repos.conf/gentoo.confSwitching to rsyncsync-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:
/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
/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)
Issue:
(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:
/etc/conf.d/keymapsSet the keymap as requiredkeymap="dvorak"
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
Issue:
(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:
/etc/portage/make.confModifying the CPU_FLAGS_X86 for more efficient compiled codeCPU_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
Installing:
(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
linux-6.3.5-gentoo
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 #wget https://gitlab.com/dimonade/configs/-/raw/master/usr/src/linux/.config_6.3.4
(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:
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`.
Compilation
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 System.map-6.3.5-gentoo -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:
/etc/dracut.confMinimum required components to decrypt LUKS volumes using dracutadd_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
sda
└─sda1 <long_string_sda1>
└─crypt < ... additional output supressed ... >
├─vg0-root < ... additional output supressed ... >
├─vg0-var < ... additional output supressed ... >
└─vg0-home < ... additional output supressed ... >
sdc
└─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:
/etc/fstab'"`UNIQ--pre-0000002F-QINU`"'
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):
/etc/default/grubEncrypted root with dracut initramfs and a GPG encrypted key file crypt_key.luks.gpg on /dev/sdc1'"`UNIQ--pre-00000032-QINU`"'
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.*
Rebooting
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.
Troubleshooting
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.