Installation Quicknotes

Installation resources

Get to the chroot

Enable networking:

Preparing the disks:

  • lsblk

  • parted -a optimal /dev/sda

  • using parted (from handbook or Sakaki’s guide with LVM, LUKS, EFI boot)

    • print or just p to print the current partition table

    • make a new partition table (destroys entire disk):

      mklabel gpt

    • set units to work in with e.g. unit mib, unit gib, or unit s for sectors. Also need an s suffix on numbers for working with sectors.

    • make partitions
      • mkpart primary START END (in whatever units)
      • mkpart primary fat32 1 1024 (for an EFI boot partition)
      • name 1 efiboot
      • set 1 boot on (see here and here)


    if the installation media isn’t booted with EFI, then ‘/sys/firmware/efi` will not be properly populated and confuse the grup installation later on.


    “For completeness, the BIOS boot partition is needed when a GPT partition layout is used with GRUB2 in PC/BIOS mode. It is not required when booting in EFI/UEFI mode.”

  • make the filesystems and mount:
    • mkfs.fat -F 32 /dev/sda1 (see here in the handbook about using EFI.)
    • mkfs.ext4 /dev/sda3
    • mount /dev/sda3 /mnt/gentoo
    • mkdir -p /mnt/gentoo/boot
    • mount /dev/sda1 /mnt/gentoo/boot

install stage3

  • ensure that the system time is correct. It is okay if it is still in UTC - we’ll fix the timezone later.

  • download the tarball:
    • browse to it with links:


      releases –> amd4 –> autobuilds

    • or get it directly:
    • and the verification signatures
      • wget -c
      • wget -c
  • move the tarball to /mnt/gentoo

  • unpack the tarball:

    tar xvpf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner

enter the chroot

  • preconfigure mirrors for the new system
    • mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf (interactive selection)
    • mirrorselect -c USA -s3 -b10 -D && cp /etc/portage/make.conf /mnt/gentoo/etc/portage (choose the 3 fastest USA mirrors)
  • mount the filesystems
    • mount -t proc /proc /mnt/gentoo/proc
    • mount -R /sys /mnt/gentoo/sys
    • mount -R /dev /mnt/gentoo/dev
    • mount --make-rslave /mnt/gentoo/sys
    • mount --make-rslave /mnt/gentoo/dev
  • cp -L /etc/resolv.conf /mnt/gentoo/etc
  • chroot /mnt/gentoo /bin/bash
  • source /etc/profile
  • export PS1="(chroot) ${PS1}"

Configure/build the system

configure the build options:

  • mkdir -p /etc/portage/repos.conf
  • cp /usr/share/portage/config/repos.conf /etc/portage/repos.conf/gentoo.conf to set up the repositories. (and see here for more about the sync system)
  • nano /etc/portage/make.conf
    • COMMON_FLAGS="-march=native -02 -pipe
    • MAKEOPTS="-j2"
    • PORTAGE_TMPDIR="/dev/shm"
    • PORTAGE_TMPFS="/dev/shm"
  • might also have to add none   /dev/shm    tmpfs   rw,nosuid,nodev,relatime 0 0 to /etc/fstab to remove the noexec option to allow portage to work in the tmpfs.

install a snapshot and update:

  • emerge-webrsync to get the latest snapshot of the portage tree
  • emerge --sync to bring the portage tree up to date

configure the build options for the system



build the system

  • eslect profile list/set

    “A profile is a building block for any Gentoo system. Not only does it specify default values for USE, CFLAGS, and other important variables, it also locks the system to a certain range of package versions. These settings are all maintained by Gentoo’s Portage developers.”

    gentoo wiki on profiles

  • emerge --ask --verbose--update --deep --newuse @world

  • here, we can go ahead and install vim, tmux, zsh, git

initial system configuration

  • set the timezone:

    echo "America/New_York" > /etc/timezone
    emerge --config sys-libs/timezone-data
  • configure locale (localization guide and the utf8 article):

    vim /etc/locale.gen
    en_US ISO-8859-1
    en_US.UTF-8 UTF-8
    eselect locale list/set
    env-update && source /etc/profile

configure/build the kernel

  • emerge --ask sys-kernel/gentoo-sources
  • cd /usr/src/linux
  • make localyesconfig
  • make && make modules_install
  • make install
  • cp /boot/vmlinux-<version>-gentoo /boot/EFI/BOOT/BOOTX64.EFI (if using EFI boot)

If we’re booting straight from EFI, make sure that the following are configured:

Processor type and features  --->
  [*] EFI runtime service support
  [*]   EFI stub support
  [ ]     EFI mixed-mode support
  [*] Built-in kernel command line

And maybe using root=PARTUUID= is preferable. Then use blkid and do something like:

Processor type and features  --->
  [*] Built-in kernel command line

To ensure that wireless firmware can be loaded (firmware will be installed later on), make sure that the drivers are built as modules:

Device Drivers  --->

        [*] Network device support  --->

        --- Network device support
        [*]   Wireless LAN  --->

            --- Wireless LAN
            [ ]   mac80211-based legacy WDS support
            [ ]   ADMtek devices
            [ ]   Atheros/Qualcomm devices
            [ ]   Atmel devices
            [ ]   Broadcom devices
            [ ]   Cisco devices
            [*]   Intel devices
            < >     Intel PRO/Wireless 2100 Network Connection
            < >     Intel PRO/Wireless 2200BG and 2915ABG Network Connection
            < >     Intel Wireless WiFi 4965AGN (iwl4965)
            < >     Intel PRO/Wireless 3945ABG/BG Network Connection (iwl3945)
            <M>     Intel Wireless WiFi Next Gen AGN - Wireless-N/Advanced-N/Ultimate-N (iwlwifi)
            <M>       Intel Wireless WiFi DVM Firmware support
            <M>       Intel Wireless WiFi MVM Firmware support
                      Debugging Options  --->
            [ ]   Intersil devices

filesystem information

Edit /etc/fstab with either device names or UUIDs as given by the blkid command. Note that the /boot partition doesn’t necessarily have to be present/mounted.


Edit /etc/conf.d/hostname to set the hostname.

  • emerge -a --noreplace net-misc/netifrc

  • emerge -a dhcpcd wpa_supplicant

  • vim /etc/conf.d/net gets config_wlp2s0="dhcp"

  • add hostname to /etc/hosts`

  • vim /etc/wpa_supplicant/wpa_supplicant.conf:

    # The below line not be changed otherwise wpa_supplicant refuses to work
    # Ensure that only root can read the WPA configuration
    # Let wpa_supplicant take care of scanning and AP selection
    # Simple case: WPA-PSK, PSK as an ASCII passphrase, allow all valid ciphers
      psk="very secret passphrase"
      # The higher the priority the sooner we are matched
  • rc-update add wpa_supplicant default

see here for information on wireless networking in gentoo.

probably also need firmware for iwlwifi.

  • emerge linux-firmware
  • and make the kernel options modules (see the kernel config section above).

install utilities

miscellaneous configuration

  • set the root password
  • check /etc/rc.conf
  • check /etc/conf.d/hwclock

install utilities

  • emerge syslog-ng logrotate cronie mlocate e2fsprogs dosfstools parted
  • rc-update add syslog-ng default
  • rc-update add cronie default

bootloader (non-EFI booting)

the default grub from the handbook

  • emerge -av sys-boot/grub:2
  • be sure that GRUB_PLATFORMS="efi-64" shows up in the output before emerging. If not, then enable with echo 'GRUB_PLATFORMS="efi-64"' >> /etc/portage/make.conf
  • mount the EFI system partion (has “esp” flag in parted -l /dev/sda output)
  • grub-install --target=x86_64-efi --efi-directory=/boot
  • grub-mkconfig -o /boot/grub/grub.cfg

final configuration

add a user

  • useradd -m -G users,wheel,audio,video -s /bin/zsh larry
  • passwd larry

set up the console keymap

  • use showkey to get the keycode numbers of the key(s) of interest
  • edit/copy whatever keymap in /usr/share/keymaps[/i386/qwerty]
  • OpenRC:
    • make sure that /etc/conf.d/keymaps points at the file with the desired map
    • /etc/init.d/keymaps restart
  • systemd:
    • edit /etc/vconsole.conf to point at the map
    • FIXME presumably restart some service

set the console resolution

  • enter the grub shell and use videoinfo to get the supported modes
  • set e.g. GRUB_GFXMODE=1366x768 in /etc/default/grub and reboot

Early configuration

useful packages

  • gentoolkit portage-utils esearch bash-completion zsh-completions gentoo-bashcomp gentoo-zsh-completions mlocate

if using zsh for root, put at least this into ~/.zshrc

autoload -U compinit promptinit compinit promptinit; prompt gentoo

Dual Booting (e.g. Ubuntu)

(coming soon)

for starters, see the tip box in the grub configure section. (grub-mkconfig)

consider sys-boot/os-prober for Detect other operating systems

Ubuntu 20.04 after Gentoo

This was an odd experiment. I had super vanilla (no lvm, normal grub, etc) gentoo installed on /dev/sda3, with its /boot and ESP on /dev/sda1. I then dd if=/dev/sda3 of=/dev/sda4, and copied the /boot from /dev/sda1 to the /boot directory on /dev/sda4. This gave me two identical gentoos, even with the same UUIDs in /etc/fstab (since they come from the filesystem).

The ubuntu installer asked me about installing beside multiple other oses, but the option it gave me for automatic drive formatting didn’t look reasonable. So I did the advanced setup myself. Here, I selected /dev/sda5 as a physical lvm partition for encryption and set a passphrase. Then I place root on it as ext4. The installer complained that since it was encrypted, it needed a separate /boot, so I placed this on /dev/sda2 as ext4.

This resulted in ubuntu placing a new EFI entry first in the bios, and presenting a grub menu with ubuntu, and gentoo on /dev/sda4. Both of these boot fine. I can boot gentoo on /dev/sda3 by entering the bios boot selection and picking the “gentoo” option, which is now second in the list.


  • Based on another experiment, the ubuntu installer insisted on having a separate EFI system partition from /boot (even though this isn’t required when you’re not PC/BIOS booting GPT), so even though I gave it a separate /boot parition, it used one of the other gentoo /boot partitions that was marked for both boot and ESP - it wrote to the /boot/EFI directory.

  • Ubuntu’s bootloader is booting sda4 gentoo because it can find the /boot easily, and it needs at least the kernel and maybe the efi info from it.

  • Ubuntu can boot /dev/sda4 gentoo because Ubuntu’s bootloader is ignoring the grub config in /boot of /dev/sda4.

  • I’m not completely sure how other parts of the system are getting confused by the identical UUIDs, but presumably the device argument to the kernel at boot time is enough to settle this.

  • There seem to be two ways to easily dual-boot these two (ubuntu/gentoo):

    • The os-prober utility from within ubuntu finds both gentoos. However, the 30_os-prober script is only generating an entry for /dev/sda4 gentoo in /boot/grub/grub.cfg in ubuntu. Maybe I can also configure grub the grub config in ubuntu to include the /dev/sda1,3 gentoo. The simplest way seems to be to use the /etc/grub.d/40_custom entry and then rerun something like grub-mkconfig - just copy the menu entries from the original gentoo’s /boot/grub/grub.cfg.
    • One could just go ahead and let any OS install itself onto unused parition(s), and then use the bios EFI selector to order and pick. This also implies that partioning needs to include at least a separate boot/esp partition for each OS (especially if it is encrypted).

Encrypted drive

This is done with dm-crypt and LUKS. Setting up the drives is straightforward. But then an initramfs is also needed so that the kernel can decrypt the root drive when booting.

(coming soon)

Rescue partitions and media

consider dev-libs/libisoburn for Create rescue media (grub-mkrescue)

manual backups

One could use the following procedure:

  1. tar up the host sysem (from live media / not when it is booted)

  2. untar from live media onto a new partition as if it were a mega stage3

    • remember to use tar xvpjf backup.tar.bz2 --xattrs-include='*.*' --numeric-owner

3. change uuids as needed in /etc/fstab, etc. 3. change options (like GRUB_GFXMODE) in /etc/default/grub 4. reconfigure/reinstall the bootloader with e.g.

  • to update the UUIDs etc. in the grub config: grub-mkconfig -o /boot/grub/grub.cfg
  • to update the UEFI entry for this OS: grub-install --target=x86_64-efi --efi-directory=/boot
  1. on the thinkpad, there is no option in the bios to manually add UEFI boot entries, but the grub-install seems to have populated it (and put it first). On the dell, the UEFI entry was not present even after the grub-install, so I added it manually (it even let me browse to the efi file on the two detected ESPs) in the bios setup and it booted just fine.
  2. update the hostname in /etc/hosts and /etc/conf.d/hostname

UEFI boot (no bootloader)

In fact, even though grub is typically used to boot EFI systems, it can be done straight from the bios as described in Sakaki’s guide.

Essentially, there needs to be an EFI type partition with a FAT32 filesystem. Most firmwares can be configured with the path to the image, but the default is \EFI\BOOT\BOOTX64.

The efibootmgr utility can be used to manage UEFI boot entries. It is not a bootloader, but it rather interacts with the EFI firmware of the system itself. The Gentoo Handbook has a short section on setting this up at Alternative 2: efibootmgr.

For more information, check out:

Systemd / Gnome 3.28+

This can be done as a conversion after the installation - really at any time.

(coming soon)

Notes on Using Portage

useful tools:

  • app-portage/gentoolkit is useful (equery, euse, revdep-rebuild, among others).
  • dispatch-conf (included)
  • app-portage/esearch
  • portage-utils
  • bash-completion
  • zsh-completions
  • gentoo-bashcomp
  • gentoo-zsh-completions
  • mlocate

The world file at /var/lib/portage/world shows all packages installed by the user

The default gentoo package tree lives at /var/db/repos/gentoo. Besides all of the ebuilds, the profiles live here as well (including make.defaults, use.desc, use.local.desc, etc.).

saving space

  • firmware

    edit /etc/portage/savedconfig/sys-kernel/linux-firmware-* and remove the blobs that aren’t needed. Leaving just intel-* and iwlwifi-* resulted in going from 521M to 144M.

  • distfiles

    clear out DISTDIR where portage keeps the downloaded source tarballs. By default, this is at /var/cache/distfiles. There is also an eclean utility as part of gentoolkit, but I have no experience with it yet.

  • linux kernel sources

    clear out the old sources in /usr/src/linux-*. Watch out; portage will try to do this for you automatically when it merges a new source tree.

USE flags

sources of truth for the system:

  • descriptions of all global[/local] USE flags known to the system are at /var/db/repos/gentoo/profiles/use[.local].desk
  • emerge -pv packagename shows what USE flagss were/will be used to build packagename

utilities for working with USE flags (shortcuts)

  • FIXME: quse, euse, equery portageq

the complete USE flag index (global and local)

and some hints and utilities about working with USE flags.

Here is an explanation of some REQUIRED_USE expressions.


see this DRM driver list for which cards are supported by each driver.

and this feature list for which driver to use with which intel chipset generation. There is also a lot of useful information on that same page about configuring kernel options, drivers and USE flags for X, etc.

tips and tricks

If you want to enable Portage completions and Gentoo prompt, emerge app-shells/gentoo-zsh-completions and add:

autoload -U compinit promptinit
promptinit; prompt gentoo

to your ~/.zshrc Also, if you want to enable cache for the completions, add zstyle ':completion::complete:*' use-cache 1 to your ~/.zshrc


if /bin/ping gives an “Operation not permitted” when run by an unpriviledged user (but works as root), then setcap cap_net_raw=ep /bin/ping.

tmux split characters

If tmux shows ‘x’/’q’ for vertical/horizontal bars when splitting panes, then there is a mismatch between the terminal and terminfo being used by tmux.

The core cause of this is utf8 being set incorrectly. One thing to test is to force tmux to draw unicode characters by starting with tmux -u.

The real way to set this is to set to a utf8 locale. eselect locale list/set and a new login shell should be sufficient. The gentoo wiki articles are thorough, see utf8 on gentoo wiki and localization/guide.

lcd brightness

At least in the console, we can do this manually. First, test if the kernel has the necessary support:

grep BACKLIGHT /boot/config

and then trying writing values into /sys/class/backlight/[something]/brightness.

Other Gentoo

check out gentoo prefix to use gentoo in other OSes.