Startup Configuration

This documents the boot process in Gentoo Linux.

UEFI

• Computers that implement UEFI don't really need GRUB, as UEFI implements a boot manager. You still need a bootloader after the OS has been chosen, but this can be done directly by the kernel image if you compile it with the EFI_STUB option. You probably also need to setup the Built-in kernel command line (at the bottom of Processor type and features).
• So on a computer implementing UEFI, the best choice is to not install GRUB at all. Generally the motherboard firmware will offer an interface to add / modify / delete UEFI entries. However, you may need to pass some kernel parameters on the command line (such as root=/dev/sdaX). You may build those directly on the kernel.
• Be careful when entering the new EFI entry; it should use the syntax fsX:\pathfilename.efi where X is the UEFI mapping (drive number). So it can be fs1:\ or fs0:\ for instance. WARNING: On ASUS models it seems you have to omit the fsX: part altogether. Just enter the path to the EFI file.
• In case of problems, running the EFI Shell can be helpful. It should be copied to the root of the ESP partition and renamed to shellx64.efi (at least for ASUS models).
• To know if you booted in UEFI mode, just check if /sys/firmware/efi exists. If no, you've booted into legacy BIOS mode.

EFI System Partition (ESP)

• You need to have an ESP partition in order for UEFI to work. The filesystem type should be FAT32 and there is a specific GPT identifier for the partition.
• It's also better to have a GPT partition table on the drive hosting the EFI partition. Normally UEFI supports MBR partition tables, but some UEFI implementations switch to BIOS boot mode when discovering MBR partitions.
• There is a specific file-system hierarchy that should be respected on the ESP.

efibootmgr

• If you cannot directly create the entry via the motherboard firmware, you can use efibootmgr. Be careful that in this case the computer must be booted in UEFI mode, not in BIOS legacy mode. Example invocation:

efibootmgr -c -d /dev/sda -p 1 -L "Grub" -l '\efi\gentoo\grubx64.efi'

• Note that the UEFI motherboard software can sometimes loose the UEFI boot entries. You can run efibootmgr to recreate them.

UEFI Shell

• The most important command is bcfg but not all shells support it. You can use help -b to get a list of all commands.

GRUB 2

General information

• First write the correct value for the GRUB_PLATFORMS variable in /etc/portage/make.conf. It should be "efi-64" for UEFI systems and "pc" for BIOS systems. Emerge sys-boot/grub.

• Chroot into the new system if not done already. This is very important: it's not easy to generate a working GRUB configuration for a new hard drive, if you make the installation while booted on a previous hard drive. If you are chrooted, all is much simpler, as the autoconfiguration (grub-mkconfig) will correctly detect everything.

• You have to run grub-mkconfig -o /boot/grub/grub.cfg, which should generate the proper configuration file. If it fails, it probably means that /boot/grub directory does not exist and should be created. Kernels are auto-discovered if their names start with kernel-* and they are present in /boot. Be sure to first emerge os-prober if you have a Windows boot partition, as it will autodetect it.

• If you have a setup where the boot partition is distinct from the root partition, double check if there is a symlink (boot that points to .) in the boot partition. Most of the time in grub.cfg the path to the kernel is given as /boot/kernel-xxx and this will fail without the symlink.

Using GRUB with a full UEFI configuration

• If you don't use directly the kernel as a bootloader, you may want to install GRUB as an UEFI bootloader, which will then launch the Linux kernel. This can be mandatory if your motherboard UEFI interface does not allow you to create UEFI boot entries (although you should be able to create those manually with efibootmgr).

• Installation is done via grub-install. The EFI System Partition (ESP) should be currently mounted at /boot/efi when running the command. efibootmgr will be automatically invoked and will create the requested UEFI entry (or entries). Normally GRUB is installed in the ESP at /efi/gentoo/grubx64.efi.

• Dual booting with Windows can be achieved with the following entry (added to grub.cfg file). root='hd0,gpt1' corresponds to the ESP partition (since we load bootmgfw.efi on the ESP partition).

menuentry "Windows 10" {
        insmod part_gpt
        insmod chain
        search --no-floppy --fs-uuid --set=root 3E9E-1333
        chainloader ($root)/EFI/Microsoft/Boot/bootmgfw.efi
}

• The UUID of the search line above can be obtained easily by running the blkid tool on Linux. Before, #set root='hd0,gpt1' could be used instead, but it does not seem to work with a NVME SSD drive.

Using GRUB with a BIOS / GPT partition table configuration

• Even if your system supports UEFI boot, sometimes it is advisable to use a plain BIOS boot configuration. This is especially recommended on servers, where no visual access to the screen can make a pure UEFI boot configuration painful. Sometimes, there are also bugs in EFI firmwares (I had this with MSI motherboards and would not recommend them as a result) that prevent a normal EFI boot.

• To use a BIOS boot with a GPT partition, there should be, in the first 2TBs of the HD, a small 1MB partition with type BIOS boot - 04 in fdisk. It's not mandatory to have this boot partition as the first partition. No filesystem is needed on that partition.

• Also don't forget that in that case, you need insmod part_gpt in your grub.cfg file. Also, you need to provide a line such as:

set root='hd0,gpt2'

Using GRUB with a BIOS / DOS partition table configuration

• Once configuration file is generated, just run grub-install /dev/sda to install Grub 2 on the MBR.

• If you have a RAID array, just running grub-install /dev/sda should be enough. However, you need to emerge mdadm or grub-install will report an error and exit.

Checking GRUB

• Checking GRUB can only be done visually or through a (v)KVM. Note that GRUB does not write to the filesystem when ran, only to the boot sectors of the hard drive. If GRUB boots on a vKVM, it means it is OK, even if the hardware is emulated inside the vKVM.

• Note that repartitioning a disk does not necessarily wipe out the bootloader (GRUB) which is installed in the Master Boot Record (MBR). To completely erase a previously installed bootloader:

dd if="/dev/zero" of="${HARD_DISK_DEVICE}" count="1" bs="2048"

Note that the previous command will destroy the partition table, so will destroy all data on the hard drive!

Booting in console mode

• This can be done by appending "single" to the linux kernel boot line. For instance:

linux   /boot/kernel-5.16.12 root=/dev/nvme0n1p2 ro single

Obtaining a log of the boot messages

Very early messages

• If you don't have any message on the screen after the kernel has been loaded by GRUB, it is possible that you are lacking an UEFI framebuffer. Add this option to the kernel configuration.

Kernel log

• It is available at /var/log/dmesg. It will give you a log of the kernel messages.

• You can still get some information by editing /etc/conf.d/rc, changing RC_BOOTLOG="yes" and emerging the package showconsole. The log file will be written to /var/log/boot.msg. But it will miss some parts of the boot process - that's normal.

With OpenRC

• In /etc/rc.conf:
  • Enable rc_logger="YES", logs will go to /var/log/rc.log.
  • Enable rc_interactive="YES" and press "I" as soon as you can if you have errors at boot.
  • Increasing rc_start_wait can also help with debugging.

Log System

You need to emerge a log system (and activate it, you need to add the init script to a runlevel) such as syslog-ng. It can also give you some information.

udev activating services

• If udev is activating services you don't want (and possibly also loading kernel modules), try to change RC_COLDPLUG value in /etc/conf.d/rc (and possibly RC_HOTPLUG too).

Mounting filesystems

• Filesystems listed in /etc/fstab are either mounted by the localmount script, or if they are considered network filesystems, by the netmount script. The list of filesystems considered network are in the variable NET_FS_LIST, normally defined in /sbin/functions.sh. You can override it in /etc/conf.d/localmount and /etc/conf.d/netmount.

Required /dev files

• With udev most of the /dev directory can be empty, however you still need those three nodes or Gentoo won't boot:

mknod --mode=600 console c 5 1 
mknod --mode=666 null c 1 3 
mknod --mode=666 zero c 1 5

Display Manager

• With SDDM and KDE, you need elogind in order for the reboot / shutdown button to work on the SDDM environment (ie, login page). These buttons did not work on OpenRC / ConsoleKit setup.
• With a nvidia card, it may be needed to active DRM enabled in the kernel, and an option must be activated on the boot command line (for the nvidia module). This is described in this article.