1UKIFY(1) ukify UKIFY(1)
2
6 ukify - Combine kernel and initrd into a signed Unified Kernel Image
7
9 /usr/lib/systemd/ukify LINUX INITRD... [OPTIONS...]
10
12 Note: this command is experimental for now. While it is intended to
13 become a regular component of systemd, it might still change in
14 behaviour and interface.
15 ukify is a tool that combines a kernel and an initrd with a UEFI boot
17 stub to create a Unified Kernel Image (UKI)[1] — a PE binary that can
18 be executed by the firmware to start the embedded linux kernel. See
19 systemd-stub(7) for details about the stub.
20 Additional sections will be inserted into the UKI, either automatically
22 or only if a specific option is provided. See the discussions of
23 --cmdline=, --os-release=, --devicetree=, --splash=, --pcrpkey=,
24 --uname=, and --section= below.
25 If PCR signing keys are provided via the --pcr-public-key= and
27 --pcr-private-key= options, PCR values that will be seen after booting
28 with the given kernel, initrd, and other sections, will be calculated,
29 signed, and embedded in the UKI. systemd-measure(1) is used to perform
30 this calculation and signing.
31 The calculation of PCR values is done for specific boot phase paths.
33 Those can be specified with --phases= option. If not specified, the
34 default provided by systemd-measure is used. It is also possible to
35 specify the --pcr-private-key=, --pcr-public-key=, and --phases=
36 arguments more than once. Signatures will be then performed with each
37 of the specified keys. When both --phases= and --pcr-private-key= are
38 used, they must be specified the same number of times, and then the
39 n-th boot phase path set will be signed by the n-th key. This can be
40 used to build different trust policies for different phases of the
41 boot.
42 If a SecureBoot signing key is provided via the
44 --secureboot-private-key= option, the resulting PE binary will be
45 signed as a whole, allowing the resulting UKI to be trusted by
46 SecureBoot. Also see the discussion of automatic enrollment in systemd-
47 boot(7).
48
50 Note that the LINUX positional argument is mandatory. The INITRD
51 positional arguments are optional. If more than one is specified, they
52 will all be combined into a single PE section. This is useful to for
53 example prepend microcode before the actual initrd.
54 The following options are understood:
56 --cmdline=TEXT|@PATH
58 Specify the kernel command line (the ".cmdline" section). The
59 argument may be a literal string, or "@" followed by a path name.
60 If not specified, no command line will be embedded.
61 --os-release=TEXT|@PATH
63 Specify the os-release description (the ".osrel" section). The
64 argument may be a literal string, or "@" followed by a path name.
65 If not specified, the os-release(5) file will be picked up from the
66 host system.
67 --devicetree=PATH
69 Specify the devicetree description (the ".dtb" section). The
70 argument is a path to a compiled binary DeviceTree file. If not
71 specified, the section will not be present.
72 --splash=PATH
74 Specify a picture to display during boot (the ".splash" section).
75 The argument is a path to a BMP file. If not specified, the section
76 will not be present.
77 --pcrpkey=PATH
79 Specify a path to a public key to embed in the ".pcrpkey" section.
80 If not specified, and there's exactly one --pcr-public-key=
81 argument, that key will be used. Otherwise, the section will not be
82 present.
83 --uname=VERSION
85 Specify the kernel version (as in uname -r, the ".uname" section).
86 If not specified, an attempt will be made to extract the version
87 string from the kernel image. It is recommended to pass this
88 explicitly if known, because the extraction is based on heuristics
89 and not very reliable. If not specified and extraction fails, the
90 section will not be present.
91 --section=NAME:TEXT|@PATH
93 Specify an arbitrary additional section "NAME". Note that the name
94 is used as-is, and if the section name should start with a dot, it
95 must be included in NAME. The argument may be a literal string, or
96 "@" followed by a path name. This option may be specified more than
97 once. Any sections specified in this fashion will be inserted (in
98 order) before the ".linux" section which is always last.
99 --pcr-private-key=PATH
101 Specify a private key to use for signing PCR policies. This option
102 may be specified more than once, in which case multiple signatures
103 will be made.
104 --pcr-public-key=PATH
106 Specify a public key to use for signing PCR policies. This option
107 may be specified more than once, similarly to the
108 --pcr-private-key= option. If not present, the public keys will be
109 extracted from the private keys. If present, the this option must
110 be specified the same number of times as the --pcr-private-key=
111 option.
112 --phases=LIST
114 A comma or space-separated list of colon-separated phase paths to
115 sign a policy for. If not present, the default of systemd-
116 measure(1) will be used. When this argument is present, it must
117 appear the same number of times as the --pcr-private-key= option.
118 Each set of boot phase paths will be signed with the corresponding
119 private key.
120 --pcr-banks=PATH
122 A comma or space-separated list of PCR banks to sign a policy for.
123 If not present, all known banks will be used ("sha1", "sha256",
124 "sha384", "sha512"), which will fail if not supported by the
125 system.
126 --secureboot-private-key=SB_KEY
128 A path to a private key to use for signing of the resulting binary.
129 If the --signing-engine= option is used, this may also be an
130 engine-specific designation.
131 --secureboot-certificate=SB_CERT
133 A path to a certificate to use for signing of the resulting binary.
134 If the --signing-engine= option is used, this may also be an
135 engine-specific designation.
136 --signing-engine=ENGINE
138 An "engine" to for signing of the resulting binary. This option is
139 currently passed verbatim to the --engine= option of sbsign(1).
140 --sign-kernel, --no-sign-kernel
142 Override the detection of whether to sign the Linux binary itself
143 before it is embedded in the combined image. If not specified, it
144 will be signed if a SecureBoot signing key is provided via the
145 --secureboot-private-key= option and the binary has not already
146 been signed. If --sign-kernel is specified, and the binary has
147 already been signed, the signature will be appended anyway.
148 --tools=DIRS
150 Specify one or more directories with helper tools. ukify will look
151 for helper tools in those directories first, and if not found, try
152 to load them from $PATH in the usual fashion.
153 --measure, --no-measure
155 Enable or disable a call to systemd-measure to print pre-calculated
156 PCR values. Defaults to false.
157 --output=FILENAME
159 The output filename. If not specified, the name of the LINUX
160 argument, with the suffix ".unsigned.efi" or ".signed.efi" will be
161 used, depending on whether signing for SecureBoot was performed.
162 -h, --help
164 Print a short help text and exit.
165 --version
167 Print a short version string and exit.
168
170 Example 1. Minimal invocation
171 ukify \
173 /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
174 /some/path/initramfs-6.0.9-300.fc37.x86_64.img \
175 --cmdline='quiet rw'
176 This creates an unsigned UKI ./vmlinuz.unsigned.efi.
179 Example 2. All the bells and whistles
181 /usr/lib/systemd/ukify \
183 /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
184 early_cpio \
185 /some/path/initramfs-6.0.9-300.fc37.x86_64.img \
186 --pcr-private-key=pcr-private-initrd-key.pem \
187 --pcr-public-key=pcr-public-initrd-key.pem \
188 --phases='enter-initrd' \
189 --pcr-private-key=pcr-private-system-key.pem \
190 --pcr-public-key=pcr-public-system-key.pem \
191 --phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
192 enter-initrd:leave-initrd:sysinit:ready' \
193 --pcr-banks=sha384,sha512 \
194 --secureboot-private-key=sb.key \
195 --secureboot-certificate=sb.cert \
196 --sign-kernel \
197 --cmdline='quiet rw rhgb'
198 This creates a signed UKI ./vmlinuz.signed.efi. The initrd section
201 contains two concatenated parts, early_cpio and
202 initramfs-6.0.9-300.fc37.x86_64.img. The policy embedded in the
203 ".pcrsig" section will be signed for the initrd (the enter-initrd
204 phase) with the key pcr-private-initrd-key.pem, and for the main system
205 (phases leave-initrd, sysinit, ready) with the key
206 pcr-private-system-key.pem. The Linux binary and the resulting combined
207 image will be signed with the SecureBoot key sb.key.
208
210 systemd(1), systemd-stub(7), systemd-boot(7), objcopy(1), systemd-
211 pcrphase.service(8)
212
214 1. Unified Kernel Image (UKI)
215 https://uapi-group.org/specifications/specs/unified_kernel_image/
216systemd 253 UKIFY(1)