Gentoo Install
This installaion doc is / includes:
- OpenRC based
- Distribution Kernel based
- Sensible standard options
- Basic useful stuff you would probably want to have
- Alternatives and in depth details in separate doc
This doc covers three main disk formatting / partitioning options:
- UEFI / GPT
- BIOS / GPT
- BIOS / MBR
NOTE - All disk device names and IP addresses will probably be different on your system. Make sure to check and adjust these for your specific system. Also, the same is true for locale and timezone info.
Install Media and Getting Started
Download the installation media: https://www.gentoo.org/downloads/
The exact links will change as the version numbers change. You will want to select one of these:
- Minimal Installation CD
- LiveGUI USB Image
The Minimal Install CD works great but the LiveGUI USB Image will make copying and pasting easier.
- Boot using the install media.
PRO TIP - For easier copy and pasting. If you have a second system to work from, you can actually enable SSHD and SSH the host, while booting from the install media. This also works with the Minima Installation CD. This is great for situations where you don’t want to run the install directly from the host you are installing it on. This will allow you to easily copy and paste commands.
After booting from the install media:
rc-service sshd start # start SSHD
ip a # check the IP
passwd # make sure the root password is set
ssh root@192.168.3.209 # connect ( do this from the other host )
Disk Partitioning and Filesystems
Check whether your system uses BIOS or UEFI:
[ -d /sys/firmware/efi ] && echo UEFI || echo BIOS
UEFI / GPT
NOTE - EFI partition could be mounted on either /boot/efi or /efi. We are going with /efi. This seems to be the “default” choice in the docs. There are some advantages to using /boot/efi and I may update these instructions to use that in stead in the future. There are potential issues that could pop up and we show you a work around for this further on in the instructions.
| Gdisk Type | Partition | Mount | Size | FS |
| EF00 | EFI | /efi | 128MB | FAT32 |
| 8200 | swap | ….. | 1024MB or more | ….. |
| root | / | remaining space | XFS |
Partition disk:
gdisk /dev/sda
With these options:
o, y # new disklabel
n,1,[default],+128M,EF00 # EFI
n,2,[default],+1024MB,8200 # swap
n, 3, [default], [default], [default] # root
w, y # write
Format disks:
mkfs.vfat -F 32 /dev/sda1
mkswap /dev/sda2 && swapon /dev/sda2
mkfs.xfs /dev/sda3
Mount disks:
mkdir -p /mnt/gentoo
mount /dev/sda3 /mnt/gentoo
mkdir /mnt/gentoo/efi # EFI only
mount /dev/sda1 /mnt/gentoo/efi # EFI only
BIOS / GPT
| Gdisk Type | Partition | Mount | Size | FS |
| EF02 | BIOS Boot | ….. | 2MB | ….. |
| 8200 | swap | ….. | 1024MB or more | ….. |
| root | / | remaining space | XFS |
Partition disk:
gdisk /dev/sda
With these options:
o, y # new disklabel
n,1,[default],+2M,EF02 # BIOS Boot
n,2,[default],+1024MB,8200 # swap
n, 3, [default], [default], [default] # root
w, y # write
Format disks:
mkswap /dev/sda2 && swapon /dev/sda2
mkfs.xfs /dev/sda3
Mount disks:
mkdir -p /mnt/gentoo
mount /dev/sda3 /mnt/gentoo
BIOS / MBR
| Gdisk Type | Partition | Mount | Size | FS |
| 8200 | swap | ….. | 1024MB or more | …. |
| root | / | remaining space | XFS |
Partition disk:
fdisk /dev/sda
With these options:
o # new MBR disklabel
swap, n, p, default, default, +4G, t, default, 82 # swap
root /, n, p, default, default, default # root
w
Format disks:
mkswap /dev/sda1 && swapon /dev/sda2
mkfs.xfs /dev/sda2
Mount disks:
mkdir -p /mnt/gentoo
mount /dev/sda3 /mnt/gentoo
Network - Temp Setup for Installation
The network is probably already working at this point but if it isn’t you can use the below steps.
Check interfaces:
ifconfig # show interfaces
ifconfig -a # show all interfaces ( even when down )
ip addr # show interfaces ( newer tool )
Missing interfaced? - It may be possible to manually load network drivers.
Find,load, and verify network modules:
ls /lib/modules/`uname -r`/kernel/drivers/net # show modules
modprobe pcnet32 # insert modules
ls /sys/class/net # list interfaces
ifconfig eth0 # check interface
Configure interface with DHCP:
dhcpcd eth0 # receive DHCP info
Alternatively, use this tool to setup the network:
net-setup eth0
Another alternative for static IP bring the interface up manually. Bring the interface up with the desired IP info and add the default gateway.
ifconfig eth0 192.168.0.3 broadcast 192.168.0.255 netmask 255.255.255.0 up
route add default gw 192.168.0.1
Point to the DNS servers you want:
nano -w /etc/resolv.conf
nameserver 8.8.8.8
nameserver 8.8.4.4
- See the network section at the end of this document for wifi setuo instructions.
Tarball and Mirrors
cd /mnt/gentoo
Find the most updated Stage3 tarball here: https://www.gentoo.org/downloads/
- Choose the right tarball ( OpenRC vs systemd, desktop vs no desktop )
Download ( Note the path will be different / changed. Find the updated path at the link above. ):
wget https://distfiles.gentoo.org/releases/amd64/autobuilds/current-stage3-amd64-openrc/stage3-amd64-openrc-20231022T164658Z.tar.xz
## wget https://distfiles.gentoo.org/releases/amd64/autobuilds/20231029T164701Z/stage3-amd64-desktop-openrc-20231029T164701Z.tar.xz
Unpack:
tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner
Find mirrors to use here ( or use the tool below ): https://www.gentoo.org/downloads/mirrors/
Nice tool for selecting mirrors. You probably won’t need to install it. It should already be installed. If it isn’t add the tool with this command before running it.
emerge app-portage/mirrorselect
Select the mirror:
mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf
Alternatively, mirrors can be configured directly here:
/mnt/gentoo/etc/portage/make.conf
# mirrors selected in order
GENTOO_MIRRORS="https://mirrors.mit.edu/gentoo-distfiles/"
Create repo configs:
mkdir --parents /mnt/gentoo/etc/portage/repos.conf
cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf
Copy the current DNS server setting before chrooting:
cp --dereference /etc/resolv.conf /mnt/gentoo/etc/
Mount Filesystems and Chroot
Mount filesystems and chroot:
cd /mnt/gentoo
mount --types proc /proc /mnt/gentoo/proc
mount --rbind /sys /mnt/gentoo/sys
mount --make-rslave /mnt/gentoo/sys
mount --rbind /dev /mnt/gentoo/dev
mount --make-rslave /mnt/gentoo/dev
mount --bind /run /mnt/gentoo/run
mount --make-slave /mnt/gentoo/run
chroot . /bin/bash
source /etc/profile
For EFI, this partition should still be mounted but if it isn’t you need to make sure that it is re-mounted:
mkdir /efi
mount /dev/sda1 /efi
Check and set time if needed. Can leave this until later if the date/time are OK.
date
emerge net-misc/chrony
chronyd -q
Update and Portage Setup
Probably won’t need anything changed but here is an example:
nano /etc/portage/make.conf
MAKEOPTS="-j4 -l4"
-j # jobs
-l # load average
Default behavior is to set to smaller of these two values:
- number of CPU threads
- 2G of ram for every job ( ex -j6 needs 12 GiB )
Install latest snapshot ( repo info ). This command works well behind firewalls and conserves bandwidth:
emerge-webrsync
Show profiles:
eselect profile list
Select a profile. Use the same profile version as the stage tarball. Upgrading a profile version requires special instructions.
eselect profile set 2 # select the number you want
Emerge @world:
emerge -avuDN @world
Show current system wide variable:
portageq envvar ACCEPT_LICENSE
Overriding system wide default from profile:
nano /etc/portage/make.conf
ACCEPT_LICENSE="-* @BINARY-REDISTRIBUTABLE"
Probably also want:
nano /etc/portage/make.conf
ACCEPT_LICENSE="-* @BINARY-REDISTRIBUTABLE @EULA"
Users and Important Tools
Set root password:
passwd
Add a user:
useradd -g users -G wheel,portage,audio,video,usb,cdrom -m user1
passwd user1
Install VIM:
emerge -vq vim
Fstab
NOTE - You can also identify disks by UUID instead of device name ( ex. sda1 ).
For EFI:
nano /etc/fstab
/dev/sda1 /efi vfat defaults 0 2
/dev/sda2 none swap sw 0 0
/dev/sda3 / xfs defaults,noatime 0 1
/dev/cdrom /mnt/cdrom auto noauto,user 0 0
For MBR:
nano /etc/fstab
/dev/sda1 none swap sw 0 0
/dev/sda2 / xfs defaults,noatime 0 1
/dev/cdrom /mnt/cdrom auto noauto,user 0 0
Locale, Timezone, etc
View supported locales:
cat /usr/share/i18n/SUPPORTED
Set locales:
nano /etc/locale.gen
C.UTF8 UTF-8
en_US ISO-8859-1
en_US.UTF-8 UTF-8
Generate and verify locales:
locale-gen # generate locales
locale -a # verify
Select locale:
eselect locale list
eselect locale set 3 # choose en_US.UTF-8 UTF-8
OR manually select locale:
nano /etc/env.d/02locale
LANG="en_US.UTF-8"
LC_COLLATE="C.UTF-8"
Reload env stuff:
env-update && source /etc/profile && export PS1="(chroot) ${PS1}"
ls -l /usr/share/zoneinfo/*/*
Set timezone:
echo "America/New_York" > /etc/timezone
emerge --config sys-libs/timezone-data
Kernel
Install firmware for NICs, GPUs, and more. Also includes AMD microcode.
emerge --ask sys-kernel/linux-firmware
Install Intel microcode ( optional on AMD systems ).
emerge --ask sys-firmware/intel-microcode
Three main kernel approaches:
- Full automation approach: Distribution kernels
- Hybrid approach: Genkernel
- Full manual approach
We are covering dist kernels here.
Distribution kernels ( dist kernels )
Setting this will run grub-mkconfig automatically:
nano /etc/portage/make.conf
USE="grub"
Install kernel package:
emerge --ask sys-kernel/installkernel-gentoo
Install distribution kernel:
emerge --ask sys-kernel/gentoo-kernel
Install kernel sources:
emerge -av sys-kernel/gentoo-sources
Show and set which kernel sources are linked:
eselect kernel list
eselect kernel set 1 # only change if needed
ls -l /usr/src/linux
Bootloader
Install GRUB Package
EFI:
echo 'GRUB_PLATFORMS="efi-64"' >> /etc/portage/make.conf
emerge --ask sys-boot/grub
BIOS:
echo 'GRUB_PLATFORMS="pc"' >> /etc/portage/make.conf
emerge --ask sys-boot/grub
Install GRUB to Disk
EFI:
grub-install --target=x86_64-efi --efi-directory=/efi
EFI - Alternative
Specifying “–removeable” will install the boot loader into the default location instead of a specific directory (/boot/efi/EFI/BOOT/BOOTX64.EFI). This is good for installing on removable media or systems with a broken/messed up UEFI. If you do this it won’t rely on the EFI variables stored in NVRAM/EEPROM. A potential side effect could be that it might not show as a boot option presented by the firmware.
If you mounted your EFI partition on /efi and not on /boot/efi then you will need to create the link below. If you mounted it on /boot/efi then you don’t need to create the link.
cd /boot
ln -s /efi efi
grub-install --target=x86_64-efi --removable
BIOS:
grub-install /dev/sda
GRUB Configs
Install OS Prober before generating GRUB configs if you want to detect other OSes:
emerge -a sys-boot/os-prober
I ran into an issue with config files not being overwritte while trying to intall the package. Without going into too much detail, you can fix it with this:
cd /etc/portage/package.use
diff ._cfg0000_zz-autounmask zz-autounmask
mv ._cfg0000_zz-autounmask zz-autounmask
Also, make sure that OS Prober is enabled:
nano /etc/default/grub
GRUB_DISABLE_OS_PROBER=false
Generate GRUB configs:
grub-mkconfig -o /boot/grub/grub.cfg
Network
Set hostname:
echo test1 > /etc/hostname
Hosts file;
nano /etc/hosts
127.0.0.1 test1.example.org test1 localhost
192.168.0.5 steve.example.org steve
192.168.0.6 greg.example.org greg
You might want to check and update your resolv.conf file. The below example uses Google’s pulbic DNS servers which is good in most cases. If you prefer, you can set them to something else. You can also just let DHCP set this.
nano /etc/resolv.conf
nameserver 8.8.8.8
nameserver 8.8.4.4
Public DNS:
- Google’s 8.8.8.8 or
- Cloudflare’s 1.1.1.1
Install useful network packages that are usually good to have ( maybe exclude wifi packages on a server ):
emerge net-misc/dhcpcd sys-apps/iproute2 net-wireless/wpa_supplicant net-wireless/iw net-wireless/wireless-tools
Start and Enable DHCP:
rc-update add dhcpcd default
rc-service dhcpcd start
Wifi
-
Install Wifi packages ( command in section above )
-
For WPA/WPA2 see our doc on WPA Supplicant
ip link # find device name
iw dev wlp9s0 link # check connection
Activate interface:
ip link set dev wlp9s0 up
Connect to open network, connect using hex wep key, connect using ASCII wep key:
iw dev wlp9s0 connect -w GentooNode
iw dev wlp9s0 connect -w GentooNode key 0:d:1234123412341234abcd
iw dev wlp9s0 connect -w GentooNode key 0:some-password
Netifrc (OpenRC)
Instead of manually starting the dhcpd service ( as shown above ) we can use Netifrc to configure networking with either static or dynamic IPs.
Full example in this file:
cat /usr/share/doc/netifrc-*/net.example.bz2
Install Netifrc:
emerge --ask --noreplace net-misc/netifrc
Static IP configuration:
nano /etc/conf.d/net
config_eth0="192.168.0.2 netmask 255.255.255.0 brd 192.168.0.255"
routes_eth0="default via 192.168.0.1"
DHCP configuration:
nano /etc/conf.d/net
config_eth0="dhcp"
Start networking at boot:
cd /etc/init.d
ln -s net.lo net.eth0
rc-update add net.eth0 default
Finish Install
- You can perform all of the steps in the “Basic Standard Components” section before exiting and restarting if you prefer. You can also leave them until the end and just keep following this in order if you like.
Exit chroot environment and reboot:
exit
cd
umount -l /mnt/gentoo/dev{/shm,/pts,}
umount -R /mnt/gentoo
reboot
- Reomve installation media before sysetm boots back up.
Remove tarballs:
rm /stage3-*.tar.*
Basic Standard Components
These are standard, normal components that I would generally expect to be present on most systems. These are usually a good idea to install. You could also install these before restarting the host if you like
Remote access:
- Root login not allowed for ssh by default
- Options: ssh and serial console
If you already enabled sshd but did it before chrooting, you will want to enable it again now. Do this first before everything else for convenience. Note that the IP address may have changed if you are using DHCP.
OpenRC - Enable and start SSHD
rc-update add sshd default
rc-service sshd start
OpenRC - Agetting for serial consoles:
nano -w /etc/inittab
# SERIAL CONSOLES
s0:12345:respawn:/sbin/agetty 9600 ttyS0 vt100
s1:12345:respawn:/sbin/agetty 9600 ttyS1 vt100
PCI Utils
Nice to have:
emerge -av pciutils
Logging:
Three logging options for OpenRC::
| app-admin/sysklogd | good for beginners, works out of the box |
| app-admin/syslog-ng | more advanced, needs configuration |
| app-admin/metalog | more advanced |
Install / setup sysklogd:
emerge --ask app-admin/sysklogd
rc-update add sysklogd default
Cron
OpenRC Cron Options:
| sys-process/cronie | based on original cron |
| sys-process/dcron | lightweight |
| sys-process/fcron | more functionality |
| sys-process/bcron | security focused |
Install / setup cronie:
emerge --ask sys-process/cronie
rc-update add cronie default
File Indexing
File indexing with mlocate:
emerge --ask sys-apps/mlocate
Shell Completion
Shell completion for bash ( includes Gentoo specific commands and others ):
emerge --ask app-shells/bash-completion
Chrony / NTP
Setup Chrony for time keeping:
emerge --ask net-misc/chrony # install
rc-update add chronyd default # enable with OpenRC
FS Tools
| XFS | sys-fs/xfsprogs |
| ext4 | sys-fs/e2fsprogs |
| VFAT (FAT32, …) | sys-fs/dosfstools |
| Btrfs | sys-fs/btrfs-progs |
| ZFS | sys-fs/zfs |
| JFS | sys-fs/jfsutils |
emerge sys-fs/xfsprogs sys-fs/e2fsprogs sys-fs/dosfstools sys-fs/btrfs-progs sys-fs/zfs sys-fs/jfsutils
Extra Device Stuff
Important for scheduler behavior with nvme drives (???):
emerge --ask sys-block/io-scheduler-udev-rules