Introduction
Installation media
Partitioning the data storage
1. Caveats
Creating and mounting filesystems
Installing a stage tarball
Chrooting
Configuring Portage
Configuring timezone
Configuring locale
1. Caveats
Installing Linux kernel
Installing system tools
Configuring system
Installing boot loader
Finalizing

Introduction

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

This document describes how to install Gentoo with systemd, btrfs on LUKS root, swap on LUKS, and systemd-boot on an amdm64 system.

This document is not a replacement for official Gentoo Handbook, you SHOULD read it before your first installation.

Installation media

You can use any installation media which contains the following:

Btrfs utilities
DOS filesystem tools
Tool to setup encrypted devices with dm-crypt

Minimal installation CD fits.

Partitioning the data storage

Partition	Size	Type
`/dev/efi_system_partition`	256–1024 MiB	EFI System
`/dev/swap_partition`	Any size	Linux filesystem
`/dev/root_partition`	Rest of data storage	Linux filesystem

You can use fdisk for partitioning.

Caveats

You SHOULD NOT use filesystem type like “Linux root (x86-64)” or “Linux swap”. There is systemd-gpt-auto-generator that automatically tries to mount that filesystems. systemd will not find there what expects.

If you want it anyway, then you MUST add systemd.gpt_auto=0 to the kernel command line parameters.

Creating and mounting filesystems

mkfs.vfat -F 32 /dev/efi_system_partition
cryptsetup luksFormat /dev/root_partition
cryptsetup open /dev/root_partition cryptos
mkfs.btrfs /dev/mapper/cryptos

ROOT=/mnt/gentoo
OPTS=defaults,compress=zstd
mount -o "$OPTS" /dev/mapper/cryptos "$ROOT"
btrfs subvolume create "${ROOT}/sv_snapshots"
btrfs subvolume create "${ROOT}/sv_roots"
btrfs subvolume create "${ROOT}/sv_roots/sv_gentoo"
for i in sv_{root,srv,usr,var}; do
    btrfs subvolume create "${ROOT}/sv_roots/sv_gentoo/${i}"
done
btrfs subvolume create "${ROOT}/sv_roots/sv_gentoo/sv_usr/sv_local"
for i in sv_{cache,games,lib,log,spool,tmp}; do
    btrfs subvolume create "${ROOT}/sv_roots/sv_gentoo/sv_var/${i}"
done
for i in sv_{AccountsService,NetworkManager,docker,libvirt,machines,portables}
do
    btrfs subvolume create \
	"${ROOT}/sv_roots/sv_gentoo/sv_var/sv_lib/${i}"
done
for i in sv_userdata{,/sv_{home,root}}; do
    btrfs subvolume create "${ROOT}/${i}"
done
umount /mnt/gentoo

mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_root" \
    /dev/mapper/cryptos "$ROOT"
mkdir -p \
    "$ROOT"/{.btrfs/snapshots,boot,home,root,srv,usr/local,var} \
    "$ROOT"/var/{cache,games,lib,log,spool,tmp} \
    "$ROOT"/var/lib/{AccountsService,NetworkManager,docker,libvirt,machines,portables}
mount /dev/efi_system_partition "${ROOT}/boot"
mount -o "${OPTS},subvol=/sv_snapshots" /dev/mapper/cryptos \
    "${ROOT}/.btrfs/snapshots"
mount -o "${OPTS},subvol=/sv_userdata/sv_home" \
    /dev/mapper/cryptos "${ROOT}/home"
mount -o "${OPTS},subvol=/sv_userdata/sv_root" \
    /dev/mapper/cryptos "${ROOT}/root"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_srv" \
    /dev/mapper/cryptos "${ROOT}/srv"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_usr/sv_local" \
    /dev/mapper/cryptos "${ROOT}/usr/local"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_cache" \
    /dev/mapper/cryptos "${ROOT}/var/cache"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_games" \
    /dev/mapper/cryptos "${ROOT}/var/games"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_log" \
    /dev/mapper/cryptos "${ROOT}/var/log"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_spool" \
    /dev/mapper/cryptos "${ROOT}/var/spool"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_tmp" \
    /dev/mapper/cryptos "${ROOT}/var/tmp"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_AccountsService" \
    /dev/mapper/cryptos "${ROOT}/var/lib/AccountsService"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_NetworkManager" \
    /dev/mapper/cryptos "${ROOT}/var/lib/NetworkManager"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_docker" \
    /dev/mapper/cryptos "${ROOT}/var/lib/docker"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_libvirt" \
    /dev/mapper/cryptos "${ROOT}/var/lib/libvirt"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_machines" \
    /dev/mapper/cryptos "${ROOT}/var/lib/machines"
mount -o "${OPTS},subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_portables" \
    /dev/mapper/cryptos "${ROOT}/var/lib/portables"
mkdir -p \
    "$ROOT"/.btrfs/snapshots/userdata/{home,root} \
    "$ROOT"/.btrfs/snapshots/roots/gentoo/{root,srv,usr/local} \
    "$ROOT"/.btrfs/snapshots/roots/gentoo/var/{cache,games,log,spool} \
    "$ROOT"/.btrfs/snapshots/roots/gentoo/var/lib/{AccountsService,NetworkManager,machines,portables}

Note that subvolumes for /srv, /var/lib/machines, and /var/lib/portables wanted by systemd¹. To view all datasets that systemd wants:

grep '^[vqQ]' /usr/lib/tmpfiles.d/*

Installing a stage tarball

ntpd -qg
cd /mnt/gentoo
wget "$stage_file"{,.asc,.sha256}
gpg --import /usr/share/openpgp-keys/gentoo-release.asc
gpg --verify *.asc
gpg --verify *.sha256
chksum="$(sha256sum *.tar.xz | cut -d' ' -f1)"
grep "$chksum" *.sha256
tar xpvf *.tar.xz --xattrs-include='*.*' --numeric-owner
echo $?  # Verify that tar unpack archive successfully.

Chrooting

mirrorselect -io >>/mnt/gentoo/etc/portage/make.conf
mkdir /mnt/gentoo/etc/portage/repos.conf
cp /mnt/gentoo/usr/share/portage/config/repos.conf \
    /mnt/gentoo/etc/portage/repos.conf/gentoo.conf
cp -L /etc/resolv.conf /mnt/gentoo/etc
mount -t proc /proc /mnt/gentoo/proc
mount -R /sys /mnt/gentoo/sys
mount --make-rslave /mnt/gentoo/sys
mount -R /dev /mnt/gentoo/dev
mount --make-rslave /mnt/gentoo/dev
mount -B /run /mnt/gentoo/run
mount --make-slave /mnt/gentoo/run
chroot /mnt/gentoo /bin/bash
source /etc/profile
export PS1="(chroot) $PS1"

Configuring Portage

emerge-webrsync
eselect news list
eselect news read
emerge -avuDN @world
mkdir /etc/portage/{package.{env,license},env}

Configuring timezone

ln -sfr /usr/share/zoneinfo/Region/City /etc/localtime

Configuring locale

/etc/locale.gen example:

en_US.UTF-8 UTF-8

Generate locales:

locale-gen

Select locale:

eselect locale list
eselect locale set "$locale"

/etc/locale.conf example:

LANG="en_US.utf8"
LC_COLLATE="C.utf8"

Reload the environment:

env-update
source /etc/profile
export PS1="(chroot) $PS1"

Caveats

You SHOULD use “C.utf8” locale for LC_COLLATE environment.

Installing Linux kernel

echo 'sys-kernel/linux-firmware @BINARY-REDISTRIBUTABLE' \
    >/etc/portage/package.license/10-linux-firmware
emerge -av sys-kernel/linux-firmware
emerge -av sys-firmware/intel-microcode  # For Intel CPUs.
emerge -av sys-kernel/installkernel-systemd-boot
emerge -av sys-kernel/gentoo-kernel-bin

Installing system tools

Installing filesystem tools:

emerge -av sys-fs/{btrfs-progs,cryptsetup,dosfstools}

Installing network tools (e. g. use iwd with systemd-networkd):

emerge -av net-wireless/iwd

/etc/systemd/network/25-wireless.network example:

[Match]
Name=wlan0

[Network]
DHCP=yes
IgnoreCarrierLoss=3s

[DHCPv4]
RouteMetric=20

[IPv6AcceptRA]
RouteMetric=20

/etc/systemd/network/20-wired.network example:

[Match]
Name=enp0s3

[Network]
DHCP=yes

[DHCPv4]
RouteMetric=10

[IPv6AcceptRA]
RouteMetric=10

Configuring system

echo "$hostname" >/etc/hostname
passwd
systemd-firstboot --prompt --setup-machine-id
systemctl preset-all

/etc/crypttab example (discard option for devices that support trim):

cryptswap	/dev/disk/by-partuuid/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX	/dev/urandom	swap,discard

/etc/fstab example:

/dev/mapper/cryptos     /                               btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_root                               0       0
/dev/mapper/cryptos     /srv                            btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_srv                                0       0
/dev/mapper/cryptos     /usr/local                      btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_usr/sv_local                       0       0
/dev/mapper/cryptos     /var/cache                      btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_cache                       0       0
/dev/mapper/cryptos     /var/games                      btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_games                       0       0
/dev/mapper/cryptos     /var/log                        btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_log                         0       0
/dev/mapper/cryptos     /var/spool                      btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_spool                       0       0
/dev/mapper/cryptos     /var/tmp                        btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_tmp                         0       0
/dev/mapper/cryptos     /var/lib/AccountsService        btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_AccountsService      0       0
/dev/mapper/cryptos     /var/lib/NetworkManager         btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_NetworkManager       0       0
/dev/mapper/cryptos     /var/lib/docker                 btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_docker               0       0
/dev/mapper/cryptos     /var/lib/libvirt                btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_libvirt              0       0
/dev/mapper/cryptos     /var/lib/machines               btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_machines             0       0
/dev/mapper/cryptos     /var/lib/portables              btrfs   defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_var/sv_lib/sv_portables            0       0
/dev/mapper/cryptos     /home                           btrfs   defaults,compress=zstd,subvol=/sv_userdata/sv_home                                      0       0
/dev/mapper/cryptos     /root                           btrfs   defaults,compress=zstd,subvol=/sv_userdata/sv_root                                      0       0
/dev/mapper/cryptos     /.btrfs/snapshots               btrfs   defaults,compress=zstd,subvol=/sv_snapshots                                             0       0
UUID=XXXX-XXXX          /boot                           vfat    defaults                                                                                0       2
/dev/mapper/cryptswap   none                            swap    sw,discard                                                                              0       0

Installing boot loader

Installing systemd-boot (and systemd cryptsetup):

echo 'sys-apps/systemd cryptsetup gnuefi' \
    >/etc/portage/package.use/10-systemd
emerge -avDU @world
bootctl install

/etc/kernel/cmdline example:

rd.luks.name="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX=cryptos" rd.luks.options=discard root=/dev/mapper/cryptos rootfstype=btrfs rootflags="defaults,compress=zstd,subvol=/sv_roots/sv_gentoo/sv_root" splash quiet ro

where XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX is UUID /dev/root_partition.

Setup initramfs:

mkdir /etc/dracut.conf.d

/etc/dracut.conf.d/compress.conf example:

compress="zstd"

Reconfigure kernel:

emerge --config "$kernel_atom"

Finalizing

Exit the chrooted environment, unmount all mounted partitions, and reboot:

exit
cd
umount -l /mnt/gentoo/dev{/shm,/pts,}
umount -R /mnt/gentoo
cryptsetup close cryptos
reboot

Enable and setup services:

systemctl enable iwd.service  # For Wi-Fi.
systemctl enable fstrim.timer  # For devices that support trim.
ln -sfr /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf

Creating a user:

useradd -mG wheel,users "$user"
passwd "$user"

Giving a power to user:

emerge -av app-admin/sudo
sed -i '/^#%wheel ALL=(ALL:ALL) ALL$/ s/#//' /etc/sudoers
cat >/etc/polkit-1/rules.d/10-admin.rules <<-EOF
    polkit.addAdminRule(function(action, subject) {
	return ["unix-group:wheel"];
    });
EOF

Removing tarball files:

rm /*.tar.xz*

Footnotes

¹ See 1, 2, and 3.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.reuse		.reuse
LICENSES		LICENSES
README.md		README.md
README.md.license		README.md.license
README.org		README.org

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Table of Contents

Introduction

Installation media

Partitioning the data storage

Caveats

Creating and mounting filesystems

Installing a stage tarball

Chrooting

Configuring Portage

Configuring timezone

Configuring locale

Caveats

Installing Linux kernel

Installing system tools

Configuring system

Installing boot loader

Finalizing

Footnotes

About

Releases

Packages

k4leg/installing_gentoo

Folders and files

Latest commit

History

Repository files navigation

Table of Contents

Introduction

Installation media

Partitioning the data storage

Caveats

Creating and mounting filesystems

Installing a stage tarball

Chrooting

Configuring Portage

Configuring timezone

Configuring locale

Caveats

Installing Linux kernel

Installing system tools

Configuring system

Installing boot loader

Finalizing

Footnotes

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Packages