User:Csfore/Blocks

For arches that support EFI

Assume all block links are prefixed with Handbook:ABC/Blocks/EFI unless it has Blocks before it, i.e. /Blocks/ABC.

Handbook:Parts/Installation/Disks

Blocks link: /Mkfs

EFI system partition filesystem

The EFI system partition () must be formatted as FAT32:

root #mkfs.vfat -F 32

Blocks link: /Mount

The ESP should also be mounted under the root partition location:

root #mkdir --parents

Handbook:Parts/Installation/Base

Blocks link: /Preparing

UEFI systems

For UEFI systems, was formatted with the FAT32 filesystem and will be used as the EFI System Partition (ESP). Create a new directory (if not yet created), and then mount ESP there:

root #mkdir

root #mount

Handbook:Parts/Installation/Kernel

=== Blocks link: /Blocks/Secure_Boot/Manual

Blocks link: /Blocks/Secure_Boot/Dist_Kernel

Optional: Signing the kernel image (Secure Boot)

The kernel image in the prebuilt distribution kernel (sys-kernel/gentoo-kernel-bin) is already signed for use with Secure Boot. To sign the kernel image of kernels built from source enable the secureboot USE flag, and optionally specify which key to use for signing in /etc/portage/make.conf. Note that signing the kernel image for use with secureboot requires that the kernel modules are also signed, the same key may be used to sign both the kernel image and the kernel modules:

FILE /etc/portage/make.confEnable custom signing keys

USE="modules-sign secureboot"

# Optionally, to use custom signing keys.
MODULES_SIGN_KEY="/path/to/kernel_key.pem"
MODULES_SIGN_CERT="/path/to/kernel_key.pem" # Only required if the MODULES_SIGN_KEY does not also contain the certificate.
MODULES_SIGN_HASH="sha512" # Defaults to sha512.

# Optionally, to boot with secureboot enabled, may be the same or different signing key.
SECUREBOOT_SIGN_KEY="/path/to/kernel_key.pem"
SECUREBOOT_SIGN_CERT="/path/to/kernel_key.pem"

Note
The SECUREBOOT_SIGN_KEY and SECUREBOOT_SIGN_CERT may be different files. For this example the pem file generated by OpenSSL includes both the key and the accompanying certificate, and thus both variables are set to the same value.

Note
For this example the same key that was generated to sign the modules is used to sign the kernel image. It is also possible to generate and use a second separate key for signing the kernel image. The same OpenSSL command as in the previous section may be used again.

See the above section for instructions on generating a new key, the steps may be repeated if a separate key should be used to sign the kernel image.

To successfully boot with Secure Boot enabled, the used bootloader must also be signed and the certificate must be accepted by the UEFI firmware or Shim. This will be explained later in the handbook.

Optional: Building an Unified Kernel Image

An Unified Kernel Image (UKI) combines, among other things, the kernel, the initramfs and the kernel command line into a single executable. Since the kernel command line is embedded into the unified kernel image it should be specified before generating the unified kernel image (see below). Note that any kernel command line arguments supplied by the bootloader or firmware at boot are ignored when booting with secure boot enabled.

An unified kernel image requires a stub loader, currently the only one available is systemd-stub. To enable it:

For systemd systems:

FILE /etc/portage/package.use/systemd

sys-apps/systemd boot

For OpenRC systems:

FILE /etc/portage/package.use/systemd-utils

sys-apps/systemd-utils boot kernel-install

Installkernel can automatically generate an unified kernel image using either dracut or ukify, by enabling the respective flag. The uki USE flag should be enabled as well to install the generated unified kernel image to the $ESP/EFI/Linux directory on the EFI system partition (ESP).

For dracut:

FILE /etc/portage/package.use/installkernel

sys-kernel/installkernel dracut uki

FILE /etc/dracut.conf

uefi="yes"
kernel_cmdline="some-kernel-command-line-arguments"

For ukify:

FILE /etc/portage/package.use/installkernel

sys-apps/systemd ukify          # For systemd systems
sys-apps/systemd-utils ukify    # For OpenRC systems
sys-kernel/installkernel dracut ukify uki

FILE /etc/kernel/cmdline

some-kernel-command-line-arguments

Note that while dracut can generate both an initramfs and an unified kernel image, ukify can only generate the latter and therefore the initramfs must be generated separately with dracut.

Generic Unified Kernel Image

The prebuilt sys-kernel/gentoo-kernel-bin can optionally install a prebuilt generic unified kernel image containing a generic initramfs that is able to boot most systemd based systems. It can be installed by enabling the generic-uki USE flag, and configuring installkernel to not generate a custom initramfs or unified kernel image:

FILE /etc/portage/package.use/generic-uki

sys-kernel/gentoo-kernel-bin generic-uki
sys-kernel/installkernel -dracut -ukify uki

Secure Boot

The generic Unified Kernel Image optionally distributed by sys-kernel/gentoo-kernel-bin is already pre-signed. How to sign a locally generated unified kernel image depends on whether dracut or ukify is used. Note that the location of the key and certificate should be the same as the SECUREBOOT_SIGN_KEY and SECUREBOOT_SIGN_CERT as specified in /etc/portage/make.conf.

For dracut:

FILE /etc/dracut.conf

uefi="yes"
kernel_cmdline="some-kernel-command-line-arguments"
uefi_secureboot_key="/path/to/kernel_key.pem"
uefi_secureboot_cert="/path/to/kernel_key.pem"

For ukify:

FILE /etc/kernel/uki.conf

[UKI]
SecureBootPrivateKey=/path/to/kernel_key.pem
SecureBootCertificate=/path/to/kernel_key.pem

Blocks link: /Installkernel

systemd-boot

When using systemd-boot (formerly gummiboot) as the bootloader, systemd's kernel-install must be used. Therefore ensure the systemd and the systemd-boot USE flags are enabled on sys-kernel/installkernel, and then install the relevant package for systemd-boot.

On OpenRC systems:

FILE /etc/portage/package.use/systemd-boot

sys-apps/systemd-utils boot kernel-install
sys-kernel/installkernel systemd systemd-boot

root #emerge --ask sys-apps/systemd-utils

On systemd systems:

FILE /etc/portage/package.use/systemd

sys-apps/systemd boot
sys-kernel/installkernel systemd-boot

root #emerge --ask sys-apps/systemd

Handbook:Parts/Installation/System

Blocks link: /Fstab

(Just move to Handbook:AMD64/Blocks/Fstab?)

UEFI systems

Below is an example of an /etc/fstab file for a system that will boot via UEFI firmware:

FILE /etc/fstabA full /etc/fstab example for an UEFI system

# Adjust for any formatting differences and/or additional partitions created from the "Preparing the disks" step
                    0 2
   none             sw                   0 0
   /                defaults,noatime              0 1

/dev/cdrom  /mnt/cdrom   auto    noauto,user          0 0

When auto is used in the third field, it makes the mount command guess what the filesystem would be. This is recommended for removable media as they can be created with one of many filesystems. The user option in the fourth field makes it possible for non-root users to mount the CD.

To improve performance, most users would want to add the noatime mount option, which results in a faster system since access times are not registered (those are not needed generally anyway). This is also recommended for systems with solid state drives (SSDs). Users may wish to consider lazytime instead.

Tip
Due to degradation in performance, defining the discard mount option in /etc/fstab is not recommended. It is generally better to schedule block discards on a periodic basis using a job scheduler such as cron or a timer (systemd). See Periodic fstrim jobs for more information.

Double-check the /etc/fstab file, then save and quit to continue.