Gentoo EFIBOOTMGR

 

efibootmgr

On UEFI based systems, the UEFI firmware on the system (in other words the primary bootloader), can be directly manipulated to look for UEFI boot entries. Such systems do not need to have additional (also known as secondary) bootloaders like GRUB2 in order to help boot the system. With that being said, the reason EFI-based bootloaders such as GRUB2 exist is to extend the functionality of UEFI systems during the boot process. Using efibootmgr is really for those who desire to take a minimalist (although more rigid) approach to booting their system; using GRUB2 (see above) is easier for the majority of users because it offers a flexible approach when booting UEFI systems.

Remember sys-boot/efibootmgr application is not a bootloader; it is a tool to interact with the UEFI firmware and update its settings, so that the Linux kernel that was previously installed can be booted with additional options (if necessary), or to allow multiple boot entries. This interaction is done through the EFI variables (hence the need for kernel support of EFI vars).

Be sure to read through the EFI stub kernel article before continuing. The kernel must have specific options enabled to be directly bootable by the system's UEFI firmware. It might be necessary to recompile the kernel.

************************EFI stub kernel****************

The (U)EFI firmware present in many computers can function as bootloader, allowing systems to boot without needing an additional software bootloader. This article shows how to configure and install an unsigned kernel in the EFI System Partition (ESP) of a computer running in EFI mode with secureboot turned off.

Contents

• 1Kernel configuration
• 2Installation
• 3Optional: Initramfs
• 4See also
• 5External resources
• 6References

Kernel configuration

In order to boot directly from UEFI, the kernel needs to know where to find the root (/) partition of the system to be booted. Enable EFI runtime service support (CONFIG_EFI), EFI stub support (CONFIG_EFI_STUB) and Built-in kernel command line (CONFIG_CMDLINE_BOOL) and add the root partition path (example: /dev/sda2) or its PARTUUID to (CONFIG_CMDLINE).

KERNEL Enable EFI stub support

Processor type and features  --->
    [*] EFI runtime service support 
    [*]   EFI stub support
    [ ]     EFI mixed-mode support
    ...
    ...
    [*] Built-in kernel command line
    (root=/dev/sda2)

Using root=PARTUUID= might be preferable. To find out use blkid:

 Note
The partition's PARTUUID is distinct from the filesystem's UUID.

root # blkid | grep sda2

/dev/sda2: UUID="d1e0c1e0-3a40-42c5-8931-cfa2c7deae32" TYPE="ext4" PARTUUID="adf55784-15d9-4ca3-bb3f-56de0b35d88d"

KERNEL CONFIG_CMDLINE - alternative using PARTUUID (example: adf55784-15d9-4ca3-bb3f-56de0b35d88d)

Processor type and features  --->
    [*] Built-in kernel command line
    (root=PARTUUID=adf55784-15d9-4ca3-bb3f-56de0b35d88d)

It is also a good idea to enable EFI Variable Support via sysfs (CONFIG_EFI_VARS) so that the efivars can be mounted. CONFIG_EFI_MIXED as proposed by Gentoo Handbook is not needed for the EFI boot stub.

KERNEL EFI Variable Support via sysfs

Firmware Drivers  --->
    EFI (Extensible Firmware Interface) Support  --->
        <*> EFI Variable Support via sysfs

Installation

If an ESP does not exist, one needs to be created. See EFI System Partition. Still in the kernel directory, build the kernel and install the modules:

root # cd /usr/src/linux

root # make && make modules_install

Have the ESP (in this example /dev/sda1) mounted at /boot:

root # mount /dev/sda1 /boot

Copy or move the kernel image to the right place adding version number and the .efi suffix:

root # mkdir -p /boot/EFI/Gentoo

root # cp arch/x86/boot/bzImage /boot/EFI/Gentoo/bzImage-4.9.76-r1.efi

In the ESP it should then be listed like:

user $ tree -L 3 /boot

 /boot
 └── EFI
     └── Gentoo
         └── bzImage-4.9.76-r1.efi

Alternatively the fallback directory /boot/EFI/Boot could be used additionally to or instead of /boot/EFI/Gentoo.

Next, update the NVRAM creating a new boot entry using e.g. efibootmgr.

Optional: Initramfs

If for some reason an initramfs is needed, it can either be embedded into the kernel or be used as a separate file.

In case it's desired as a separate file, it should also be copied or moved into the ESP and the NVRAM be updated accordingly.

root # mv /boot/initramfs-4.9.76-r1-gentoo.img /boot/EFI/Gentoo/initramfs.img

root # mount /sys/firmware/efi/efivars -o rw,remount

root # efibootmgr --create --part 1 --label "Gentoo" --loader '\efi\gentoo\bzImage-4.9.76-r1.efi' -u 'initrd=\efi\gentoo\initramfs.img'

root # mount /sys/firmware/efi/efivars -o ro,remount

Some UEFI implementations however seem to not support passing parameters from the NVRAM to the EFI stub kernel.

For embedding the initramfs directly into the kernel image, the Initramfs source file(s)(CONFIG_INITRAMFS_SOURCE) must be coded in the kernel (directly under the Initial RAM filesystem and RAM disk (initramfs/initrd) support (CONFIG_BLK_DEV_INITRD) option) as shown here for a custom initramfs created in /usr/src/initramfs:

KERNEL CONFIG_INITRAMFS_SOURCE="/usr/src/initramfs" — (Example from Custom Initramfs)

General setup ---> [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support (/usr/src/initramfs) Initramfs source file(s)

Embedding takes place on compilation, so the kernel must then be recompiled and be moved (or copied) again into the ESP.

***************EFI stub kernel END*************

 Note
To reiterate, efibootmgr is not a requirement to boot an UEFI system. The Linux kernel itself can be booted immediately, and additional kernel command-line options can be built-in to the Linux kernel (there is a kernel configuration option called that allows the user to specify boot parameters as command-line options. Even an initramfs can be 'built-in' to the kernel.

Those that have decided to take this approach must install the software:

root # emerge --ask sys-boot/efibootmgr

Then, create the /boot/efi/boot/ location, and then copy the kernel into this location, calling it bootx64.efi:

root # mkdir -p /boot/efi/boot

root # cp /boot/vmlinuz-* /boot/efi/boot/bootx64.efi

Next, tell the UEFI firmware that a boot entry called "Gentoo" is to be created, which has the freshly compiled EFI stub kernel:

root # efibootmgr --create --disk /dev/sda --part 2 --label "Gentoo" --loader "\efi\boot\bootx64.efi"

If an initial RAM file system (initramfs) is used, add the proper boot option to it:

root # efibootmgr -c -d /dev/sda -p 2 -L "Gentoo" -l "\efi\boot\bootx64.efi" initrd='\initramfs-genkernel-amd64-3.16.5-gentoo'

 Note
The use of \ as directory separator is mandatory when using UEFI definitions.

With these changes done, when the system reboots, a boot entry called "Gentoo" will be available.