systemd ukify 1 ukify Combine components into a signed Unified Kernel Image for UEFI systems /usr/lib/systemd/ukify LINUX INITRD OPTIONS Note: 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 components (e.g.: 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 Cmdline=/--cmdline=, OSRelease=/--os-release=, DeviceTree=/--devicetree=, Splash=/--splash=, PCRPKey=/--pcrpkey=, Uname=/--uname=, 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-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=/--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 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-boot7. 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. 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: --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 commandline option does not fully override the config file setting are explicitly mentioned in the descriptions of individual options. --measure --no-measure Enable or disable a call to systemd-measure to print pre-calculated PCR values. Defaults to false. --section=NAME:TEXT|@PATH 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. --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. --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. --summary Print a summary of loaded config and exit. This is useful to check how the options form the configuration file and the commandline are combined. Linux=LINUX positional argument LINUX A path to the kernel binary. Initrd=INITRD... positional argument 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|@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. 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-release5 file will be picked up from the host system. 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. 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. 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. 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. 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. SecureBootSigningTool=SIGNER --signtool=SIGNER Whether to use sbsign or pesign. Depending on this choice, different parameters are required in order to sign an image. Defaults to sbsign. 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= option is used, this may also be an engine-specific designation. This option is required by SecureBootSigningTool=sbsign/--signtool=sbsign. 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= option is used, this may also be an engine-specific designation. This option is required by SecureBootSigningTool=sbsign/--signtool=sbsign. 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. 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. SigningEngine=ENGINE --signing-engine=ENGINE An "engine" to for signing of the resulting binary. This option is currently passed verbatim to the --engine= option of sbsign1. 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. In the config file, those options are grouped by section. On the commandline, 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 commandline, this option may be specified more than once, in which case multiple signatures will be made. PCRPublicKey=PATH --pcr-public-key=PATH A public key to use for signing PCR policies. On the commandline, 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 commandline, if present, the this option must be specified the same number of times as the --pcr-private-key= option. 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-measure1 will be used. On the commandline, when this argument is present, it must appear the same number of times as the --pcr-private-key= option. $ ukify \ /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. # /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. 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=sb.key SecureBootCerificate=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 # /usr/lib/systemd/ukify -c ukify.conf \ /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ /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 commandline. 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. ukify \ --secureboot-private-key=sb.key \ --secureboot-certificate=sb.cert \ --cmdline='debug' \ --output=debug.cmdline This creates a signed PE binary that contains the additional kernel command line parameter debug. systemd1, systemd-stub7, systemd-boot7, systemd-measure1, systemd-pcrphase.service8