EFI stub

From Gentoo Wiki
(Redirected from EFI Stub)
Jump to:navigation Jump to:search
Other languages:
  • English
This article has some todo items:
  • CONFIG_PM_STD_PARTITION for hibernation

The (U)EFI firmware present in many computers functions as a boot manager, allowing systems to boot by the use of a compatible EFI bootloader. By making the Linux kernel itself such a bootloader, called an EFI stub. This configuration boots without the need for secondary bootloader. This article provides instructions on configuring and installing kernels in the EFI System Partition (ESP) of a computer running in EFI mode.

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.

The following kernel configuration options must be enabled:

KERNEL Enable EFI stub support
Processor type and features  --->
    [*] EFI runtime service support 
    [ ]     EFI handover protocol (DEPRECATED) (OPTIONAL)
    [*]     EFI stub support
    [ ]     EFI mixed-mode support (OPTIONAL)
    [*] Built-in kernel command line
Setting the root location using a UUID or PARTUUID is generally preferable and less error prone. This information can be obtained with blkid:
root #blkid | grep sda2
/dev/sda2: UUID="d1e0c1e0-3a40-42c5-8931-cfa2c7deae32" TYPE="ext4" PARTUUID="adf55784-15d9-4ca3-bb3f-56de0b35d88d"

The partition's PARTUUID is distinct from the filesystem's UUID. The UUID refers to the filesystem partition, while the PARTUUID refers to the disk partition.

EFI mixed-mode support is only required to boot a 64-bit kernel from 32-bit firmware if the CPU supports 64-bit mode and EFI handover is enabled.

.config equivalent with a cmdline with dracut parameters:

CODE .config configuration for an EFI stub with an embedded kernel command line
CONFIG_CMDLINE="root=/dev/mapper/vg0-root rd.luks.key=/crypt_key.luks.gpg:UUID=044502df-6f rd.luks.uuid=5e0022f4-e1c9-4b58-b53e-25d3cd417451 rd.lvm.lv=vg0/root"
The command line does not need to be built into the kernel, and can be passed by the UEFI or bootloader. efibootmgr) can use the --unicode argument to define a new command line.
For Distribution kernels (except gentoo-kernel-bin) the kernel settings go to savedconfig or /etc/kernel/config.d.


Kernel Installation

With the kernel configured with EFI Stub support (assuming that ESP is mounted at /boot):

/usr/src/linux-6.3.4-gentoo-r1 #make && make modules_install && make install

This will install the kernel to /boot/vmlinuz-6.3.4-gentoo-r1.

The EFI stub kernel file can be moved to /{ESP}/EFI/BOOT/BOOTx64.efi, where most UEFIs will check for efi files by default.

Signing for Secure Boot

If Secure Booting this kernel, it must be signed witn sbsign, part of app-crypt/sbsigntools:

root #sbsign --key {db key} --cert {db cert} /boot/vmlinuz-6.3.4-gentoo-r1-initramfs

More information is available at Secure Boot.

EFI Configuration

With the kernel file at /boot/vmlinuz-6.3.4-gentoo-r1-initramfs.signed, a boot entry can be added with:

/boot #efibootmgr --create --disk /dev/sda --label "Signed Gentoo EFI Stub" --loader vmlinuz-6.3.4-gentoo-r1-initramfs.signed

To add an entry with kernel command line arguments:

/boot #efibootmgr --create --disk /dev/sda --label "Signed Gentoo EFI Stub" --loader vmlinuz-6.3.4-gentoo-r1-initramfs.signed --unicode "root=/dev/sdb1"

Microcode loading

An efistub compatible method to load microcode without using an initramfs can be found in the following articles:

Optional: initramfs

See the Generating the Initramfs and Using a Stub Kernel sections of the Early Userspace Mounting article.


root #efibootmgr -c -L "Gentoo Linux" -l '\EFI\Gentoo\bootx64.efi' -u 'root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
To create a boot entry with efibootmgr and hibernation on swap partition:
root #efibootmgr -c -L "Gentoo Linux" -l '\EFI\Gentoo\bootx64.efi' -u 'root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX resume=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

See also

External resources