gentoo-install: a scripted Gentoo install with a TUI and a config file

Two audiences: people who want to try Gentoo, and people who want it scripted

The project describes itself as aspiring to be your favourite way to install Gentoo, with a smooth installation experience for both beginners and experts. You configure it either through a menuconfig-inspired interface or simply via a config file.

The audience is stated explicitly. This installer might appeal to you if you want to try Gentoo without initially investing a lot of time, or fully committing to it yet, or if you are already a Gentoo expert but want an automatic and repeatable best-practices installation.

The third paragraph of the README is the part most people will notice. The maintainers encourage everyone to install Gentoo manually, because you will learn a lot if you have not done so already. That is a rare thing for an installer to say about itself, and it tells you the tool's intended value: not teaching, but removing the tedium for people who already understand the process or who want to try it without a weekend of setup.

The project grew from a way of documenting a best-practices installation for the author, and configuration options were added as it grew to suit legacy needs. The licence is MIT and the primary language is Shell, with `configure` and `install` as the two entry point scripts at the repository root, plus `scripts/`, `contrib/`, `tests/` and `gentoo.conf.example`.

The install runs from a live environment in a handful of commands

The usage section starts from a live environment of your choice, and the recommendation is the Arch Linux live ISO, for a specific reason: the installer can then automatically download required programs or set up ZFS support on the fly. That is a real design constraint, since the installer needs tools it may not have on the running system.

The command sequence is:

pacman -Sy git  # (Archlinux) Install git in live environment, then clone:
git clone "https://github.com/oddlama/gentoo-install"
cd gentoo-install
./configure     # configure to your liking, save as gentoo.conf
./install       # begin installation

`./configure` opens the TUI configurator, and every option is explained in detail in `gentoo.conf.example` and in the help menus of that configurator. `./install` then begins the installation.

Two behaviours matter here. When installing, you are asked to review the partitioning before anything critical is done, which puts a human checkpoint in front of the one irreversible step. And the installer should be able to run without any user supervision after partitioning, but depending on the current state of the Gentoo repository you might need to intervene if a package fails to emerge, with the critical commands asking what to do in case of a failure.

There is also a chroot escape hatch. If you need to enter an installed system to fix something, for example after rebooting your live system, you can clone the installer, mount your main drive under `/mnt` and use `./install --chroot /mnt` to chroot into your system.

Seven steps, and the scope stops right after them

The installer performs a defined list of main steps, in roughly this order, with some parts depending on the chosen configuration.

First, partition disks, which is highly dependent on configuration. Then download and extract the stage3 tarball, with cryptographic verification, and from that point on it continues in a chroot. Third, set up portage with an initial rsync or git sync, running mirrorselect and creating the zz-autounmask files. Fourth, base system configuration covering hostname, timezone, keymap and locales. Fifth, install the required packages, git and the kernel among them. Sixth, make the system bootable by generating fstab, building the initramfs and creating the efibootmgr or syslinux boot entry. And seventh, ensure a minimal working system, with automatic wired networking, eix installed and the root password set, plus the optional steps of installing sshd with a secure configuration that has no password logins, and installing additional packages provided in the config.

The stated goal is just to set up a minimal Gentoo system following best practices, and anything beyond that is considered out of scope, with the exception of configuring sshd.

The post-install list in the documentation is short and specific. Read the news with `eselect news read`. Compile a custom kernel and remove `gentoo-kernel-bin`, or `gentoo-kernel` if you used `KERNEL_TYPE=source`. Adjust `/etc/portage/make.conf`, setting `CFLAGS` to `<march_native_flags> -O2 -pipe` for native builds using the `resolve-march-native` tool, and setting `CPU_FLAGS_X86` using the `cpuid2cpuflags` tool. And use a safe umask like `umask 077`.

That last item, the umask, is a small detail that reflects the project's priorities, and the note about the additional packages option makes the same point: it is recommended to keep the extra package list to a minimum, because of the quite interactive nature of Gentoo package management.

Disk layout, init system and boot mode are all configuration

The description of the project lists the supported matrix, and it is where the flexibility lives.

The most common disk layouts are supported, with file systems including ext4, ZFS and btrfs, plus additional layers such as LUKS or mdraid. Both EFI, which is recommended, and BIOS boot are supported, and the init system can be systemd or OpenRC. SSH can also be configured, to allow an automation framework such as Ansible or Fora to automate beyond system installation.

That combination is the reason this installer is more than a partition script. A Gentoo installation where the filesystem is ZFS on top of mdraid with LUKS, booting in EFI mode under OpenRC, is a configuration that a manual installation would take a long time to get right and that you would want to repeat identically across several machines. The config file is the artefact you keep, and the config file is what the TUI produces.

The optional sshd path is documented in detail, and the defaults are conservative. The script can provide a fully configured ssh daemon with reasonably good security settings: by default it only allows ed25519 keys, restricts key exchange algorithms to a reasonable subset, disables any password based authentication, and only allows root to login. You can provide keys that are written to root's `.ssh/authorized_keys`, which lets you continue your setup with your favourite infrastructure management software.

The `KERNEL_TYPE` setting is the other one worth understanding before you install. By default the installed system uses Gentoo's binary kernel distribution, `sys-kernel/gentoo-kernel-bin`, with an initramfs generated by dracut, which ensures the installed system works on common hardware configurations. Setting `KERNEL_TYPE=source` builds the kernel from source using `sys-kernel/gentoo-kernel` with the same distribution config, compiled locally.

Kernel updates are a documented manual procedure

Once the system boots, the documentation covers the maintenance task that will recur, which is updating the kernel.

The locations differ by boot mode, and the documentation gives the exact paths:

# EFI
kernel="/boot/efi/vmlinuz.efi"
initrd="/boot/efi/initramfs.img"
# BIOS
kernel="/boot/bios/vmlinuz-current"
initrd="/boot/bios/initramfs.img"

The installer provides a convenience script named `generate_initramfs.sh` in `/boot/efi/` or `/boot/bios` depending on the mode, used to generate a new initramfs for a given kernel version.

The update procedure itself is five steps. Emerge the new kernel, then `eselect kernel set <kver>`, then back up the old kernel and initramfs with `mv "$kernel"{,.bak}`, `mv "$initrd"{,.bak}`, then generate the new initramfs for that kernel with `generate_initramfs.sh <kver> "$initrd"`, and finally copy the new kernel with `cp /boot/kernel-<kver> "$kernel"` for systemd or `cp /boot/vmlinuz-<kver> "$kernel"` for openrc.

The distinction in the last step is worth noticing, because the binary name differs between the two init systems, and getting it wrong leaves you with an old kernel in place. The backup step existing at all is a reminder that this procedure is manual, and that a failed copy leaves a machine that boots the previous kernel rather than one that fails to boot.

Where this installer is the wrong choice

Three limits are real.

The first is the one the maintainers state themselves. If you are learning Gentoo, an automated installer removes exactly the part of the process that teaches you how the distribution works. The tool is good at what it does, and what it does is skip the learning.

The second is the fragility of unattended package management. The documentation is candid that the installer should run without supervision after partitioning, but that depending on the current state of the Gentoo repository you might need to intervene if a package fails to emerge. A build failure in a source-based distribution is a normal event, and an automated script that has to ask what to do at each one is an automated script with an interactive core.

The third is the scope limit. The goal is a minimal system following best practices, and everything beyond that is out of scope. There is no desktop, no package set beyond the essentials, no user account creation, and no hardening beyond the optional sshd configuration. If you want a workstation, a server with a particular role, or a machine with a specific set of services, you are going to be writing that part yourself.

The alternative to name is a manual installation following the Gentoo Handbook, which is the choice the maintainers recommend and which is the only way to get a system you fully understand. The difference in approach is that this installer encodes one person's best-practices path, generalised across disk layouts and init systems, while the manual route derives the configuration for your specific machine. For a single machine you will live with, the handbook is the better teacher. For a fleet of identical machines, a config file that produces the same result every time is worth the trade.

Editorial conclusion

Adopt gentoo-install if you want a repeatable, scripted Gentoo installation with your disk layout and init system decided in a config file rather than typed at a prompt. Do not adopt it as a learning exercise, because the project itself encourages everyone to install Gentoo manually, and do not expect it to configure anything beyond a minimal system plus optional sshd, since everything else is out of scope. Verify first that the stage3 tarball download and verification still work against the current Gentoo mirrors, and review the partitioning step before you commit to it, since that is the part the installer asks you to review.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. oddlama/gentoo-install on GitHub
4. README
5. Releases