This guide will walk you through setting up a base Gentoo system. It is intended for beginners who want to move to an operating system that gives them more control over what is installed. It will produce a reasonably sane Gentoo "daily driver" that will allow you to run TRB and other republican goodies. It will allow you to install xorg and a tiling manager without too much trouble. It will NOT be as strict as a Dulap when it comes to banning all systemdisms and other malware, so use accordingly.¹

First of all, a huge thank you to asciilifeform for producing an ultra-hygienic Gentoo and making it available to the world. Dulap remains my go-to for server applications and any box where the need for security is greater than the desire for comfort. The first part of this guide, up to the chroot, is more or less lifted directly from the Dulap construction kit.

Prerequisites

Gather these items before beginning with the guide.

• Any random laptop or assembled assortment of PC parts²
• 2 USB thumb drives, at least 2GB
• A Gentoo Stage 3 tarball: obtained here
• A Gentoo Minimal Installation CD image: obtained here

Create the Bootable USB Drive

Note the path to your copy of the Gentoo Minimal Installation CD ISO file and check the drive device that corresponds to your USB drive with fdisk -l on Linux or diskutil list on macOS. Create the bootable USB with the following command, adjusted to your ISO file and USB drive:

dd if=install-amd64-minimal-20220308T160629Z.iso of=/dev/sdb bs=4096

Obtain a Stage 3 Tarball

Select a Stage 3 tarball from the Gentoo Downloads page.³ Download it and verify the checksum. Copy it to your other USB drive. If you're working on macOS or Window you'll need to format the drive as FAT so that your Linux build can access it.

Booting From the USB Drive and Formatting the Target Drive

Boot from the bootable install disk you created in the previous step. You'll likely need to enter your BIOS and rearrange the boot order so that USB is tried first before any internal drives.⁴ Once this option is set, exit the BIOS saving your changes, the machine should boot from the USB drive.

You are now in a mini Gentoo prepared specially for installing Gentoo. You'll first need to format your target drive so that you can proceed with the install. Run fdisk -l to view your drives and verify that your main drive (where you intend to install Gentoo) is in the first position. This will be /dev/sda if it's a SATA drive and /dev/nvme0n1 if it's an NVMe drive. If it is not one of these, reboot and adjust your BIOS boot order again until it is.

Using the correct device, run the following commands:

# Set the partition scheme
parted -s /dev/sda mklabel gpt

# Create the partitions
parted -s -a optimal /dev/sda unit s mkpart boot ext3 64 262143
parted -s -a optimal /dev/sda unit s mkpart primary ext4 262144 100%

# Enable the boot flag on the first partition
parted -s -a optimal /dev/sda set 1 boot on

sync

# Format the partitions
mkfs.ext3 /dev/sda1
mkfs.ext4 /dev/sda2

sync

# First create the mount point if it does not exist
mkdir /mnt/gentoo

# Mount the main partition to a mount point of your choice, here it's '/mnt/gentoo'
mount /dev/sda2 /mnt/gentoo

Now your target drive should be ready. Try running fdisk -l to see a summary of the new partitions.

Next, connect and mount your other USB drive, the one containing the Stage 3 tarball. You can mount this one to /mnt/usb or anywhere else you choose. If you're not sure which device is the USB drive you just plugged in run fdisk -l again and find it among the list.

# Mount the USB drive at /dev/sdb2 to /mnt/usb. Change to your own values if necessary.
mount /dev/sdb2 /mnt/usb

Now run lsmod and dmesg and save the output to your USB drive with the Stage 3 tarball. You will need this information later when configuring the kernel.

lsmod > /mnt/usb/lsmodout.txt
dmesg > /mnt/usb/dmesgout.txt

Extracting the Tarball and Chroot'ing Into the New System

Navigate to the root of your new drive and extract the Stage 3 tarball.

cd /mnt/gentoo
tar xpvf /mnt/usb/stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner

After this completes you can run ls -l and you'll see your new system at home on its new drive.

Use the included net-setup tool to get network access. Then after you have a connection, copy the DNS info to the new environment.

# Run 'net-setup'
net-setup

# Verify that you have a connection
ping thebitcoin.foundation

# Copy the DNS info to the new environment
cp --dereference /etc/resolv.conf /mnt/gentoo/etc/

You are now ready to chroot into the new system.

# Mount the boot partition
mount /dev/sda1 /mnt/gentoo/boot

mount -o bind /dev /mnt/gentoo/dev
mount -o bind /proc /mnt/gentoo/proc
mount -o bind /sys /mnt/gentoo/sys
chroot /mnt/gentoo /bin/bash

You are now "inside" the new system, meaning what was previously /mnt/gentoo is now simply /. For example, ls / will display the contents of the partition at /dev/sda2 that you created earlier, not the contents of the bootable USB drive. Everything you do from here on out will affect the new system.⁵

Configuring Portage and Obtaining the Kernel Source

After chrooting, run emerge-webrsync to get a snapshot of the latest upstream repo. If you downloaded a Musl Stage 3 tarball then you will want to add the Musl overlay at this point. If not, then skip this step.

Add the Musl Overlay (skip if building a glibc-based system)

Overlays⁶ are a feature of Portage, Gentoo's package management system, that allow you to add additional packages not tracked in the main upstream repository. They can be thought of as sheets of vellum paper overlaying the default repository. They leave the original package list intact while adding one or more new packages (or versions of packages). This will be covered more in Part Two but for now—if you opted for a musl-based system—you will need to enable at least one overlay. If you opted for a glibc-based system, proceed to the next step.

# Emerge 'eselect-repository' and 'git'
emerge -av app-eselect/eselect-repository
emerge -av dev-vcs/git

# Create the config directory
mkdir -p /etc/portage/repos.conf 

# Enable and sync the 'musl' overlay
eselect repository enable musl
emaint sync -r musl

This will give you an up-to-date musl overlay, which is necessary for emerging⁷ the correct musl versions of packages for your musl-based build.

Apply the Ban List

Create a file called 'crapolade'⁸ /etc/portage/package.mask/crapolade and include in it asciilifeform's ban list:

# Create this file at /etc/portage/package.mask/crapolade

# systemdisms
sys-apps/systemd
sys-apps/systemd-tmpfiles
sys-fs/udev
virtual/tmpfiles
sys-auth/consolekit
sys-auth/polkit
sys-apps/dbus

media-video/libav
gnome-base/gconf
>=app-crypt/gnupg-2.0.22
app-accessibility/at-spi2-atk
app-accessibility/at-spi2-core
gnome-extra/polkit-gnome
dev-util/gdbus-codegen
gnome-base/dconf
>=x11-libs/gtk+-3.0.0
#>=sys-devel/gcc-5.0

The way this works is that Portage will check all entries in /etc/portage/package.mask when emerging packages and refuse to install packages that you have "masked". This also applies to packages brought in as dependencies by other packages, so it's a pretty effective way of keeping unwanted cruft out of your machine. You may have noticed that one item, >=sys-devel/gcc-5.0, is commented out. This is because any Stage 3 tarball that you download today will already include a GCC newer than 5.0, so the only result of leaving that line in would be some error spew about "Masked package already installed" every time emerge is run.

Later in this guide you will have to comment out other lines. As I mentioned in the beginning, this guide is not designed to produce a military grade Gentoo, but rather a comfortable daily driver that will run TRB and other republican software.⁹

In addition to the output of lsmod and dmesg that we saved earlier, there's another utility, lspci, available that I find useful for identifying hardware components. Emerge with:

emerge --ask --verbose sys-apps/pciutils

You will later use the output of lspci and the saved output from lsmod and dmesg to get an idea of what you'll need to enable in the kernel.

If you're on a more recent model laptop you may also need to install the Linux firmware package to enable graphics cards or wifi chips. If your laptop has Intel wifi, for example, you'll probably need this.

emerge -av sys-kernel/linux-firmware

Finally, emerge the Linux kernel source.

emerge -av sys-kernel/gentoo-sources

# Create a symlink to simplify things, change the version/filename to match what you have in /usr/src
ln -s /usr/src/linux-5.15.11-gentoo /usr/src/linux

Configuring and Building the Kernel

If this is your first time configuring a Linux kernel, which would not be unreasonable considering you're reading "A Beginner's Guide to Installing Gentoo", then it may feel a little daunting. Given the nearly endless combinations of possible hardware configurations there's also no way to create a step-by-step guide—you're on your own for this.

The strategy I would recommend going into this for the first time would be: don't overthink it and don't overdo it. There's a non-zero chance that you won't need to make any modifications at all and your kernel will boot with the defaults. Other knobs will be obvious. If you have an NVMe drive, be sure to enable support for NVMe drives. If you have an Nvidia graphics card it's probably ok to disable graphics support for other vendors, etc.¹⁰

cd /usr/src/linux

# Launch the config UI, you will make all your changes here
make menuconfig

#Compile the kernel
make && make modules_install

# Copies the kernel and config to /boot
make install

Building the Initramfs

Get genkernel to build the initramfs.

emerge --ask sys-kernel/genkernel

Build the initramfs. Be absolutely sure that the path you pass to --kernel-config points to the same config used to compile the kernel. This config should be present at /boot/config-5.15.11-gentoo (or whatever version kernel you used). If not, adjust accordingly.

genkernel --install --kernel-config=/boot/config-5.15.11-gentoo initramfs

Configure the File Systems Tab (fstab)

Edit /etc/fstab to set boot and primary disks.

# SAMPLE fstab
/dev/sda1       /boot       ext3        defaults        0 2
/dev/sda2       /           ext4        noatime,discard 0 1

Configure the Bootloader

You will have to choose a bootloader. The two main options are LILO and GRUB.¹¹ You should try to get LILO to work first, it's got a much smaller footprint than GRUB and less moving parts means less that can potentially go wrong. If you can't get LILO to work¹² or your just don't like LILO for some reason then you can use GRUB.

Option One: LILO

Emerge LILO.

emerge -av sys-boot/lilo

Edit /etc/lilo.conf and adjust the values to match your system. Then run lilo to install the bootloader.

lilo

That should be it.

Option Two: GRUB

Emerge GRUB 2.

emerge -av sys-boot/grub

Exit the chroot and enable EFI if you’re using that. If not, skip to installing GRUB.

# Exit the chroot
exit

# Enable EFI
modprobe efivars
modprobe efivarfs

# Re-enter the chroot
chroot /mnt/gentoo

Install grub.

# For EFI
grub-install --target=x86_64-efi --efi-directory=/boot --debug

# For Non-EFI (adjust device to match your system)
grub-install --target=i386-pc /dev/sda --debug

Generate the GRUB config.

grub-mkconfig -o /boot/grub/grub.cfg

Booting Your New OS

Before rebooting set a root user password. If you do not set this you will be locked out and will have to boot from your USB drive and chroot in all over again.

passwd

If you’re on a machine that only has a wireless connection you’ll also need to grab the wpa_supplicant and a DHCP client before you boot into your new system otherwise you will not have internet connectivity.

emerge -av net-wireless/wpa_supplicant
emerge -av net-misc/dhcpcd

Attempt to reboot to your newly installed Gentoo.

#Exit chroot and reboot
exit
reboot

If everything works you can log in as root with the password you set.

A Few Remaining Basics

Your system now works but before you can start having fun with it there are a few small things to take care of.

Make Your HiDPI Display Usable

If you are on a HiDPI display your console font is likely really tiny, to the point where it is practically illegible. Increase it by choosing a different font.

setfont latarcyrheb-sun32

Make this permanent by editing /etc/conf.d/consolefont and adding to boot services.

rc-update -v show | grep consolefont
rc-update add consolefont boot

See list of available fonts in /usr/share/consolefonts if you want to experiment with different options.

Enable Wireless and Connect to a WiFi Network

The wpa_supplicant replaces that little WiFi icon in the top-right corner of your old OS as the primary means of finding, selecting, and connecting to WiFi networks.

# Add 'wpa_supplicant' to the default and boot runlevels
rc-update add wpa_supplicant default
rc-update add wpa_supplicant boot

# Start the service
rc-service wpa_supplicant start

If this doesn’t work it’s likely because your kernel driver isn’t loaded.

# Load the kernel module
modprobe iwlwifi

# Try starting the service again
rc-service wpa_supplicant start

To make the kernel module load at boot, create the following file:

# /etc/modules-load.d/networking.conf
iwlwifi

You can now use wpa_cli to control your wireless interface. First try scanning for available networks.

# Scan for networks
wpa_cli scan

# Wait a few seconds then view results
wpa_cli scan_results

Note the SSID of the network you would like to connect to. To generate the WPA PSK for the network run the following command with the SSID and password of the network:

wpa_passphrase my-network-5g mynetworkpass

The output will look something like this:

network={
        ssid="my-network-5g"
        #psk="mynetworkpass"
        psk=9f1315f6253481f27965068df528064ae85e6cbb06540090c79e3817cb8f12a7
}

Copy the entire block and add it to the config at /etc/wpa_supplicant/wpa_supplicant.conf. Also add ctrl_interface and update_config knobs to the top of the file. Your file should look something like this:

# WPA Supplicant config at '/etc/wpa_supplicant/wpa_supplicant.conf'

ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel
update_config=1

network={
        ssid="my-network-5g"
        #psk="mynetworkpass"
        psk=9f1315f6253481f27965068df528064ae85e6cbb06540090c79e3817cb8f12a7
}

Save the config, then use wpa_cli again to load the config and list saved networks.

# Reload the config
wpa_cli reconfigure

# List saved networks
wpa_cli list_networks

# Select the network, where the number is the ID of the network returned by the previous command
wpa_cli select_network 0

You should now have internet access again.

Create a Non-Root User and Install 'sudo'

Now that you have an internet connection you should create a user account and install/configure sudo so that you’re not doing everything as root. First create your new user.

# Create a new user, '-m' creates a home folder for this user
useradd -m mynewuser

# Set the password for this user
passwd mynewuser

emerge -av app-admin/sudo

Configure with visudo

visudo

You can read more elsewhere about this file but an easy way to control who has sudo access is with the "sudo" group. Uncomment the line for this configuration so that it looks like:

%sudo ALL=(ALL) ALL

You can also set a longer timeout if you like (the default is only 5 minutes).

# Include this line to set the default sudo timeout to 30 minutes
Defaults env_reset, timestamp_timeout=30

Create the sudo group and add your user to the group

groupadd sudo
sudo usermod -a -G sudo mynewuser

Now you can log out of the root account with exit and log back in to your new user. Congratulations, you now have a basic working Gentoo linux machine with wireless internet access. You can now sudo emerge any package you like. In part two we’ll set up a minimal graphical environment plus some command line niceties. If you tried using this guide and noticed errors or parts that were unclear please leave feedback so that I can make improvements.

1. If you intend to build a web server or have no need for a browser or any graphical environment then I suggest following this guide to build a Dulap instead. [↩]
2. I won't bother with listing "minimum specs" because they aren't high enough to be worth mentioning and because it mostly depends on what you want to run. Gentoo isn't macOS or Windows, you don't need 4GB of RAM just for the OS. Any cheapo laptop from the last 15 years should do. If your goal is to run TRB then you need at least a 1TB SSD. [↩]
3. At this point in time, if you use a current glibc-based system you will need to create a separate chroot environment later on in order to build TRB with the rotor due to a version incompatibility. If you select a musl-based system then you will be able to build TRB just fine, with a few tweaks, but you may have a harder time running other popular programs that don't yet play nice with musl. [↩]
4. This varies by machine, depending on your motherboard. Typically F1, F11, or DEL gets you into the BIOS— the post splash screen should say which key, something like "Press F1 to enter setup". From there just keyboard navigate until you find what you're looking for. [↩]
5. Unless you exit the chroot. [↩]
6. Now called "ebuild repositories". [↩]
7. Installing [↩]
8. You can call it whatever you want but this name fits. [↩]
9. So why include the ban list in the first place? The idea is to make you think twice about what you're installing, and only unmask the bare minimum that you absolutely need. Often if you are blocked because of a masked package you can get around it by installing an older version the package you want, or manually installing an older version of the specific dependency that's asking to bring in the masked package. Or you can find another program that has similar functionality to what you want but that doesn't depend on a masked package. If you conclude that you really must have a package that is blocked on a certain masked dependency, then you can unmask only that dependency. [↩]
10. Although don't worry too much about optimization at this point, you can always slim the kernel later on. [↩]
11. There may be others, I don't know. [↩]
12. I was unable to get LILO to successfully install the bootloader on my ThinkPad but it's what I use on my FX-8350 desktop. YMMV. [↩]

This entry was posted on Saturday, March 12th, 2022 at 4:51 p.m. and is filed under gentoo, guides. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.