Unified kernel image

Resources

GitHub

A unified kernel image (UKI) is a single executable which can be booted directly from UEFI firmware, or automatically sourced by boot-loaders with little or no configuration.

An unified kernel image allows to incorporate all or a subset of the following:

• a EFI stub loader like systemd-stub,
• the kernel command line,
• Microcode,
• an initramfs image,
• a kernel image,
• a splash screen.

The resulting executable, and therefore all these elements together can then be easily signed for use with Secure Boot.

Configuration

Generating a Unified Kernel Image can be done either with Dracut or with systemd's ukify tool. The latter does not generate an initramfs, this will have to be done separately with e.g. Dracut.

The systemd kernel-install implementation provided by sys-apps/systemd or sys-apps/systemd-utils[boot] can be configured to install kernels in the UKI format:

FILE /etc/kernel/install.conf

layout=uki

Dracut

As of sys-kernel/dracut version 059-r4 the Dracut kernel-install plugin will automatically pick up the layout setting and generate an uki instead of an initrd when used with the systemd kernel-install implementation. The resulting image will then be installed to the EFI System Partition.

The kernel build system will call kernel-install automatically when running make install. Therefore no additional configuration is required for users of manually configured kernels such as sys-kernel/gentoo-sources. Users who wish to use the pre-configured sys-kernel/gentoo-kernel instead will have to explicitly configure Dracut to generate UKIs:

FILE /etc/kernel/install.conf

layout=uki
uki_generator=dracut
initrd_generator=dracut

FILE /etc/dracut.conf

uefi="yes"
kernel_cmdline="..."

Warning
/etc/kernel/cmdline is not used when generating Unified Kernel Images with Dracut! This file is used by kernel-install to write a kernel command line setting to the bootloader configuration. When using Unified Kernel Images the kernel command line is not specified by the bootloader, instead it is embedded in the image. This embedded kernel command line is set by the kernel_cmdline Dracut configuration parameter.

Secure Boot

To automatically sign the generated UKI for use with Secure Boot:

FILE /etc/dracut.conf

uefi_secureboot_cert="..." 
uefi_secureboot_key="..."

To use a PKCS11 URI instead of a plain key file:

FILE /etc/dracut.conf

uefi_secureboot_cert="..." 
uefi_secureboot_key="pkcs11:..."
uefi_secureboot_engine="pkcs11"

Note
To successfully boot with Secure Boot enabled the Boot Loader should also be signed if one is used. This can be done using the sbsign tool from app-crypt/sbsigntools. Additionally, the UEFI firmware should be configured to accept the used key, this can be done manually or alternatively app-crypt/sbctl can be used to automatically generate and enroll a set of keys. It is also possible to use shim as a pre-loader that is already signed with the 3rd-party Microsoft key, accepted by default on most UEFI enabled motherboards.

Ukify

As of sys-apps/systemd version 254, the ukify kernel-install plugin can be used to generate the unified kernel image. To configure kernel-install to use it:

FILE /etc/kernel/install.conf

layout=uki
uki_generator=ukify
initrd_generator=dracut

FILE /etc/kernel/uki.conf

[UKI]
Cmdline=...

FILE /etc/dracut.conf

uefi="no"

Secure Boot

To automatically sign the generated UKI for use with Secure Boot:

FILE /etc/kernel/uki.conf

[UKI]
SecureBootSigningTool=sbsign
SecureBootPrivateKey=...
SecureBootCertificate=...

To use a PKCS11 URI instead of a plain key file:

FILE /etc/kernel/uki.conf

[UKI]
SecureBootSigningTool=sbsign
SecureBootPrivateKey=pkcs11:...
SecureBootCertificate=...
SigningEngine=pkcs11

Measured Boot

To instruct ukify to pre-calculate and sign PCR values for use with Measured Boot:

FILE /etc/kernel/uki.conf

[PCRSignature:initrd]
PCRPrivateKey=...
PCRPublicKey=...
Phases=enter-initrd

[PCRSignature:system]
PCRPrivateKey=...
PCRPublicKey=...
Phases=enter-initrd:leave-initrd
       enter-initrd:leave-initrd:sysinit
       enter-initrd:leave-initrd:sysinit:ready

Boot Loaders

Boot Loaders with support for unified kernel images dynamically detect UKIs in the Linux directory on the EFI System Partition, no further configuration is required. Currently the following boot loaders support unified kernel images:

• systemd-boot
• rEFInd
• GRUB (version 2.12 and up)

Unified kernel images can also be booted directly from UEFI firmware without any boot loader. Efibootmgr can be used to add or remove boot menu entries for unified kernel images:

root #efibootmgr --create --disk /dev/sdX --part partition_number --label "Gentoo Linux x.y.z" --loader 'EFI\Linux\linux-x.y.z-gentoo.efi' --unicode

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.
• Secure Boot — an enhancement the security of the pre-boot process of a UEFI system.
• Dracut — an initramfs infrastructure and aims to have as little as possible hard-coded into the initramfs.
• EFI stub — provides instructions on configuring and installing kernels in the EFI System Partition (ESP) of a computer running in EFI mode