ukifysystemdukify1ukifyCombine kernel and initrd into a signed Unified Kernel Image/usr/lib/systemd/ukifyLINUXINITRDOPTIONSDescriptionNote: this command is experimental for now. While it is intended to become a regular component of
systemd, it might still change in behaviour and interface.ukify is a tool that combines a kernel and an initrd with
a UEFI boot stub to create a
Unified Kernel Image (UKI)
— a PE binary that can be executed by the firmware to start the embedded linux kernel.
See systemd-stub7
for details about the stub.Additional sections will be inserted into the UKI, either automatically or only if a specific
option is provided. See the discussions of
,
,
,
,
,
,
and
below.If PCR signing keys are provided via the and
options, PCR values that will be seen after booting with the given
kernel, initrd, and other sections, will be calculated, signed, and embedded in the UKI.
systemd-measure1 is
used to perform this calculation and signing.The calculation of PCR values is done for specific boot phase paths. Those can be specified with
option. If not specified, the default provided by
systemd-measure is used. It is also possible to specify the
, , and
arguments more than once. Signatures will be then performed with each of the specified keys. When both
and are used, they must be specified the
same number of times, and then the n-th boot phase path set will be signed by the n-th key. This can be
used to build different trust policies for different phases of the boot.If a SecureBoot signing key is provided via the option,
the resulting PE binary will be signed as a whole, allowing the resulting UKI to be trusted by
SecureBoot. Also see the discussion of automatic enrollment in
systemd-boot7.
OptionsNote that the LINUX positional argument is mandatory. The
INITRD positional arguments are optional. If more than one is specified, they
will all be combined into a single PE section. This is useful to for example prepend microcode before the
actual initrd.The following options are understood:Specify the kernel command line (the .cmdline section). The
argument may be a literal string, or @ followed by a path name. If not specified,
no command line will be embedded.Specify the os-release description (the .osrel section). The
argument may be a literal string, or @ followed by a path name. If not specified,
the os-release5
file will be picked up from the host system.Specify the devicetree description (the .dtb section). The
argument is a path to a compiled binary DeviceTree file. If not specified, the section will not be
present.Specify a picture to display during boot (the .splash section).
The argument is a path to a BMP file. If not specified, the section will not be present.
Specify a path to a public key to embed in the .pcrpkey section.
If not specified, and there's exactly one argument, that key will
be used. Otherwise, the section will not be present.Specify the kernel version (as in uname -r, the
.uname section). If not specified, an attempt will be made to extract the version
string from the kernel image. It is recommended to pass this explicitly if known, because the
extraction is based on heuristics and not very reliable. If not specified and extraction fails, the
section will not be present.Specify an arbitrary additional section
NAME. Note that the name is used as-is, and if the
section name should start with a dot, it must be included in NAME. The
argument may be a literal string, or @ followed by a path name. This option may be
specified more than once. Any sections specified in this fashion will be inserted (in order) before
the .linux section which is always last.Specify a private key to use for signing PCR policies. This option may be specified
more than once, in which case multiple signatures will be made.Specify a public key to use for signing PCR policies. This option may be specified
more than once, similarly to the option. If not present, the
public keys will be extracted from the private keys. If present, the this option must be specified
the same number of times as the option.A comma or space-separated list of colon-separated phase paths to sign a policy for.
If not present, the default of
systemd-measure1
will be used. When this argument is present, it must appear the same number of times as the
option. Each set of boot phase paths will be signed with the
corresponding private key.A comma or space-separated list of PCR banks to sign a policy for. If not present,
all known banks will be used (sha1, sha256,
sha384, sha512), which will fail if not supported by the
system.A path to a private key to use for signing of the resulting binary. If the
option is used, this may also be an engine-specific
designation.A path to a certificate to use for signing of the resulting binary. If the
option is used, this may also be an engine-specific
designation.An "engine" to for signing of the resulting binary. This option is currently passed
verbatim to the option of
sbsign1.
Override the detection of whether to sign the Linux binary itself before it is
embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is
provided via the option and the binary has not already
been signed. If is specified, and the binary has already been signed,
the signature will be appended anyway.Specify one or more directories with helper tools. ukify will look
for helper tools in those directories first, and if not found, try to load them from
$PATH in the usual fashion.Enable or disable a call to systemd-measure to print
pre-calculated PCR values. Defaults to false.The output filename. If not specified, the name of the
LINUX argument, with the suffix .unsigned.efi or
.signed.efi will be used, depending on whether signing for SecureBoot was
performed.ExamplesMinimal invocationukify \
/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
--cmdline='quiet rw'
This creates an unsigned UKI ./vmlinuz.unsigned.efi.All the bells and whistles/usr/lib/systemd/ukify \
/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
early_cpio \
/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
--pcr-private-key=pcr-private-initrd-key.pem \
--pcr-public-key=pcr-public-initrd-key.pem \
--phases='enter-initrd' \
--pcr-private-key=pcr-private-system-key.pem \
--pcr-public-key=pcr-public-system-key.pem \
--phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
enter-initrd:leave-initrd:sysinit:ready' \
--pcr-banks=sha384,sha512 \
--secureboot-private-key=sb.key \
--secureboot-certificate=sb.cert \
--sign-kernel \
--cmdline='quiet rw rhgb'
This creates a signed UKI ./vmlinuz.signed.efi.
The initrd section contains two concatenated parts, early_cpio
and initramfs-6.0.9-300.fc37.x86_64.img.
The policy embedded in the .pcrsig section will be signed for the initrd (the
enter-initrd phase) with the key
pcr-private-initrd-key.pem, and for the main system (phases
leave-initrd, sysinit, ready) with the
key pcr-private-system-key.pem. The Linux binary and the resulting
combined image will be signed with the SecureBoot key sb.key.See Alsosystemd1,
systemd-stub7,
systemd-boot7,
objcopy1,
systemd-pcrphase.service8