Gentoo¶

Installation Quicknotes ¶

Installation resources

Get to the chroot ¶

Enable networking:

ifconfig -a
net-setup wlp3s0
(details for manual wifi setup at Sakaki’s guide)
ping google.com

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)
Caution

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.

Note

“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:
  
  links https://www.gentoo.org/downloads/mirrors
  
  releases –> amd4 –> autobuilds
- or get it directly:
  
  get the release file name from http://distfiles.gentoo.org/releases/amd64/autobuilds/latest-stage3-amd64.txt
  
  wget -c http://distfiles.gentoo.org/releases/amd64/autobuilds/YYYYMMDDThhmmssZ/stage3-amd64-YYYYMMDDThhmmssZ.tar.xz
- and the verification signatures
  
  wget -c http://distfiles.gentoo.org/releases/amd64/autobuilds/YYYYMMDDThhmmssZ/stage3-amd64-YYYYMMDDThhmmssZ.tar.xz.CONTENTS
  
  wget -c http://distfiles.gentoo.org/releases/amd64/autobuilds/YYYYMMDDThhmmssZ/stage3-amd64-YYYYMMDDThhmmssZ.tar.xz.DIGESTS.asc
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

Error

FIXME

set the ACCEPT_LICENSE options
set package options in /etc/portage/package.use/

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

locale-gen
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
  (root=/dev/sda2)

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

Processor type and features  --->
  [*] Built-in kernel command line
  (root=PARTUUID=adf55784-15d9-4ca3-bb3f-56de0b35d88d)

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.

networking ¶

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
ctrl_interface=/var/run/wpa_supplicant

# Ensure that only root can read the WPA configuration
ctrl_interface_group=0

# Let wpa_supplicant take care of scanning and AP selection
ap_scan=1

# Simple case: WPA-PSK, PSK as an ASCII passphrase, allow all valid ciphers
network={
  ssid="simple"
  psk="very secret passphrase"
  # The higher the priority the sooner we are matched
  priority=5
}

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

It is good to verify all of the downloads (stage3 snapshot, portage tree snapshot, and each package source download) to make sure that they haven’t been tampered with (as far as the signing author is concerned).

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.

Suspicions

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:

tar up the host sysem (from live media / not when it is booted)
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

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.
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+¶

arch’s wiki page is quite good.

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

(coming soon)

Notes on Using Portage ¶

https://wiki.gentoo.org/wiki/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.

make.conf ¶

https://wiki.gentoo.org/wiki//etc/portage/make.conf

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.

VIDEO_CARDS ¶

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
compinit
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

Unsorted ¶

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.

graham lopez

Navigation

Related Topics

Gentoo¶

Installation Quicknotes ¶

Get to the chroot ¶

Configure/build the system ¶

configure/build the kernel ¶

filesystem information ¶

networking ¶

install utilities ¶

bootloader (non-EFI booting)¶

final configuration ¶

Early configuration ¶

More installation security ¶

Dual Booting (e.g. Ubuntu)¶

Ubuntu 20.04 after Gentoo ¶

Encrypted drive ¶

Rescue partitions and media ¶

manual backups ¶

UEFI boot (no bootloader)¶

Systemd / Gnome 3.28+¶

Notes on Using Portage ¶

saving space ¶

make.conf ¶

USE flags ¶

VIDEO_CARDS ¶

tips and tricks ¶

Unsorted ¶

tmux split characters ¶

lcd brightness ¶

Other Gentoo ¶