10.4. Using GRUB to Set Up the Boot Process

10.4.1. Introduction

Warning

Configuring GRUB incorrectly can render your system inoperable without an alternate boot device such as a CD-ROM or bootable USB drive. This section is not required to boot your LFS system. You may just want to modify your current boot loader, e.g. Grub-Legacy or GRUB2.

Ensure that an emergency boot disk is ready to “rescue” the computer if the computer becomes unusable (un-bootable). If you do not already have a boot device, you can create one. In order for the procedure below to work, you need to jump ahead to BLFS and install xorriso from the libisoburn package.

cd /tmp
grub-mkrescue --output=grub-img.iso
xorriso -as cdrecord -v dev=/dev/cdrw blank=as_needed grub-img.iso

10.4.2. Turn off Secure Boot

LFS does not have the essential packages to support Secure Boot. To set up the boot process following the instructions in this section, Secure Boot must be turned off from the configuration interface of the firmware. Read the documentation provided by the manufacturer of your system to find out how.

10.4.3. GRUB Naming Conventions

GRUB uses its own naming structure for drives and partitions in the form of (hdn,m), where n is the hard drive number and m is the partition number. The hard drive numbers start from zero, but the partition numbers start from one for normal partitions (from five for extended partitions). Note that this is different from earlier versions where both numbers started from zero. For example, partition sda1 is (hd0,1) to GRUB and sdb3 is (hd1,3). In contrast to Linux, GRUB does not consider CD-ROM drives to be hard drives. For example, if using a CD on hdb and a second hard drive on hdc, that second hard drive would still be (hd1).

10.4.4. Setting Up the Configuration

On the systems with UEFI firmware, GRUB works by storing the main GRUB image as a PE-COFF executable file at a standard location in the EFI System Partition: EFI/BOOT/BOOTLOONGARCH64.EFI. The UEFI firmware loads it from the standard location and executes it, launching GRUB.

Many GRUB functions (including booting the Linux kernel) are not included in the main GRUB image. Instead, they are stored in a file system as GRUB modules. That file system is usually mounted in a way that the GRUB modules can be accessed in /boot/grub on most Linux distributions. To avoid the chicken-and-egg problem, grub-install embeds the modules necessary to access this file system into the main GRUB image, so it can find and load other modules.

Using the above information, determine the appropriate designator for the root partition. For the following example, it is assumed that the root partition is sda2.

For booting with UEFI, make sure the EFI System Partition is mounted at /boot/efi. After that, install the GRUB files into /boot/grub and the main GRUB image at /boot/efi/EFI/BOOT/BOOTLOONGARCH64.EFI:

Warning

The following command will overwrite the /boot/efi/EFI/BOOT/BOOTLOONGARCH64.EFI file. If it already exists, it's likely that it's the entry of another boot loader (for example the GRUB installation from the host distro, or the Windows Boot Manager). Backup the file so it can be restored later or loaded as a secondary boot loader by the new GRUB installation from LFS.

grub-install --target=loongarch64-efi --removable

The --removable option makes grub-install use the standard location, EFI/BOOT/BOOTLOONGARCH64.EFI, instead of the location GRUB prefers (EFI/GRUB/GRUBLOONGARCH64.EFI). Using a non-standard location would result in the location in a EFI variable be recorded, but LFS lacks the BLFS package efibootmgr, which is needed to manipulate EFI variables.

Note

Some UEFI bootloaders, while rare, skip the hardcoded EFI path.When the boot entry is missing in the BIOS, you will need to install the BLFS package efibootmgr to create a boot entry for UEFI. If it's easier, the package can be installed via the distribution's package manager, if applicable, and used on the host instead of on the LFS system. This can prevent the need for downloading more tarballs onto the LFS system for now.

First install the package, then mount the EFI variable file system if it isn't already mounted:

mountpoint /sys/firmware/efi/efivars ||
  mount -v -t efivarfs efivarfs /sys/firmware/efi/efivars

Now create a boot entry for the EFI:

efibootmgr -c -d /dev/sd<x> \
  -p <y> -L "LFS" -l '\EFI\BOOT\BOOTLOONGARCH64.EFI'

The /dev/sd<x> drive should match the one you are installing LFS onto. The <y> partition number should match the number which the ESP is mounted. If the ESP is on /dev/sda2, then the partition number would be 2.

Some (broken) firmwares may require additional parameters for efibootmgr, like --full-dev-path or -e 1 -E. Read the man page efibootmgr(8) for details.

Now unmount the EFI variable file system:

umount -v /sys/firmware/efi/efivars

10.4.5. Creating the GRUB Configuration File

Generate /boot/grub/grub.cfg:

cat > /boot/grub/grub.cfg << "EOF"
# Begin /boot/grub/grub.cfg
set default=0
set timeout=5

insmod part_gpt
insmod ext2

set root=(hd0,2)

insmod efi_gop

menuentry "GNU/Linux, Linux 6.19.10-lfs-loongarch-r13.0-77-systemd" {
        linux   /boot/vmlinuz-6.19.10-lfs-loongarch-r13.0-77-systemd root=/dev/sda2 ro
}

menuentry "Debian" {
        insmod fat
        insmod chain
        chainloader (hd0,1)/EFI/DEBIAN/GRUBLOONGARCH64.EFI
}

menuentry "Firmware Setup" {
        fwsetup
}
EOF

The insmod commands load the GRUB modules named part_gpt, ext2, and efi_gop. Despite the naming, ext2 actually supports ext2, ext3, and ext4 filesystems. On UEFI systems, efi_gop is for video support. In a typical configuration, the part_gpt and ext2 modules are already embedded in the main GRUB image by grub-install, and the insmod commands for them will do nothing. However, they do no harm anyway, and they may be needed with some rare configurations.

The “Debian” section demonstrate how a UEFI boot loader can “chainload” another. If you've backed up the previous BOOTLOONGARCH64.EFI file before running the grub-install command, you can put it it back into the ESP (with a different path) and chainload it as well.

The “Firmware Setup” section demonstrate the use of the fwsetup command, which invokes the configuration interface of the UEFI firmware (widely known as “BIOS Setup”).

Note

The GRUB designator for a partition may change if you added or removed some disks (including removable disks like USB thumb devices). The change may cause boot failure because grub.cfg refers to some “old” designators. If you wish to avoid such a problem, you may use the UUID of a partition and the UUID of a filesystem instead of a GRUB designator to specify a device. Run lsblk -o UUID,PARTUUID,PATH,MOUNTPOINT to show the UUIDs of your filesystems (in the UUID column) and partitions (in the PARTUUID column). Then replace set root=(hdx,y) with search --set=root --fs-uuid <UUID of the filesystem where the kernel is installed>, and replace root=/dev/sda2 with root=PARTUUID=<UUID of the partition where LFS is built>.

Note that the UUID of a partition is completely different from the UUID of the filesystem in this partition. Some online resources may instruct you to use root=UUID=<filesystem UUID> instead of root=PARTUUID=<partition UUID>, but doing so will require an initramfs, which is beyond the scope of LFS.

The name of the device node for a partition in /dev may also change (very frequently on some systems with multiple NVME disks). You can also replace paths to device nodes like /dev/sda1 with PARTUUID=<partition UUID>, in /etc/fstab, to avoid a potential boot failure in case the device node name has changed.

GRUB is an extremely powerful program and it provides a tremendous number of options for booting from a wide variety of devices, operating systems, and partition types. There are also many options for customization such as graphical splash screens, playing sounds, mouse input, etc. The details of these options are beyond the scope of this introduction.