Unified Kernel Image by Gentoo

What is a Unified Kernel Image (UKI)?
A UKI is a single executable which can be booted directly from UEFI firmware or automatically sourced by bootloaders with little or no configuration.

What does a Unified Kernel Image (UKI) allow you to incorporate?
A UKI allows you to incorporate:

  • An EFI stub loader.
  • The kernel command line.
  • Microcode.
  • An initramfs image.
  • A kernel image.
  • A splash screen.

What can you easily do with a Unified Kernel Image (UKI)?
With a UKI, you can easily sign it for use with Secure Boot.

Supported architectures

What does a Unified Kernel Image (UKI) require?
A UKI requires a stub loader.

What is the only stub loader available for Unified Kernel Images (UKIs)?
The only stub loader available for UKIs is systemd-stub.

What architectures is systemd-stub available for?
The architectures that systemd-stub is available for are:

  • amd64.
  • x86.
  • arm64.

What kernel configuration setting must be set if you're using arm64 and what should that setting be set to?
If you're using arm64, the kernel configuration setting that must be set is the CONFIG_EFI_ZBOOT setting, which must be set to =y.

Todo

This section explains why CONFIG_EFI_ZBOOT is required to be set to =y for arm64 systems. It shows how to change this setting automatically and manually.

Configuration

What are the two programs you can use to generate a Unified Kernel Image (UKI)?
The two programs you can use to generate a UKI are:

  1. Dracut.
  2. systemd's ukify.

What can ukify not do and what other program needs to be used for it?
ukify can't generate an initramfs and the other program which needs to be used for it is Dracut.

What are the two ways to download systemd-stub?
The two ways to download systemd-stub are:

  • Enabling the boot USE flag on sys-apps/systemd (for systemd).
  • Enabling the boot USE flag on sys-apps/systemd-utils (for OpenRC).

What does the kernel build system call automatically if sys-kernel/installkernel is installed and when?
If sys-kernel/installkernel is installed, the kernel build system automatically calls installkernel when make install runs.

What can installkernel be configured to do and with what USE flag?
installkernel can be configured to generate and install UKIs to the EFI/Linux directory on the ESP with the uki USE flag.

Dracut

What will Dracut do automatically as of version 059-r4?
As of version 059-r4, Dracut will automatically pick up the layout setting and generate a UKI instead of an initramfs.

What can be done with the Unified Kernel Image (UKI) that Dracut generates?
The UKI that Dracut generates can be installed to the ESP.

What two USE flags must be enabled with sys-kernel/installkernel?
The two USE flags which must be enabled with sys-kernel/installkernel are:

  1. dracut.
  2. uki.

How will the /usr/lib/kernel/install.conf file for the kernel be automatically configured with the dracut and uki USE flags enabled?
With the dracut and uki USE flags enabled, the /usr/lib/kernel/install.conf file for the kernel will automatically be configured like so:

layout=uki
initrd_generator=dracut
uki_generator=dracut

What does Dracut allow you to do since a Unified Kernel Image (UKI) can contain a kernel command line?
Since a UKI can contain a kernel command line, Dracut allows you to specify the kernel command line to be included in the UKI.

How do you specify the kernel command line to be included in the Unified Kernel Image (UKI) which Dracut generates?
To specify the kernel command line to be included in the UKI which Dracut generates, include this option in /etc/dracut.conf:

kernel_cmdline="..."

What file isn't used when configuring the kernel command line to be used in the Unified Kernel Image (UKI) which Dracut generates?
The file that isn't used when configuring the kernel command line to be used in the UKI which Dracut generates is /etc/kernel/cmdline.

Which program uses /etc/kernel/cmdline to configure the kernel command line for a Unified Kernel Image (UKI) and when?
The program that uses /etc/kernel/cmdline to configure the kernel command line for a UKI is ukify when generating entries for systemd-boot.

Secure Boot

What options in the /etc/dracut.conf file can you use to automatically sign the Unified Kernel Image (UKI) for use with Secure Boot?
The options in the /etc/dracut.conf file you can use to automatically sign the UKI for use with Secure Boot are:

  1. uefi_secureboot_cert="...".
  2. uefi_secureboot_key="...".

To successfully boot with Secure Boot enabled, the ... ... should also be signed if one is used.
To successfully boot with Secure Boot enabled, the boot loader should also be signed if one is used.

What program can you use to sign the boot loader so it can be booted with Secure Boot?
To sign the boot loader so that it can be booted with Secure Boot, you can use sbsign from the app-crypt/sbsigntools package.

What needs to be done with the UEFI firmware so that the signed boot loader can be booted with Secure Boot?
For the signed boot loader to be booted with Secure Boot, the UEFI firmware needs to be configured to accept the key that was used.

What are the three ways you can configure the UEFI firmware to accept the key that was used to sign the boot loader?
The three ways you can configure the UEFI firmware to accept the key that was used to sign the boot loader are:

  1. Manually.
  2. Automatically generate and enroll a set of keys with app-crypt/sbctl.
  3. Using shim as a pre-loader which is already signed with the 3rd-party Microsoft key accepted by most UEFI-enabled motherboards.

Ukify

Todo

This section of the article talks about configuring ukify to generate and install a Unified Kernel Image (UKI) just like Dracut. Since I'm using OpenRC, this section isn't entirely relevant to my system. I will ignore it for now and revisit it if necessary.

systemd-boot and rEFInd

What two boot loaders can automatically detect installed Unified Kernel Images (UKI)?
The two boot loaders which can automatically detect installed UKIs are:

  1. systemd-boot.
  2. rEFInd.

What directory do systemd-boot and rEFInd check for Unified Kernel Images (UKIs)?
The directory that systemd-boot and rEFInd check for UKIs is the Linux directory of the ESP.

What USE flag should be enabled for sys-kernel/installkernel so that rEFInd uses the correct icon for the installed Unified Kernel Image (UKI)?
The USE flag which should be enabled for sys-kernel/installkernel so that rEFInd uses the correct icon for the installed UKI is the refind USE flag.

GRUB

How do you load Unified Kernel Images (UKIs) with GRUB?
To load UKIs with GRUB, use the chainloader command.

What is done to the parameters entered at the end of the chainloader command?
The parameters entered at the end of the chainloader command are passed to the kernel.

Example of a GRUB configuration stored in /etc/grub.d/40_custom which creates a menu entry for loading a UKI
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

What program can you use to add a Unified Kernel Image (UKI) as a boot menu entry?
The program you can use to add a UKI as a boot menu entry is efibootmgr.

Example of using efibootmgr to add a Unified Kernel Image (UKI) as a boot menu entry
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

If EFI stub doesn't work, what light-weight EFI chain-loading solution is guaranteed to work on all UEFI systems?
If EFI stub doesn't work, the light-weight EFI chain-loading solution that's guaranteed to work on all UEFI systems is systemd-boot.

Systemd kernel-install

What program can assist in creating and removing UEFI boot entries for Unified Kernel Images (UKIs)?
The program which can assist in creating and removing UEFI boot entries for UKIs is kernel-bootcfg.

Which package contains kernel-bootcfg?
The package that contains kernel-bootcfg is app-emulation/virt-firmware.

What three USE flags for sys-kernel/installkernel need to be enabled to set up kernel-bootcfg?
To set up kernel-bootcfg, the three USE flags that need to be enabled for sys-kernel/installkernel are:

  1. uki.
  2. efistub.
  3. systemd.

What needs to be enabled in order for kernel-bootcfg to automatically create and remove UEFI boot entries and how do you do it for systemd and OpenRC?
For kernel-bootcfg to automatically create and remove UEFI boot entries, the init service provided by app-emulation/virt-firmware needs to be enabled and you do it like so:

  • systemctl enable --now kernel-bootcfg-boot-successful.service (for systemd).
  • rc-update add kernel-bootcfg-boot-successful default (for OpenRC).

Although the systemd USE flag on sys-kernel/installkernel is required for setting up kernel-bootcfg, what does it not create and why?
Although the systemd USE flag on sys-kernel/installkernel is required for setting up kernel-bootcfg, it doesn't create a dependency on systemd because the dependencies are satisfied by the boot and kernel-install flags on sys-apps/systemd-utils.

How do you create a UEFI boot entry for the currently installed kernel after setting up kernel-bootcfg
To create a UEFI boot entry for the currently installed kernel after setting up kernel-bootcfg, the kernel must be reinstalled with either emerge --config gentoo-kernel{,-bin} for distribution kernels or make install for managed kernels.

What can kernel-bootcfg do if sys-boot/shim is installed and present on the EFI System Partition (ESP)?
If sys-boot/shim is installed and present on the ESP, kernel-bootcfg can register the UKIs for booting via shim.

How do you set up kernel-bootcfg to use shim?
To set up kernel-bootcfg to use shim:

  1. Run emerge --ask sys-boot/shim.
  2. Run cp /usr/share/shim/BOOTX64.efi ${ESP}/EFI/Gentoo/shimx64.efi.
  3. Run cp /usr/share/shim/mmx64.efi ${ESP}/EFI/Gentoo/mmx64.efi.

How do you manually register a new Unified Kernel Image (UKI) with kernel-bootcfg?
To manually register a new UKI with kernel-bootcfg, run kernel-bootcfg --add-uki ${ESP}/EFI/Linux/linux-x.y.z-gentoo-dist.efi --title x.y.z.gentoo-dist --once.

What does the --once flag do when used with kernel-bootcfg?
When used with kernel-bootcfg, the --once flag will tell kernel-bootcfg to register the new entry but not add it to the top of the boot order until the system successfully reboots once.

How do you manually remove a boot entry for a given Unified Kernel Image (UKI)?
To manually remove a boot entry for a given UKI, run kernel-bootcfg --remove-uki ${ESP}/EFI/Linux/linux-x.y.z-gentoo-dist.efi.

Traditional installkernel

How is automated EFI stub booting implemented on non-systemd systems?
On non-systemd systems, EFI stub booting is implemented using sys-boot/uefi-mkconfig.

How do you set up sys-boot/uefi-mkconfig?
To set up sys-boot/uefi-mkconfig:

  1. Enable the uki and efistub USE flags and disable the systemd USE flag for sys-kernel/installkernel.
  2. Reinstall the kernel.

What will sys-boot/uefi-mkconfig boot new entries with if what is installed?
sys-boot/uefi-mkconfig will boot new entries with shim if sys-boot/shim is installed and the shim EFI executable is present in the same directory as the kernel images.