ukifysystemdukify1ukifyCombine components into a signed Unified Kernel Image for UEFI systemsukifyOPTIONSbuildukifyOPTIONSgenkeyukifyOPTIONSinspectFILEDescriptionukify is a tool whose primary purpose is to combine components (usually a
kernel, an initrd, and 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.CommandsThe following commands are understood:buildThis command creates a Unified Kernel Image. The two primary options that should be specified for
the build verb are Linux=/, and
Initrd=/. Initrd= accepts multiple
whitespace-separated paths and can be specified multiple times.Additional sections will be inserted into the UKI, either automatically or only if a specific
option is provided. See the discussions of
Cmdline=/,
OSRelease=/,
DeviceTree=/,
Splash=/,
PCRPKey=/,
Uname=/,
SBAT=/,
and
below.ukify can also be used to assemble a PE binary that is not executable but
contains auxiliary data, for example additional kernel command line entries.If PCR signing keys are provided via the
PCRPrivateKey=/ and
PCRPublicKey=/ 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
the Phases=/ option. If not specified, the default provided
by systemd-measure is used. It is also possible to specify the
PCRPrivateKey=/,
PCRPublicKey=/, and
Phases=/ arguments more than once. Signatures will then be
performed with each of the specified keys. On the command line, 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. In the config file, PCRPrivateKey=,
PCRPublicKey=, and Phases= are grouped into separate sections,
describing separate boot phases.If a SecureBoot signing key is provided via the
SecureBootPrivateKey=/ 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.
If the stub and/or the kernel contain .sbat sections they will be merged in
the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim. For
more information on SBAT see
Shim documentation.
genkeyThis command creates the keys for PCR signing and the key and certificate used for SecureBoot
signing. The same configuration options that determine what keys and in which paths will be needed for
signing when build is used, here determine which keys will be created. See the
discussion of PCRPrivateKey=/,
PCRPublicKey=/, and
SecureBootPrivateKey=/ below.The output files must not exist.inspectDisplay information about the sections in a given binary or binaries.
If is given, all sections are shown.
Otherwise, if option is specified at least once, only those sections are shown.
Otherwise, well-known sections that are typically included in an UKI are shown.
For each section, its name, size, and sha256-digest is printed.
For text sections, the contents are printed.Also see the description of / and
.Other tools that may be useful for inspect UKIs:
llvm-objdump1
and pe-inspect.
Configuration settingsSettings can appear in configuration files (the syntax with SomeSetting=value) and on the command line (the syntax
with ). For some command
line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must
be in the appropriate section, so the descriptions are grouped by section below. When the same setting
appears in the configuration file and on the command line, generally the command line setting has higher
priority and overwrites the config file setting completely. If some setting behaves differently, this is
described below.If no config file is provided via the option ,
ukify will try to look for a default configuration file in the following paths in this
order: /run/systemd/ukify.conf, /etc/systemd/ukify.conf,
/usr/local/lib/systemd/ukify.conf, and /usr/lib/systemd/ukify.conf,
and then load the first one found. ukify will proceed normally if no configuration file
is specified and no default one is found.The LINUX and INITRD positional arguments, or
the equivalent Linux= and Initrd= settings, are optional. If more
than one initrd 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 and settings are understood:Command line-only optionsLoad configuration from the given config file. In general, settings specified in
the config file have lower precedence than the settings specified via options. In cases where the
command line option does not fully override the config file setting are explicitly mentioned in the
descriptions of individual options.Enable or disable a call to
systemd-measure1
to print pre-calculated PCR values. Defaults to false.For all verbs except inspect, the first syntax is used.
Specify an arbitrary additional section 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.For the inspect verb, the second syntax is used.
The section NAME will be inspected (if found).
If the second argument is text, the contents will be printed.
If the third argument is given, the contents will be saved to file PATH.
Note that the name is used as-is, and if the section name should start with a dot, it must be
included in NAME.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.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.Print a summary of loaded config and exit. This is useful to check how the options
from the configuration file and the command line are combined.Print all sections (with inspect verb).Generate JSON output (with inspect verb).[UKI] sectionLinux=LINUXA path to the kernel binary.Initrd=INITRD...Zero or more initrd paths. In the configuration file, items are separated by
whitespace. The initrds are combined in the order of specification, with the initrds specified in
the config file first.Cmdline=TEXT|@PATHThe 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.OSRelease=TEXT|@PATHThe 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.DeviceTree=PATHThe 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.
Splash=PATHA 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.
PCRPKey=PATHA path to a public key to embed in the .pcrpkey section. If not
specified, and there's exactly one
PCRPublicKey=/ argument, that key will be used.
Otherwise, the section will not be present.Uname=VERSIONSpecify 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.PCRBanks=PATHA 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.SecureBootSigningTool=SIGNERWhether to use sbsign or pesign.
Depending on this choice, different parameters are required in order to sign an image.
Defaults to sbsign.SecureBootPrivateKey=SB_KEYA path to a private key to use for signing of the resulting binary. If the
SigningEngine=/ option is used, this may also be
an engine-specific designation. This option is required by
SecureBootSigningTool=sbsign/. SecureBootCertificate=SB_CERTA path to a certificate to use for signing of the resulting binary. If the
SigningEngine=/ option is used, this may also
be an engine-specific designation. This option is required by
SecureBootSigningTool=sbsign/. SecureBootCertificateDir=SB_PATHA path to a nss certificate database directory to use for signing of the resulting binary.
Takes effect when SecureBootSigningTool=pesign/ is used.
Defaults to /etc/pki/pesign.SecureBootCertificateName=SB_CERTNAMEThe name of the nss certificate database entry to use for signing of the resulting binary.
This option is required by SecureBootSigningTool=pesign/.SecureBootCertificateValidity=DAYSPeriod of validity (in days) for a certificate created by
genkey. Defaults to 3650, i.e. 10 years.SigningEngine=ENGINEAn "engine" for signing of the resulting binary. This option is currently passed
verbatim to the option of
sbsign1.
SignKernel=BOOLOverride 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
SecureBootPrivateKey=/ option and the
binary has not already been signed. If
SignKernel=/ is true, and the binary has already
been signed, the signature will be appended anyway.SBAT=TEXT|@PATHSBAT metadata associated with the UKI or addon. SBAT policies are useful to revoke
whole groups of UKIs or addons with a single, static policy update that does not take space in
DBX/MOKX. If not specified manually, a default metadata entry consisting of
uki,1,UKI,uki,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html
will be used, to ensure it is always possible to revoke UKIs and addons. For more information on
SBAT see Shim documentation.
[PCRSignature:NAME] sectionIn the config file, those options are grouped by section. On the command line, they
must be specified in the same order. The sections specified in both sources are combined.
PCRPrivateKey=PATHA private key to use for signing PCR policies. On the command line, this option may
be specified more than once, in which case multiple signatures will be made.PCRPublicKey=PATHA public key to use for signing PCR policies.On the command line, 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. On the command line, if present, this option must be specified the same number of
times as the option.Phases=LISTA comma or space-separated list of colon-separated phase paths to sign a policy
for. Each set of boot phase paths will be signed with the corresponding private key. If not
present, the default of
systemd-measure1
will be used.On the command line, when this argument is present, it must appear the same number of times as
the option. ExamplesMinimal invocation$ ukify build \
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=/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$ ukify build \
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=early_cpio \
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
--sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' \
--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.All the bells and whistles, via a config fileThis is the same as the previous example, but this time the configuration is stored in a
file:$ cat ukify.conf
[UKI]
Initrd=early_cpio
Cmdline=quiet rw rhgb
SecureBootPrivateKey=sb.key
SecureBootCertificate=sb.cert
SignKernel=yes
PCRBanks=sha384,sha512
[PCRSignature:initrd]
PCRPrivateKey=pcr-private-initrd-key.pem
PCRPublicKey=pcr-public-initrd-key.pem
Phases=enter-initrd
[PCRSignature:system]
PCRPrivateKey=pcr-private-system-key.pem
PCRPublicKey=pcr-public-system-key.pem
Phases=enter-initrd:leave-initrd
enter-initrd:leave-initrd:sysinit
enter-initrd:leave-initrd:sysinit:ready
$ ukify -c ukify.conf build \
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img
One "initrd" (early_cpio) is specified in the config file, and
the other initrd (initramfs-6.0.9-300.fc37.x86_64.img) is specified
on the command line. This may be useful for example when the first initrd contains microcode for the CPU
and does not need to be updated when the kernel version changes, unlike the actual initrd.Kernel command line auxiliary PEukify build \
--secureboot-private-key=sb.key \
--secureboot-certificate=sb.cert \
--cmdline='debug' \
--sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
uki.addon.author,1,UKI Addon for System,uki.addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html'
--output=debug.cmdline
This creates a signed PE binary that contains the additional kernel command line parameter
debug with SBAT metadata referring to the owner of the addon.Decide signing policy and create certificate and keysFirst, let's create an config file that specifies what signatures shall be made:# cat >/etc/kernel/uki.conf <<EOF
EOFNext, we can generate the certificate and keys:# ukify genkey --config=/etc/kernel/uki.conf
Writing SecureBoot private key to /etc/kernel/secure-boot.key.pem
Writing SecureBoot certificate to /etc/kernel/secure-boot.cert.pem
Writing private key for PCR signing to /etc/kernel/pcr-initrd.key.pem
Writing public key for PCR signing to /etc/kernel/pcr-initrd.pub.pem
Writing private key for PCR signing to /etc/kernel/pcr-system.key.pem
Writing public key for PCR signing to /etc/kernel/pcr-system.pub.pem
(Both operations need to be done as root to allow write access
to /etc/kernel/.)Subsequent invocations using the config file
(ukify build --config=/etc/kernel/uki.conf)
will use this certificate and key files. Note that the
kernel-install8
plugin 60-ukify.install uses /etc/kernel/uki.conf
by default, so after this file has been created, installations of kernels that create a UKI on the
local machine using kernel-install will perform signing using this config.See Alsosystemd1systemd-stub7systemd-boot7systemd-measure1systemd-pcrphase.service8