Skip to content
LinuxHow-To Published Updated 3 min readViews unavailable

How to Build and Verify a Unified Kernel Image for UEFI Linux Boot

A distribution-aware UKI workflow covering kernel, initrd, command line, os-release, Secure Boot signing, inspection, rollout, and rollback verification.

A Unified Kernel Image (UKI) is a UEFI PE executable that bundles a Linux kernel with boot metadata and, typically, an initrd and command line. Firmware or a boot manager can execute one signed artifact instead of assembling mutable pieces from several file-system locations. That reduces ambiguity, but only if the build, signing, update, and rollback paths are controlled.

Define what the image must contain

The UKI specification defines sections such as .linux, .initrd, .cmdline, .osrel, and .uname; systemd-stub consumes them and exposes measured information to the booted system. Distribution tooling may add device trees, splash data, signatures, or policy metadata. Use the distribution’s supported kernel-install integration where possible rather than creating an untracked parallel boot pipeline.

The embedded command line is security-sensitive. Do not put plaintext disk keys or credentials in it: command-line data is broadly visible after boot. Decide whether the command line is fixed and signed, supplied externally under a Secure Boot policy, or measured for attestation. The choice affects flexibility and trust.

Build with version-matched inputs

ukify can assemble an image; exact options vary across systemd versions. A representative invocation is:

ukify build \
  --linux=/usr/lib/modules/"$KVER"/vmlinuz \
  --initrd=/boot/initramfs-"$KVER".img \
  --cmdline=@/etc/kernel/cmdline \
  --os-release=@/etc/os-release \
  --uname="$KVER" \
  --output="linux-$KVER.efi"

Consult ukify --help on the build host and pin the tool version in automation. Confirm the initrd actually contains storage, encryption, file-system, and hardware modules required to reach the root volume. A perfectly assembled image with an incomplete initrd still fails after firmware hands over control.

Inspect before signing:

ukify inspect "linux-$KVER.efi"
objdump -h "linux-$KVER.efi"
sha256sum "linux-$KVER.efi"

Verify that kernel version, OS identity, command line, and initrd are the intended release. Make builds reproducible enough that an unexpected input change is visible and retain the manifest beside the artifact.

Sign within a managed Secure Boot chain

If Secure Boot policy requires a signature, sign the completed PE image with a key trusted by the target platform. Keep private signing keys away from general build hosts where possible, protect access with hardware or an isolated signer, and record certificate identity and signing time. Rebuilding after signing changes the image and invalidates the signature.

Use sbverify or the distribution’s supported verification tool to inspect the embedded signature, then verify on a test machine with the same firmware trust enrollment. A cryptographically valid signature from an unenrolled certificate will still be rejected.

Install atomically and keep rollback

Place the UKI on the EFI System Partition through the distribution’s kernel-install or boot-manager workflow. Write a temporary file on the same file system, sync as appropriate, rename into place, and only then update the boot entry. Do not delete the last-known-good image until the new one has booted and passed acceptance checks.

Test normal boot, encrypted-root prompting, resume if supported, emergency mode, remote recovery, and kernel arguments. After boot, compare the running kernel and measured/loaded image identity with the build manifest. Then test rollback from the firmware or boot-manager interface without depending on the broken new image.

A UKI creates a clean signed unit of deployment. Its reliability still depends on correct initrd contents, explicit command-line policy, protected signing keys, atomic installation, and a rollback artifact that operators have actually booted.

Related:

Sources:

Comments