About gentoo-install

This script performs a reasonably minimal installation of gentoo. An EFI system is highly recommended, but legacy BIOS boot is still supported. It does everything from the ground up, including creating partitions, downloading and extracting the stage3 archive, initial system configuration and optionally installing some additional software. The script only supports OpenRC and not systemd.

The system will temporarily use sys-kernel/vanilla-kernel-bin, which should be suitable to boot most systems out of the box. I strongly recommend you to replace this kernel with a custom built one, when the system is functional. If you are looking for a way to detect and manage your kernel configuration, have a look at autokernel.

Quick start

Edit scripts/config.sh and execute ./install in any live system. This will apply the selected partitioning scheme (with confirmation), and properly install the selected stage3 gentoo system. The new system will by default use vanilla-kernel-bin as the kernel, and an initramfs generated with dracut to provide a bootable environment. The script can optionally install sshd and ansible to allow for quick setup of the new system. So when the script finishes, you can directly begin to deploy your specific setup.

Overview

Here is a quick overview of what this script does:

• Does everything minus something
• Partition disks (supports gpt, raid, luks)
• Download and cryptographically verify the newest stage3 tarball
• Extract the stage3 tarball
• Sync portage tree
• Configure the base system
  • Set hostname
  • Set timezone
  • Set keymap
  • Generate and select locale
  • Prepare zz-autounmask files for portage autounmasking
• Select best gentoo portage mirrors
• Install git (so you can add your portage overlays later)
• Install sys-kernel/vanilla-kernel-bin (temporarily, until you replace it)
  • EFI: Copy kernel to efi partition
  • EFI: Create boot entry using efibootmgr (or install syslinux for BIOS boot)
  • BIOS: Install syslinux
• Generate fstab
• Ask for a root password

Also, optionally the following will be done:

• Install sshd with secure config
• Install dhcpcd
• Install ansible, create ansible user and add authorized ssh key
• Install additional packages provided in config

Anything else is probably out of scope for this script, but you can obviously do anything later on when the system is booted. I highly recommend building a custom kernel and maybe encrypting your root filesystem. Have a look at the Recommendations section.

Install

Installing gentoo with this script is simple.

1. Boot into the live system of your choice. As the script requires some utilities, I recommend using a live system where you can quickly install new software. Any Arch Linux live iso works fine.
2. Clone this repository
3. Edit scripts/config.sh, and particularily pay attention to the device which will be partitioned. The script will ask before partitioning, but better be safe than sorry.
4. Execute ./install. The script will tell you if your live system is missing any required software.

Config

The config file scripts/config.sh allows you to adjust some parameters of the installation. The most important ones will probably be the device to partition, and the stage3 tarball name to install. By default you will get the hardened nomultilib profile without systemd.

(Optional) sshd

The script can provide a fully configured ssh daemon with reasonably good security settings. It will by default run on port 2222, only allow ed25519 keys, restrict the key exchange algorithms, disable any password based authentication, and only allow specifically mentioned users to use ssh service (none by default).

To add a user to the list of allowed users, append AllowUsers myuser to /etc/ssh/sshd_config. I recommend to create a separate group for all ssh users (like sshusers) and to use AllowGroups sshusers. You should adjust this to your preferences when the system is installed.

(Optional) Ansible

This script can install ansible, create a system user for ansible and add an ssh key of you choice to the .authorized_keys file. This allows you to directly use ansible when the new system is up to configure the rest of the system.

(Optional) Additional packages

You can enter any amount of additional packages to be installed on the target system. These will simply be passed to a final emerge call before the script is done. Autounmasking will be done automatically.

Troubleshooting

The script checks every command for success, so if anything fails during installation, you will be given a proper message of what went wrong. Inside the chroot, most commands will be executed in some kind of try loop, and allow you to fix problems interactively with a shell, to retry, or to skip the command.

Recommendations

There are some things that you probably want to do after installing the base system, or should consider:

• Read the news with eselect news read.
• Use a custom kernel (config and hardening, see kernconf), and remove vanilla-kernel-bin
• Adjust /etc/portage/make.conf
  • Set CFLAGS to -O2 -pipe -march=native for native builds
  • Set CPU_FLAGS_X86 using the cpuid2cpuflags tool
  • Set MAKEOPTS to -jN with N being the amount of threads used for building
  • Set EMERGE_DEFAULT_OPTS to -jN if you want parallel emerging
  • Set FEATURES="buildpkg" if you want to build binary packages
• Use a safe umask like umask 0077
• Edit /etc/ssh/sshd_config, change the port if you want and create a sshusers group.
• Encrypt your system using LUKS
  • Remount the root fs read-only
  • Use rsync -axHAWXS --numeric-ids --info=progress2 / /path/to/backup to safely backup the whole system including all extended attributes.
  • Encrypt partition with LUKS
  • Use rsync to restore the saved system root.

References

• Sakaki's EFI Install Guide
• Gentoo AMD64 Handbook