Unified kernel image

From Gentoo Wiki
(Redirected from UKI)
Jump to:navigation Jump to:search
Resources

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:

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

Supported architectures

An unified kernel image requires a stub loader, e.g. systemd-stub. Currently systemd-stub is available for amd64, x86 and arm64. On arm64 the kernel must be configured with CONFIG_EFI_ZBOOT=y since systemd-stub does not support decompressing the kernel image and as such the kernel must be built with its own decompressor (zboot). This config option exists since kernel version 6.1, and is enabled in version 6.5 and up of gentoo-kernel-bin. In sys-kernel/gentoo-kernel and sys-kernel/vanilla-kernel this option is enabled when the secureboot USE flag is enabled. It may also be configured manually:

FILE /etc/kernel/config.d/zboot.conf
CONFIG_EFI_ZBOOT=y

Configuration

Generating a Unified Kernel Image (UKI) 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.

An Unified Kernel Image requires a stub loader. Currently the only one available is systemd-stub, which must be installed by enabling the boot USE flag on sys-apps/systemd (for systemd systems) or sys-apps/systemd-utils (for openrc systems}}.

When sys-kernel/installkernel is installed the kernel build system will call installkernel automatically when running make install. Installkernel can be configured to generate and install UKIs to the EFI/Linux directory on the EFI system partition with the uki USE flag.

Dracut

As of sys-kernel/dracut version 059-r4 the Dracut installkernel plugin will automatically pick up the layout setting and generate an UKI instead of an initramfs. The resulting image will then be installed to the EFI System Partition.

Therefore no additional configuration is required other then enabling the dracut and uki flag on sys-kernel/installkernel. This USE configuration results in an install.conf as follows:

FILE /usr/lib/kernel/install.conf
layout=uki
initrd_generator=dracut
uki_generator=dracut

An Unified Kernel Image may contain a kernel command line, Dracut allows one to specified via /etc/dracut.conf. Note that any kernel command line supplied by the bootloader overrides this include command line, except when Secure Boot is enabled:

FILE /etc/dracut.conf
kernel_cmdline="..."
Warning
/etc/kernel/cmdline is not used when generating Unified Kernel Images with Dracut! This file is used by ukify and when generating entries for systemd-boot.

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 tool can be used to generate an unified kernel image. To configure installkernel to use it enable the uki and ukify USE flags. This USE configuration results in an install.conf as follows:

FILE /usr/lib/kernel/install.conf
layout=uki
initrd_generator=dracut
uki_generator=ukify

Note that ukify cannot generate an initramfs, this must be done separately with for example Dracut by enabling the dracut USE flag on sys-kernel/installkernel as well.

When ukify is used, the included kernel command line is configured in /etc/kernel/cmdline. Note that any kernel command line supplied by the bootloader overrides this include command line, except when Secure Boot is enabled.

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

systemd-boot and rEFInd dynamically detect the UKIs installed in the Linux directory on the EFI System Partition, no further configuration is required. Though users of rEFInd might want to enable the refind USE flag on sys-kernel/installkernel to ensure rEFInd will use the correct icon for the installed UKI.

GRUB's grub-mkconfig by default will not discover the UKIs installed on the EFI System Partition. When grub-mkconfig is called manually it can be made to find the UKI's by setting the GRUB_LINUX_KERNEL_GLOBS environment variable:

root #GRUB_LINUX_KERNEL_GLOBS="/boot/vmlinuz-* /boot/vmlinux-* /boot/kernel-* /vmlinuz-* /vmlinux-* /${ESP}/EFI/Linux/*.efi

Here ${ESP} should be replaced with the path to the EFI System Partition. When the grub USE flag is enabled on sys-kernel/installkernel the required GRUB_LINUX_KERNEL_GLOBS is set automatically and no further configuration is required.

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, this is currently not automated via sys-kernel/installkernel:

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