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.

• Then you have to run grub2-mkconfig -o /boot/grub/grub.cfg, which should generate the proper configuration file. 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 grub2-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.

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 grub2-install /dev/sda to install Grub 2 on the MBR.

• If you have a RAID array, just running grub2-install /dev/sda should be enough. However, you need to emerge mdadm or grub2-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!

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.