Unified kernel image

From Gentoo Wiki
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.

A 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

A 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 with Dracut or with systemd's ukify tool. ukify can be used to create a UKI using any initramfs, while dracut can create a UKI and initramfs by itself.

Important
A Unified Kernel Image requires a 'stub loader'. Currently the only packaged option 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).
Tip
The kernel build system automatically calls installkernel when running make install, when sys-kernel/installkernel is installed. 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 a 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

A 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 a 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=ugrd
uki_generator=ukify

Note that ukify cannot generate an initramfs, this must be done separately with an initramfs generator such as UgRD or Dracut by enabling the corresponding USE flag on sys-kernel/installkernel.

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

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

GRUB is capable of loading a UKI payload using the chainloader command. Any parameters entered at the end of the chainloader command will be passed to the kernel. For example:

FILE /etc/grub.d/40_custom
menuentry 'Gentoo GNU/Linux, with Linux 6.11.5-gentoo' {
    uki_path=/EFI/Linux/8e6dfbd2da15a3abb3e1a5a862dd78f3-6.11.3.efi
    export uki_path
    search --set=root --efidisk-only --file $uki_path
    chainloader $uki_path root=LABEL=linux rootflags=subvol=@gentoo rootfstype=btrfs ro quiet splash
}

EFI stub

Unified kernel images can also be booted directly from UEFI firmware without the use of 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

Automated EFI stub booting

Warning
Many vendors do not follow the UEFI specification exactly. As a result automated EFI stub booting as described below is not guaranteed to work on all systems. For such systems a light-weight EFI chain-loading solution that is guaranteed to work on all UEFI systems is systemd-boot.
Systemd kernel-install

app-emulation/virt-firmware contains the kernel-bootcfg tool to assist in the creation and removal of UEFI boot entries for unified kernel images. To set this up, enable the uki, efistub and systemd USE flags on sys-kernel/installkernel and then enable the init service provided by app-emulation/virt-firmware: For systemd systems:

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

For OpenRC systems:

root #rc-update add kernel-bootcfg-boot-successful default
Note
The systemd USE flag on sys-kernel/installkernel is required, but this flag does not force a dependency on the systemd init system. The dependencies are satisfied by the boot and kernel-install flags on sys-apps/systemd-utils, as such this also works on OpenRC systems.

UEFI boot entries for Unified Kernel Images will now be automatically created and removed. To create one for the currently running kernel the kernel must be reinstalled using either emerge --config gentoo-kernel{,-bin} (for distribution kernels) or make install (for manually managed kernels).

When sys-boot/shim is installed and present on to the EFI System Partition, kernel-bootcfg will register unified kernel images for booting via shim. This may be useful for user who wish to boot unified kernel images with Secure Boot enabled, without registering custom keys in the system's firmware. To setup kernel-bootcfg to use shim, install it to the EFI System Partition, while substituting x64 for the system's UEFI architecture and ${ESP} for the mount point of the EFI System Partition:

root #emerge --ask sys-boot/shim
root #cp /usr/share/shim/BOOTX64.EFI ${ESP}/EFI/Gentoo/shimx64.efi
root #cp /usr/share/shim/mmx64.efi ${ESP}/EFI/Gentoo/mmx64.efi

In addition to automated registration via installkernel, it is also possible to register a new UKI manually:

root #kernel-bootcfg --add-uki ${ESP}/EFI/Linux/linux-x.y.z-gentoo-dist.efi --title x.y.z-gentoo-dist --once
Tip
The --once argument will register the new entry, but not add it to the boot order yet. Instead it will instruct the system to boot the new UKI on the next reboot once (i.e. set the BootNext EFI variable). Upon a successful boot the kernel-bootcfg-boot-successful init service will then add the new UKI to the top of the boot order.

And to manually remove an entry for a given UKI:

root #kernel-bootcfg --remove-uki ${ESP}/EFI/Linux/linux-x.y.z-gentoo-dist.efi
Traditional installkernel

For non-systemd systems, automated EFI Stub booting is implemented using sys-boot/uefi-mkconfig. To set this up, enable the uki and efistub USE flags and disable the systemd USE flag on sys-kernel/installkernel. Then reinstall the kernel. uefi-mkconfig will boot new entries via Shim if sys-boot/shim is installed and the shim EFI executable is present in the same directory as the kernel images (i.e. ESP/EFI/Linux).

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 of the security of the pre-boot process of a UEFI system.
  • Shim — an alternative method of managing accepted Secure Boot keys without touching the UEFI firmware settings
  • Dracut — an initramfs infrastructure and aims to have as little as possible hard-coded into the initramfs.
  • EFI stub — describes EFI stub kernels, i.e. kernels directly executable from UEFI.
Retrieved from "https://wiki.gentoo.org/index.php?title=Unified_kernel_image&oldid=1339266"