EFI stub

From Gentoo Wiki
(Redirected from EFI stub kernel)
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.
Other languages:
Resources
This article has some todo items:
  • CONFIG_PM_STD_PARTITION for hibernation

This article describes EFI stub kernels, i.e. kernels directly executable from UEFI.

An EFI stub (aka EFI boot stub)[1] is a kernel that is an EFI executable, i.e. that can directly be booted from the UEFI firmware. This means a bootloader is not necessary for them. (But it is also possible to use a bootloader.)

Kernel configuration

EFI stub support

The following kernel configuration options must be enabled:

KERNEL Enable EFI stub support for Kernels 6.1+
Processor type and features  --->
    [*] EFI runtime service support Search for <code>CONFIG_EFI</code> to find this item.
    [*]     EFI stub support Search for <code>CONFIG_EFI_STUB</code> to find this item.
    [ ]     EFI mixed-mode support (OPTIONAL) Search for <code>CONFIG_EFI_MIXED</code> to find this item.
Note
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.

Installation

Tip
If an EFI System Partition (ESP) does not exist, please follow the steps to set it up first.

Automated

Warning
UEFI implementations differ between vendors, as such EFI Stub booting is not guaranteed to work for all UEFI systems. Ensure a back-up booting method is available before attempting (automated) EFI Stub booting.

Automated EFI stub booting is provided by sys-kernel/installkernel-38 and later when the efistub USE flag is enabled. This relocates the regular boot layout from /boot to the EFI/Gentoo directory on the EFI System Partition

Systemd kernel-install

When both the efistub and systemd USE flags are enabled on sys-kernel/installkernel, kernel-install calls kernel-bootcfg from app-emulation/virt-firmware to add or remove a boot entry for the installed or removed kernel. Installkernel is called automatically by the kernel's make install or by the Distribution Kernels' post-install phase. Therefore, no special action is required when installing a new kernel, though the kernel-bootcfg-boot-successful init service from app-emulation/virt-firmware should be enabled to automatically make an entry for a new kernel permanent when booting it was successful.

For systemd systems:

root #systemctl enable --now kernel-bootcfg-boot-successful.service

For OpenRC systems:

root #rc-update add kernel-bootcfg-boot-successful default

When the to-be-registered kernel image is not an Unified Kernel Image a kernel command line for the new entry is read from:

  • /etc/kernel/cmdline, or
  • /usr/lib/kernel/cmdline, or
  • /proc/cmdline

in this order. In addition, the initrd= kernel command line argument is automatically added if an initramfs was generated while installing the kernel. If on the other hand the to-be-registered kernel is an Unified Kernel Image, then no command line is added to the new entry. Instead the command line built into the Unified Kernel Image is used, the contents of this built-in command line are usually also read from the same files when the UKI is generated.

Tip
The kernel command line, as well as an initramfs, may also be embedded into the kernel, see the sections below for more information.

Traditional installkernel

When the efistub USE flag is enabled on sys-kernel/installkernel, but the systemd USE flag is disabled. Installkernel calls uefi-mkconfig from sys-boot/uefi-mkconfig to dynamically update the UEFI configuration. If the shim EFI executable is present in the same directory as the kernel image the kernels will be chainloaded via Shim.

Manual

It is recommended to create a separate directory below /efi/EFI, assuming the ESP is mounted at /efi. With the kernel configured with EFI Stub support, create a separate directory below /efi/EFI:

root #mkdir -p /efi/EFI/example
Note
On some systems /efi/EFI or /efi/efi (in lowercase) may already exist (assuming the ESP is mounted at /efi). The FAT file system of the EFI System Partition (ESP) is not case-sensitive, but case-preserving (VFAT). With the default VFAT mount options, the above command will work in both cases. See the case sensitivity section in the FAT article for further details.

The kernel is created from the current kernel directory and copied to the new directory. This will install the kernel to /efi/EFI/example/bzImage.efi:

/usr/src/linux #make && make modules_install && cp arch/x86/boot/bzImage /efi/EFI/example/bzImage.efi
Tip
It is recommended when upgrading the kernel to keep an older version which is proven to work:
user $tree -L 3 /efi
 /efi
 └── EFI
     └── example
         ├── bzImage-6.1.67.efi
         └── bzImage-6.1.70.efi

Root partition configuration

In order to boot directly from UEFI, the kernel or its initramfs needs to know where to find the root partition of the system to be booted. When using a bootmanager like grub the kernel gets its information where to find its root partition from the bootmanager via command line parameter. When using a stub kernel two options can be used to give the kernel this information - choose one of these options:

Option 1: Configuring it into the kernel
KERNEL Root Partiton information for Kernels 6.1+
Processor type and features  --->
    [*] Built-in kernel command line
    (root=PARTUUID=adf55784-15d9-4ca3-bb3f-56de0b35d88d ro)
Important
The value adf55784-15d9-4ca3-bb3f-56de0b35d88d is an example and must be replaced with the value of the real root partition. It can be obtained by using the blkid command:
root #blkid | grep sda3 
/dev/sda3: 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 unique filesystem partition and must be used with a initramfs, while the PARTUUID refers to the disk partition and can be used when booting a kernel.
Option 2: Configuring it into UEFI

To add an entry with kernel command line arguments:

root #efibootmgr --create --disk /dev/sda --label "Gentoo EFI Stub" --loader "\EFI\example\bzImage.efi" -u "root=/dev/sda3"
Important
Setting the root location using a PARTUUID, or (filesystem) UUID when using a initramfs, is generally preferable and less error prone.

More examples can be found in Creating a boot entry.

Optional: Kernel with initramfs

When using a kernel with an external initramfs (as CPIO archive) additional steps are necessary. There is always an initramfs file when building a dist-kernel or when using genkernel. When using a dist-kernel this initramfs is named "initrd" and is in /usr/src/linux-6.1.57-gentoo-dist/arch/x86/boot/initrd. This file must must be copied also into the ESP:

root #cp /path/to/my/initramfs/myinitrd.cpio.gz /efi/EFI/example/initrd.cpio.gz

Now the kernel needs the information where to find it, and the initramfs needs the information where to find its root partition. UEFI must give both information:

root #efibootmgr -c -d /dev/sda -p 1 -L "Gentoo EFI Stub" -l '\EFI\example\bzImage.efi' -u 'root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx initrd=\EFI\example\initrd.cpio.gz'

A Forums post explains it in more detail - and solved some user errors:

Forums topic - Booting UEFI without Grub

When using Early Userspace Mounting the Generating the Initramfs and Using a Stub Kernel sections explains it in more detail.

Optional: Embedded initramfs

It's also possible to embed the initramfs directly into the kernel. Advantages include the initramfs being verified by Secure Boot when it verifies the kernel, a simplified boot process and EFI partition, and it being easier to load the kernel by hand (because callers no longer need to specify the initramfs). Disadvantages are reduced flexibility, the ease of making a mistake, and using an unconventional boot setup.

Warning
If your initramfs contains Microcode, then it is critical for security that it is receiving updates. When embedded, the initramfs can't be updated independently of the kernel, and a kernel rebuild will be necessary every time the initramfs is updated. In particular, please ensure that:
  • If
    root #make clean
    is not being run before rebuilding the kernel,
    root #rm usr/initramfs_data.cpio
    is run to clear the cached initramfs CPIO archive that remains from the last build.
  • When the initramfs has an update, the kernel is rebuilt and reinstalled.
  • If the initramfs is managed by sys-apps/portage, the initramfs is updated before the kernel.

The kernel supports both CPIO files (for example, as produced by Dracut) and source directories which are to be compressed into a CPIO archive. The following shows the latter with /usr/src/initramfs, however should be substituted with /path/to/my/initramfs/myinitrd.cpio.gz if the former case is desired (it usually is, unless you are using a Custom Initramfs).

KERNEL Embedding the initramfs into the kernel
General Setup  --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
    (/usr/src/initramfs) Initramfs source file(s)
EFI firmware configuration

To ensure everything is functioning correctly, the kernel may be booted without the initrd command line argument.

To create the Unified Kernel Image entry:

root #efibootmgr --create --disk /dev/sda --label "Gentoo EFI Stub" --loader "\EFI\example\bzImage.efi"

Backup kernel

It is recommended to always have a backup kernel. If a bootmanager like grub is already installed, it should not be uninstalled, because grub can boot a stub kernel just like a normal kernel. A second possibility is to work with an additional UEFI entry. Before installing a new kernel, the current one can be copied from /efi/EFI/example/ to /efi/EFI/backup. The second UEFI entry was also created with efibootmgr. In this example, other names were used:

root #efibootmgr
BootCurrent: 0002
Timeout: 1 seconds
BootOrder: 0002,0000,0001
Boot0000* Secure        HD(1,GPT,0adcbfee-21aa-42ea-9a9a-2e53bd05e6a2,0x800,0x7f800)/File(\EFI\secure\bzImage.efi)
Boot0001* gentoo        HD(1,GPT,0adcbfee-21aa-42ea-9a9a-2e53bd05e6a2,0x800,0x7f800)/File(\EFI\gentoo\grubx64.efi)
Boot0002* Backup        HD(1,GPT,0adcbfee-21aa-42ea-9a9a-2e53bd05e6a2,0x800,0x7f800)/File(\EFI\backup\bzImage.efi)

Microcode loading

When using a kernel without an initramfs it is recommended to load the microcode described in the following articles:

Optional: 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} /efi/EFI/example/bzImage.efi

More information is available at Secure Boot.

Warning
It is not possible to EFI Stub boot via sys-boot/shim due to the vanilla EFI Stub missing the required .sbat sbat section. As such the used signing keys must be registered directly with the UEFI firmware to EFI Stub boot with Secure Boot enabled. See the Unified Kernel Image wiki page for an alternate EFI Stub booting method that does support booting via shim.

Troubleshooting

Tip
Some rare (U)EFI implementations do not accept individual EFI entries. In this case it often works to use the removable media boot path, see EFI System Partition #removable media for details. E.g. this command will copy the kernel for a 64 bit UEFI:
root #cp /usr/src/linux/arch/x86/boot/bzImage /efi/EFI/boot/bootx64.efi
Be advised that this is against the (U)EFI specification, as it will circumvent the (U)EFI boot selection on internal drives (which are configured using EFI boot entries).
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

References

  1. ↑ The kernel doc lacks unification in the terminology. The doc page [1] is titled "(the) EFI Boot Stub", but the word "EFI stub" is also used.
Retrieved from "https://wiki.gentoo.org/index.php?title=EFI_stub&oldid=1313852"