Skip to content

1. Introduction

Disclaimer

This installation guide, called "guide" in the following, builds upon the official Gentoo Linux installation handbook.

It's written with great care. Nevertheless, you are expected not to blindly copy&paste commands! Please, understand what you are going to do and adjust commands if required!

Even with the whole codeblock being a no-brainer, some codeblocks need to be copied and pasted line-by-line. In this case, a copy button won't be offered and you'll see a note saying "copy&paste one command after the other". A copy button also won't be shown for codeblocks containing sample output. They start with "❯ ".

Unless otherwise specified, all commands are executed as root.

RSS feed

You can subscribe to the RSS feed on Git tags to be notified of new stable states of the doc.

Documentation State

If I have sufficient time, I plan to conduct a test install around every 3-4 months to ensure that the documentation still works as expected. Some challenging aspects of this guide might not be covered due to time constraints, e.g. the build of non-binary kernels. I open issues for bugs, that I find and that are not yet mitigated in a tagged commit, on this page.

The latest test install has been conducted on March 30th-31st 2024 with "SystemRescue 11.00 for amd64" and:

  • the following stage3 which you might still find on this mirror or one of the mirrors mentioned here: 

    [root@sysrescue ~]# ls -1 /mnt/gentoo/stage3-amd64-hardened-systemd-20240329T230405Z.tar.xz*
/mnt/gentoo/stage3-amd64-hardened-systemd-20240329T230405Z.tar.xz
/mnt/gentoo/stage3-amd64-hardened-systemd-20240329T230405Z.tar.xz.asc

  • the following repo (link to commit "283d5461f53e571a1e7015124319b837ac64a5ca": 

    [root@sysrescue ~]# cat /mnt/gentoo/var/db/repos/gentoo/metadata/timestamp.commit
283d5461f53e571a1e7015124319b837ac64a5ca 1711844402 2024-03-31T00:20:02+00:00

You can find some info on the repo's Git mirrors here.

GnuPG Public Key

You can find information on my GnuPG public key in my Codeberg profile README!

Running the documentation locally (recommended)

I recommend checking out the doc's repository, verifying the OpenPGP signature of the latest commit and running the doc website locally with mkdocs serve. This prevents any MITM attack. Installation of "Material for MkDocs" is described in the repo's README.md. Beware, that I use Git tags to apply version numbers to Git commits that I deem stable.

Developer Contacts

You can contact me under "duxsco" at Libera Chat or OFTC if I am online. I am also on Mastodon.

1.1. Technologies

The guide results in a system that is/uses:

  • Secure Boot: All EFI binaries and unified kernel images are signed.
  • Measured Boot: systemd-cryptenroll or clevis is used to check the system for manipulations via TPM 2.0 PCRs.
  • Fully encrypted: Except for ESP(s), all partitions are LUKS encrypted.
  • RAID: Except for ESP(s), btrfs and mdadm based RAID are used for all partitions if the number of disks is ≥2.
  • Rescue system: A customised SystemRescue supports optional SSH logins and provides a convenient chroot.sh script.
  • Hardened Gentoo Linux for a highly secure, high stability production environment (link).
  • SELinux (optional) provides Mandatory Access Control using type enforcement and role-based access control (link).

1.2. System Requirements

Beside official hardware requirements, the guide has additional ones:

  • Secure Boot: It builds heavily on "secure boot". Without that, "measured boot" cannot be used. Make sure that the system is in "setup mode" in order to be able to add your custom "secure boot" keys. In next chapter 2. Live-CD Environment, we'll check whether "setup mode" is enabled.
  • TPM 2.0 is required for "measured boot".
  • systemd: The guide requires the use of systemd for "measured boot" to work without restrictions. Clevis may be an option if you want to stay with OpenRC. But, I haven't tested this. Alternatively, you can take a look at my older documentation which, however, doesn't support "measured boot" and isn't maintained by me anymore.
  • x86_64 Architecture: To keep things simple, the guide presumes that you intend to install on a x86_64 system. This is the only architecture that has been tested by me! And, it's the only architecture still actively supported by SystemRescue. SystemRescue is used for the rescue system with its custom chroot.sh script.

1.3. SSH Connectivity

After completion of this guide, optional SSH connections will be possible to the following systems using SSH public key authentication:

ssh -p 50022 david@<IP address>

ssh -p 50023 root@<IP address>

1.4. Disk Layout

Independent ESPs are created one for each disk to provide for redundancy, because there is the risk of data corruption with the redundancy provided by mdadm RAID (further info: 5.1 ESP on software RAID1). Except for ESPs, btrfs or mdadm based RAID 1 is used for all other partitions on a dual- or multi-disk setup with RAID 5, RAID 6 and RAID 10 being further options for the swap device. The 2nd partition doesn't make use of btrfs RAID due to limitations of SystemRescue.

four disks

three disks

two disks

single disk

1.5. LUKS Key Slots

On the "rescue" partition, LUKS key slots are set as follows:

  • 0: Rescue password

On all other LUKS volumes, LUKS key slots are set as follows: