|
HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | COMMANDS | CONFIGURATION SETTINGS | EXAMPLES | SEE ALSO | NOTES | COLOPHON |
|
|
|
UKIFY(1) ukify UKIFY(1)
ukify - Combine components into a signed Unified Kernel Image for
UEFI systems
ukify [OPTIONS...] build
ukify [OPTIONS...] genkey
ukify [OPTIONS...] inspect FILE...
ukify 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)[1] — a PE binary that can be executed
by the firmware to start the embedded linux kernel. See
systemd-stub(7) for details about the stub.
The following commands are understood:
build
This command creates a Unified Kernel Image. The two primary
options that should be specified for the build verb are
Linux=/--linux=, and Initrd=/--initrd=. Initrd= accepts multiple
whitespace-separated paths and --initrd= 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 Microcode=/--microcode=, Cmdline=/--cmdline=,
OSRelease=/--os-release=, DeviceTree=/--devicetree=,
DeviceTreeAuto=/--devicetree-auto=, HWIDs=/--hwids=,
Splash=/--splash=, PCRPKey=/--pcrpkey=, Uname=/--uname=,
SBAT=/--sbat=, and --section= 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=/--pcr-private-key= and
PCRPublicKey=/--pcr-public-key= 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-measure(1) 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=/--phases= option.
If not specified, the default provided by systemd-measure is used.
It is also possible to specify the
PCRPrivateKey=/--pcr-private-key=,
PCRPublicKey=/--pcr-public-key=, and Phases=/--phases= arguments
more than once. Signatures will then be performed with each of the
specified keys. On the command line, when both --phases= and
--pcr-private-key= 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 one of
SigningEngine=/--signing-engine= or
SigningProvider=/--signing-provider= is specified, then the
private key arguments will be passed verbatim to OpenSSL as URIs,
and the public key arguments will be loaded as X.509 certificates,
so that signing can be performed with an OpenSSL engine or
provider respectively.
If a SecureBoot signing key is provided via the
SecureBootPrivateKey=/--secureboot-private-key= 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-boot(7).
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[2].
genkey
This 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=/--pcr-private-key=,
PCRPublicKey=/--pcr-public-key=, and
SecureBootPrivateKey=/--secureboot-private-key= below.
The output files must not exist.
inspect
Display information about the sections in a given binary or
binaries. If --all is given, all sections are shown. Otherwise, if
--section= 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 -j/--json= and --section=.
Other tools that may be useful for inspect UKIs: llvm-objdump(1)
-p and pe-inspect.
Settings can appear in configuration files (the syntax with
SomeSetting=value) and on the command line (the syntax with
--some-setting=value). 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 --config=PATH, ukify
will try to look for a default configuration file in the following
paths in this order: /etc/systemd/ukify.conf,
/run/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 options
--config=PATH
Load 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.
Added in version 254.
--measure, --no-measure
Enable or disable a call to systemd-measure(1) to print
pre-calculated PCR values. Defaults to false.
Added in version 253.
--policy-digest, --no-policy-digest
Enable or disable a call to systemd-measure(1) to print
pre-calculated TPM2 policy digests. Useful for offline signing
of PCR policies. Defaults to false.
Added in version 258.
--section=NAME:TEXT|@PATH, --section=NAME:text|binary[@PATH]
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 the file named 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.
Added in version 253.
--join-profile=PATH
Takes a path to an existing PE file containing an additional
profile to add to the unified kernel image. The profile can be
generated beforehand with ukify. The profile does not need to
be signed or contain PCR measurements. All UKI PE sections of
the specified PE file are copied into the generated UKI. This
is useful for generating multi-profile UKIs. Note that this
only copies PE sections that are defined by the UKI
specification, and ignores any other, for example ".text" or
similar.
Added in version 257.
--sign-profile=ID
Takes a profile ID for which signed PCR measurements should be
generated by ukify. This option can be used together with
--join-profile= when building the final unified kernel image.
If not specified, signed PCR measurements will be added for
all profiles.
Added in version 258.
--tools=DIRS
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.
Added in version 253.
--output=FILENAME
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.
Added in version 253.
--summary
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.
Added in version 254.
--all
Print all sections (with inspect verb).
Added in version 255.
--json
Generate JSON output (with inspect verb).
Added in version 255.
-h, --help
Print a short help text and exit.
--version
Print a short version string and exit.
[UKI] section
Linux=LINUX, --linux=LINUX
A path to the kernel binary.
Added in version 254.
OSRelease=TEXT|@PATH, --os-release=TEXT|@PATH
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-release(5) file will be picked
up from the host system.
Added in version 253.
Cmdline=TEXT|@PATH, --cmdline=TEXT|@PATH
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.
Added in version 253.
Initrd=INITRD..., --initrd=LINUX
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.
Added in version 254.
Microcode=UCODE, --microcode=UCODE
Path to initrd containing microcode updates. If not specified,
the section will not be present.
Added in version 256.
Splash=PATH, --splash=PATH
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.
Added in version 253.
DeviceTree=PATH, --devicetree=PATH
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.
Added in version 253.
DeviceTreeAuto=PATH..., --devicetree-auto=PATH
Zero or more automatically selectable DeviceTree files. In the
configuration file, items are separated by whitespace. Each
DeviceTree will be in a separate ".dtbauto" section.
Added in version 257.
HWIDs=PATH, --hwids=PATH
The hardware ID device table (the ".hwids" section). The
argument is a path to a directory with JSON HWID device
description files. Each file needs to contain a single JSON
object with a "name", "compatible" and "hwids" keys. The
"name" and "compatible" keys must have string values and the
"hwids" key must have a list of strings as value, where the
strings must be valid UUIDs that represent CHIDs/HWIDs.
Example:
{
"type": "devicetree",
"name": "Example Laptop 16 Gen 7",
"compatible": "example,laptop-16-g7",
"hwids": [
"5dc05bf4-01f6-4089-b464-a08c47ea9295",
"3e3f8f3c-2003-46f2-811c-85554f7d5952"
]
}
Here "Example Laptop 16 Gen 7" is the device "name" (as
defined by the manufacturer), "example,laptop-16-g7" is the
"compatible" (as defined by the kernel) and "hwids" is an
array of CHIDs/HWIDs (extracted i.e. from fwupdtool hwids
output). If not specified, the section will not be present. It
is recommended to specify this parameter if automatically
selectable DeviceTrees are to be used.
Added in version 257.
Uname=VERSION, --uname=VERSION
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.
Added in version 253.
SBAT=TEXT|@PATH, --sbat=TEXT|@PATH
SBAT 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://uapi-group.org/specifications/specs/unified_kernel_image/
for UKIs and
uki-addon,1,UKI Addon,addon,1,https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html
for addons will be used, to ensure it is always possible to
revoke them. For more information on SBAT see Shim
documentation[2].
Added in version 254.
PCRPKey=PATH, --pcrpkey=PATH
A path to a public key to embed in the ".pcrpkey" section. If
not specified, and there's exactly one
PCRPublicKey=/--pcr-public-key= argument, that key will be
used. Otherwise, the section will not be present.
Added in version 253.
Profile=PATH, --profile=PATH
A path to a UKI profile to place in an ".profile" section.
This option is useful for creating multi-profile UKIs, and is
typically used in combination with --join-profile=, to extend
the specified UKI with an additional profile.
Added in version 257.
PCRBanks=PATH, --pcr-banks=PATH
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.
Added in version 253.
SecureBootSigningTool=SIGNER, --signtool=SIGNER
Whether to use "sbsign", "pesign", or "systemd-sbsign".
Depending on this choice, different parameters are required in
order to sign an image. Defaults to "sbsign".
Added in version 254.
SecureBootPrivateKey=SB_KEY, --secureboot-private-key=SB_KEY
A path to a private key to use for signing of the resulting
binary. If the SigningEngine=/--signing-engine= or
SigningProvider=/--signing-provider= option is used, this may
also be an engine or provider specific designation. This
option is required by
SecureBootSigningTool=sbsign/--signtool=sbsign.
Added in version 253.
SecureBootCertificate=SB_CERT, --secureboot-certificate=SB_CERT
A path to a certificate to use for signing of the resulting
binary. If the SigningEngine=/--signing-engine= or
SigningProvider=/--signing-provider= option is used, this may
also be an engine or provider specific designation. This
option is required by
SecureBootSigningTool=sbsign/--signtool=sbsign.
Added in version 253.
SecureBootCertificateDir=SB_PATH,
--secureboot-certificate-dir=SB_PATH
A path to a nss certificate database directory to use for
signing of the resulting binary. Takes effect when
SecureBootSigningTool=pesign/--signtool=pesign is used.
Defaults to /etc/pki/pesign.
Added in version 254.
SecureBootCertificateName=SB_CERTNAME,
--secureboot-certificate-name=SB_CERTNAME
The name of the nss certificate database entry to use for
signing of the resulting binary. This option is required by
SecureBootSigningTool=pesign/--signtool=pesign.
Added in version 254.
SecureBootCertificateValidity=DAYS,
--secureboot-certificate-validity=DAYS
Period of validity (in days) for a certificate created by
genkey. Defaults to 3650, i.e. 10 years.
Added in version 254.
SigningEngine=ENGINE, --signing-engine=ENGINE
An OpenSSL engine to be used for signing the resulting binary
and PCR measurements.
Added in version 253.
SigningProvider=PROVIDER, --signing-provider=PROVIDER
An OpenSSL provider to be used for signing the resulting
binary and PCR measurements. This option can only be used when
using systemd-sbsign as the signing tool.
Added in version 257.
CertificateProvider=PROVIDER, --certificate-provider=PROVIDER
An OpenSSL provider to be used for loading the certificate
used to sign the resulting binary and PCR measurements. This
option can only be used when using systemd-sbsign as the
signing tool.
Added in version 257.
SignKernel=BOOL, --sign-kernel, --no-sign-kernel
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
SecureBootPrivateKey=/--secureboot-private-key= option and the
binary has not already been signed. If
SignKernel=/--sign-kernel is true, and the binary has already
been signed, the signature will be appended anyway.
Added in version 253.
[PCRSignature:NAME] section
In 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=PATH, --pcr-private-key=PATH
A 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.
Added in version 253.
PCRPublicKey=PATH, --pcr-public-key=PATH
A public key to use for signing PCR policies.
On the command line, this option may be specified more than
once, similarly to the --pcr-private-key= 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 --pcr-private-key=
option.
Added in version 253.
Phases=LIST, --phases=LIST
A 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-measure(1) will be used.
On the command line, when this argument is present, it must
appear the same number of times as the --pcr-private-key=
option.
Added in version 253.
Example 1. Minimal 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.
Example 2. 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://uapi-group.org/specifications/specs/unified_kernel_image/' \
--pcr-private-key=tpm2-pcr-private-key-initrd.pem \
--pcr-public-key=tpm2-pcr-public-key-initrd.pem \
--phases='enter-initrd' \
--pcr-private-key=tpm2-pcr-private-key-system.pem \
--pcr-public-key=tpm2-pcr-public-key-system.pem \
--phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
enter-initrd:leave-initrd:sysinit:ready' \
--pcr-banks=sha384,sha512 \
--secureboot-private-key=secureboot-private-key.pem \
--secureboot-certificate=secureboot-certificate.pem \
--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 tpm2-pcr-private-key-initrd.pem, and for the
main system (phases leave-initrd, sysinit, ready) with the key
tpm2-pcr-private-key-system.pem. The Linux binary and the
resulting combined image will be signed with the SecureBoot key
secureboot-private-key.pem.
Example 3. All the bells and whistles, via a config file
This 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=secureboot-private-key.pem
SecureBootCertificate=secureboot-certificate.pem
SignKernel=yes
PCRBanks=sha384,sha512
[PCRSignature:initrd]
PCRPrivateKey=tpm2-pcr-private-key-initrd.pem
PCRPublicKey=tpm2-pcr-public-key-initrd.pem
Phases=enter-initrd
[PCRSignature:system]
PCRPrivateKey=tpm2-pcr-private-key-system.pem
PCRPublicKey=tpm2-pcr-public-key-system.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.
Example 4. Kernel command line PE addon
ukify build \
--secureboot-private-key=secureboot-private-key.pem \
--secureboot-certificate=secureboot-certificate.pem \
--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.addon.efi
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.
Example 5. Decide signing policy, and create certificate and keys
First, let's create a configuration file that specifies what
signatures shall be made:
# cat >/etc/kernel/uki.conf <<EOF
[UKI]
SecureBootPrivateKey=/etc/kernel/secureboot-private-key.pem
SecureBootCertificate=/etc/kernel/secureboot-certificate.pem
[PCRSignature:initrd]
Phases=enter-initrd
PCRPrivateKey=/etc/systemd/tpm2-pcr-private-key-initrd.pem
PCRPublicKey=/etc/systemd/tpm2-pcr-public-key-initrd.pem
[PCRSignature:system]
Phases=enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit
enter-initrd:leave-initrd:sysinit:ready
PCRPrivateKey=/etc/systemd/tpm2-pcr-private-key-system.pem
PCRPublicKey=/etc/systemd/tpm2-pcr-public-key-system.pem
EOF
Next, we can generate the certificate and keys:
# ukify genkey --config=/etc/kernel/uki.conf
Writing SecureBoot private key to /etc/kernel/secureboot-private-key.pem
Writing SecureBoot certificate to /etc/kernel/secureboot-certificate.pem
Writing private key for PCR signing to /etc/systemd/tpm2-pcr-private-key-initrd.pem
Writing public key for PCR signing to /etc/systemd/tpm2-pcr-public-key-initrd.pem
Writing private key for PCR signing to /etc/systemd/tpm2-pcr-private-key-system.pem
Writing public key for PCR signing to /etc/systemd/tpm2-pcr-public-key-system.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-install(8) 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.
Example 6. Multi-Profile UKI
First, create a few profiles:
$ ukify build \
--profile='TITLE=Base' \
--output=profile0.efi
Add a second profile (@1):
$ ukify build \
--profile='TITLE=Boot into Storage Target Mode
ID=storagetm' \
--cmdline='quiet rw rd.systemd.unit=stroage-target-mode.target' \
--output=profile1.efi
Add a third profile (@2):
$ ukify build \
--profile='TITLE=Factory Reset
ID=factory-reset' \
--cmdline='quiet rw systemd.unit=factory-reset.target' \
--output=profile2.efi
Then, create a UKI and include all the generated profiles:
$ 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' \
--join-profile=profile0.efi \
--join-profile=profile1.efi \
--join-profile=profile2.efi \
--output=base.efi
The resulting UKI base-with-profile-0-1-2.efi will now contain
three profiles.
systemd(1), systemd-stub(7), systemd-boot(7), systemd-measure(1),
systemd-pcrphase.service(8)
1. Unified Kernel Image (UKI)
https://uapi-group.org/specifications/specs/unified_kernel_image/
2. Shim documentation
https://github.com/rhboot/shim/blob/main/SBAT.md
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2025-02-02. (At that
time, the date of the most recent commit that was found in the
repository was 2025-02-02.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
systemd 258~devel UKIFY(1)
Pages that refer to this page: systemd-measure(1), systemd.directives(7), systemd.index(7), systemd-stub(7), kernel-install(8)
|
HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|