EFI stub
- 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:
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 (root=UUID=d1e0c1e0-3a40-42c5-8931-cfa2c7deae32)
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:
CONFIG_EFI=y CONFIG_EFI_STUB=y CONFIG_CMDLINE_BOOL=y 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.
Installation
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.
Troubleshooting
- Older kernels compiled with gcc:10 crashed at boot (bug #721734#c4).
- Users of sys-kernel/gentoo-kernel-bin can specify the root partition path with the
root=
parameter using efibootmgr:
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
- UEFI — a firmware standard for boot ROM designed to provide a stable API for interacting with system hardware. On x86 it replaced the legacy BIOS.
- Efibootmgr — a tool for managing UEFI boot entries.
- Architecture specific kernel configuration (AMD64 Handbook)
- REFInd — a boot manager for EFI and UEFI platforms forked from and successor to rEFIt.
External resources
- Linux Kernel Documentation on EFI Stub
- EFI Stub - booting without a bootloader Blog posting which this article is partially based on.
- EFI bootloaders listing alternative ways to boot an (U)EFI system.
- Gentoo Forums: Suspend and Hibernate with UEFI
- http://www.kroah.com/log/blog/2013/09/02/booting-a-self-signed-linux-kernel/