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.1
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.
Gather these items before beginning with the guide.
- Any random laptop or assembled assortment of PC parts2
- 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.3 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.4 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
# Format the partitions
# First create the mount point if it does not exist
# 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
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.
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'
# Verify that you have a connection
# 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.5
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)
Overlays6 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 emerging7 the correct musl versions of packages for your musl-based build.
Apply the Ban List
Create a file called 'crapolade'8
/etc/portage/package.mask/crapolade and include in it asciilifeform's ban list:
# Create this file at /etc/portage/package.mask/crapolade
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.9
In addition to the output of
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
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.10
# Launch the config UI, you will make all your changes here
#Compile the kernel
make && make modules_install
# Copies the kernel and config to /boot
Building the Initramfs
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)
/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.11 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 work12 or your just don't like LILO for some reason then you can use GRUB.
Option One: LILO
emerge -av sys-boot/lilo
/etc/lilo.conf and adjust the values to match your system. Then run
lilo to install the bootloader.
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
# Enable EFI
# Re-enter the chroot
# 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.
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
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.
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
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
# Try starting the service again
rc-service wpa_supplicant start
To make the kernel module load at boot, create the following file:
You can now use
wpa_cli to control your wireless interface. First try scanning for available networks.
# Scan for networks
# Wait a few seconds then view 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:
Copy the entire block and add it to the config at
/etc/wpa_supplicant/wpa_supplicant.conf. Also add
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'
Save the config, then use
wpa_cli again to load the config and list saved networks.
# Reload the config
# List saved 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
emerge -av app-admin/sudo
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
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.
- 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. [↩]
- 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. [↩]
- 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. [↩]
- 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. [↩]
- Unless you exit the chroot. [↩]
- Now called "ebuild repositories". [↩]
- Installing [↩]
- You can call it whatever you want but this name fits. [↩]
- 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. [↩]
- Although don't worry too much about optimization at this point, you can always slim the kernel later on. [↩]
- There may be others, I don't know. [↩]
- 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. [↩]