EFI stub

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.

Kernel configuration
In order to boot directly from UEFI, the kernel needs to have these options enabled:

Enable CONFIG_EFI and CONFIG_EFI_STUB support. It is also a good idea to enable CONFIG_EFI_VARS so that the system firmware can be manipulated via. CONFIG_EFI_MIXED as proposed by Gentoo Handbook is not suitable for the EFI boot stub.

UEFI does not pass kernel parameters to the kernel during normal boot, so they must be hard-coded them via CONFIG_CMDLINE values. In order to boot a root partition located at input the following text in the kernel configuration:

Using  might be preferable. To find out use :

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:

Have the ESP mounted at :

Run the install command:

Move to the right place adding the  suffix and delete the copies of config and System.map:

Alternatively the fallback directory could be used additionally to or instead of.

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

Optionally, additional kernels can be installed in and made known to the UEFI firmware. This is especially useful when wanting to test more kernels or to dual-boot with another operating system. These will be shown in the boot selection prompt, normally after a keyboard hotkey is pressed at the right time during system initialization. The latest added entry always gets highest boot priority, so it will be default. If the hotkey combination is unknown, search for official documentation from the computer manufacture. This information is usually not difficult to find.

Optional: Initramfs
In case an (optional) initramfs is needed, it also needs to be copied to the same place.

The EFI stub can load an initramfs and pass it to the kernel, but this requires passing a parameter from the EFI bootloader (ie. ). This parameter cannot be built into CONFIG_CMDLINE as outlined above. This may defeat the purpose of using EFI stub since many users prefer it as a way to avoid the necessity of a bootloader and/or dealing with. Another possibility is to embed the initramfs directly into the kernel image. In order to do this:


 * Generate the initramfs using a preferred method (Genkernel, Dracut, etc.).
 * Ensure the image is not compressed (just a cpio archive). Genkernel and Dracut both have command line switches for this.
 * Rename the initramfs with a extension, the kernel requires this in order to embed a cpio archive. The kernel image (with the cpio archive within it) will still be compressed as usual.
 * Ensure that the initramfs has the correct read-permissions for the user building the kernel. Most users build the kernel as the root user and may skip this step.
 * Be aware that Dracut makes the initramfs image readable only by the root user, so if the kernel was built as any other user adjust its permissions as needed. Failing to do so (and ignoring the kernel build warnings) will result in a kernel with no embedded initramfs which will leave the system potentially unbootable.

However, if passing an initramfs as a boot parameter is still desired, the only way it can be done is by using (GRUB2 will not work). An external initramfs has some advantages over building the initramfs directly into the kernel (see the kernel help on on the CONFIG_INITRAMFS_SOURCE variable for details on its limitations). In fact, both a built-in and external initramfs can be used simultaneously. Create and install the initramfs with Genkernel, Dracut, by hand, etc. Install the kernel as outlined in the Installation section below. Then:

External resources

 * 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.
 * EFISTUB on wiki.archlinux.org