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.
• So on a computer implementing UEFI, the best choice is to not install GRUB at all. Generally the BIOS 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).
• You need the first partition to be a FAT32 partition in order for UEFI to work. I also think the partition table should be GPT (not sure).

GRUB

GRUB 2

• You just have to run grub2-mkconfig -o /boot/grub/grub.cfg, which should generate the proper configuration file. Be sure to first emerge os-prober if you have a Windows boot partition, as it will autodetect it.

• Then run grub2-install /dev/sda to install Grub 2 on the MBR. For UEFI computers things are of course different but usually you then do not need GRUB at all.

• 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.

• 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.

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

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