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.