3 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
4 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"ukify" xmlns:
xi=
"http://www.w3.org/2001/XInclude" conditional='ENABLE_UKIFY'
>
10 <productname>systemd
</productname>
14 <refentrytitle>ukify
</refentrytitle>
15 <manvolnum>1</manvolnum>
19 <refname>ukify
</refname>
20 <refpurpose>Combine components into a signed Unified Kernel Image for UEFI systems
</refpurpose>
25 <command>/usr/lib/systemd/ukify
</command>
26 <arg choice=
"opt"><replaceable>LINUX
</replaceable></arg>
27 <arg choice=
"opt" rep=
"repeat"><replaceable>INITRD
</replaceable></arg>
28 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
33 <title>Description
</title>
35 <para>Note: this command is experimental for now. While it is intended to become a regular component of
36 systemd, it might still change in behaviour and interface.
</para>
38 <para><command>ukify
</command> is a tool that combines components (e.g.: a kernel and an initrd with
39 a UEFI boot stub) to create a
40 <ulink url=
"https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)
</ulink>
41 — a PE binary that can be executed by the firmware to start the embedded linux kernel.
42 See
<citerefentry><refentrytitle>systemd-stub
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
43 for details about the stub.
</para>
45 <para>Additional sections will be inserted into the UKI, either automatically or only if a specific
46 option is provided. See the discussions of
47 <option>--cmdline=
</option>,
48 <option>--os-release=
</option>,
49 <option>--devicetree=
</option>,
50 <option>--splash=
</option>,
51 <option>--pcrpkey=
</option>,
52 <option>--uname=
</option>,
53 and
<option>--section=
</option>
56 <para><command>ukify
</command> can also be used to assemble a PE binary that is not executable but
57 contains auxiliary data, for example additional kernel command line entries.
</para>
59 <para>If PCR signing keys are provided via the
<option>--pcr-public-key=
</option> and
60 <option>--pcr-private-key=
</option> options, PCR values that will be seen after booting with the given
61 kernel, initrd, and other sections, will be calculated, signed, and embedded in the UKI.
62 <citerefentry><refentrytitle>systemd-measure
</refentrytitle><manvolnum>1</manvolnum></citerefentry> is
63 used to perform this calculation and signing.
</para>
65 <para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with
66 the
<option>--phases=
</option> option. If not specified, the default provided by
67 <command>systemd-measure
</command> is used. It is also possible to specify the
68 <option>--pcr-private-key=
</option>,
<option>--pcr-public-key=
</option>, and
<option>--phases=
</option>
69 arguments more than once. Signatures will be then performed with each of the specified keys. When both
70 <option>--phases=
</option> and
<option>--pcr-private-key=
</option> are used, they must be specified the
71 same number of times, and then the n-th boot phase path set will be signed by the n-th key. This can be
72 used to build different trust policies for different phases of the boot.
</para>
74 <para>If a SecureBoot signing key is provided via the
<option>--secureboot-private-key=
</option> option,
75 the resulting PE binary will be signed as a whole, allowing the resulting UKI to be trusted by
76 SecureBoot. Also see the discussion of automatic enrollment in
77 <citerefentry><refentrytitle>systemd-boot
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
82 <title>Options
</title>
84 <para>The
<replaceable>LINUX
</replaceable> and
<replaceable>INITRD
</replaceable> positional arguments are
85 optional. If more than one
<replaceable>INITRD
</replaceable> are specified, they will all be combined into
86 a single PE section. This is useful to for example prepend microcode before the actual initrd.
</para>
88 <para>The following options are understood:
</para>
92 <term><option>--cmdline=
<replaceable>TEXT
</replaceable>|
<replaceable>@PATH
</replaceable></option></term>
94 <listitem><para>Specify the kernel command line (the
<literal>.cmdline
</literal> section). The
95 argument may be a literal string, or
<literal>@
</literal> followed by a path name. If not specified,
96 no command line will be embedded.
</para></listitem>
100 <term><option>--os-release=
<replaceable>TEXT
</replaceable>|
<replaceable>@PATH
</replaceable></option></term>
102 <listitem><para>Specify the os-release description (the
<literal>.osrel
</literal> section). The
103 argument may be a literal string, or
<literal>@
</literal> followed by a path name. If not specified,
104 the
<citerefentry><refentrytitle>os-release
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
105 file will be picked up from the host system.
</para></listitem>
109 <term><option>--devicetree=
<replaceable>PATH
</replaceable></option></term>
111 <listitem><para>Specify the devicetree description (the
<literal>.dtb
</literal> section). The
112 argument is a path to a compiled binary DeviceTree file. If not specified, the section will not be
113 present.
</para></listitem>
117 <term><option>--splash=
<replaceable>PATH
</replaceable></option></term>
119 <listitem><para>Specify a picture to display during boot (the
<literal>.splash
</literal> section).
120 The argument is a path to a BMP file. If not specified, the section will not be present.
125 <term><option>--pcrpkey=
<replaceable>PATH
</replaceable></option></term>
127 <listitem><para>Specify a path to a public key to embed in the
<literal>.pcrpkey
</literal> section.
128 If not specified, and there's exactly one
<option>--pcr-public-key=
</option> argument, that key will
129 be used. Otherwise, the section will not be present.
</para></listitem>
133 <term><option>--uname=
<replaceable>VERSION
</replaceable></option></term>
135 <listitem><para>Specify the kernel version (as in
<command>uname -r
</command>, the
136 <literal>.uname
</literal> section). If not specified, an attempt will be made to extract the version
137 string from the kernel image. It is recommended to pass this explicitly if known, because the
138 extraction is based on heuristics and not very reliable. If not specified and extraction fails, the
139 section will not be present.
</para></listitem>
143 <term><option>--section=
<replaceable>NAME
</replaceable>:
<replaceable>TEXT
</replaceable>|
<replaceable>@PATH
</replaceable></option></term>
145 <listitem><para>Specify an arbitrary additional section
146 <literal><replaceable>NAME
</replaceable></literal>. Note that the name is used as-is, and if the
147 section name should start with a dot, it must be included in
<replaceable>NAME
</replaceable>. The
148 argument may be a literal string, or
<literal>@
</literal> followed by a path name. This option may be
149 specified more than once. Any sections specified in this fashion will be inserted (in order) before
150 the
<literal>.linux
</literal> section which is always last.
</para></listitem>
154 <term><option>--pcr-private-key=
<replaceable>PATH
</replaceable></option></term>
156 <listitem><para>Specify a private key to use for signing PCR policies. This option may be specified
157 more than once, in which case multiple signatures will be made.
</para></listitem>
161 <term><option>--pcr-public-key=
<replaceable>PATH
</replaceable></option></term>
163 <listitem><para>Specify a public key to use for signing PCR policies. This option may be specified
164 more than once, similarly to the
<option>--pcr-private-key=
</option> option. If not present, the
165 public keys will be extracted from the private keys. If present, the this option must be specified
166 the same number of times as the
<option>--pcr-private-key=
</option> option.
</para></listitem>
170 <term><option>--phases=
<replaceable>LIST
</replaceable></option></term>
172 <listitem><para>A comma or space-separated list of colon-separated phase paths to sign a policy for.
173 If not present, the default of
174 <citerefentry><refentrytitle>systemd-measure
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
175 will be used. When this argument is present, it must appear the same number of times as the
176 <option>--pcr-private-key=
</option> option. Each set of boot phase paths will be signed with the
177 corresponding private key.
</para></listitem>
181 <term><option>--pcr-banks=
<replaceable>PATH
</replaceable></option></term>
183 <listitem><para>A comma or space-separated list of PCR banks to sign a policy for. If not present,
184 all known banks will be used (
<literal>sha1
</literal>,
<literal>sha256
</literal>,
185 <literal>sha384
</literal>,
<literal>sha512
</literal>), which will fail if not supported by the
186 system.
</para></listitem>
190 <term><option>--secureboot-private-key=
<replaceable>SB_KEY
</replaceable></option></term>
192 <listitem><para>A path to a private key to use for signing of the resulting binary. If the
193 <option>--signing-engine=
</option> option is used, this may also be an engine-specific
194 designation.
</para></listitem>
198 <term><option>--secureboot-certificate=
<replaceable>SB_CERT
</replaceable></option></term>
200 <listitem><para>A path to a certificate to use for signing of the resulting binary. If the
201 <option>--signing-engine=
</option> option is used, this may also be an engine-specific
202 designation.
</para></listitem>
206 <term><option>--signing-engine=
<replaceable>ENGINE
</replaceable></option></term>
208 <listitem><para>An
"engine" to for signing of the resulting binary. This option is currently passed
209 verbatim to the
<option>--engine=
</option> option of
210 <citerefentry project='archlinux'
><refentrytitle>sbsign
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
215 <term><option>--sign-kernel
</option></term>
216 <term><option>--no-sign-kernel
</option></term>
218 <listitem><para>Override the detection of whether to sign the Linux binary itself before it is
219 embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is
220 provided via the
<option>--secureboot-private-key=
</option> option and the binary has not already
221 been signed. If
<option>--sign-kernel
</option> is specified, and the binary has already been signed,
222 the signature will be appended anyway.
</para></listitem>
226 <term><option>--tools=
<replaceable>DIRS
</replaceable></option></term>
228 <listitem><para>Specify one or more directories with helper tools.
<command>ukify
</command> will look
229 for helper tools in those directories first, and if not found, try to load them from
230 <varname>$PATH
</varname> in the usual fashion.
</para></listitem>
234 <term><option>--measure
</option></term>
235 <term><option>--no-measure
</option></term>
237 <listitem><para>Enable or disable a call to
<command>systemd-measure
</command> to print
238 pre-calculated PCR values. Defaults to false.
</para></listitem>
242 <term><option>--output=
<replaceable>FILENAME
</replaceable></option></term>
244 <listitem><para>The output filename. If not specified, the name of the
245 <replaceable>LINUX
</replaceable> argument, with the suffix
<literal>.unsigned.efi
</literal> or
246 <literal>.signed.efi
</literal> will be used, depending on whether signing for SecureBoot was
247 performed.
</para></listitem>
250 <xi:include href=
"standard-options.xml" xpointer=
"help" />
251 <xi:include href=
"standard-options.xml" xpointer=
"version" />
256 <title>Examples
</title>
259 <title>Minimal invocation
</title>
261 <programlisting>ukify \
262 /lib/modules/
6.0.9-
300.fc37.x86_64/vmlinuz \
263 /some/path/initramfs-
6.0.9-
300.fc37.x86_64.img \
267 <para>This creates an unsigned UKI
<filename>./vmlinuz.unsigned.efi
</filename>.
</para>
271 <title>All the bells and whistles
</title>
273 <programlisting>/usr/lib/systemd/ukify \
274 /lib/modules/
6.0.9-
300.fc37.x86_64/vmlinuz \
276 /some/path/initramfs-
6.0.9-
300.fc37.x86_64.img \
277 --pcr-private-key=pcr-private-initrd-key.pem \
278 --pcr-public-key=pcr-public-initrd-key.pem \
279 --phases='enter-initrd' \
280 --pcr-private-key=pcr-private-system-key.pem \
281 --pcr-public-key=pcr-public-system-key.pem \
282 --phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
283 enter-initrd:leave-initrd:sysinit:ready' \
284 --pcr-banks=sha384,sha512 \
285 --secureboot-private-key=sb.key \
286 --secureboot-certificate=sb.cert \
288 --cmdline='quiet rw rhgb'
291 <para>This creates a signed UKI
<filename index='false'
>./vmlinuz.signed.efi
</filename>.
292 The initrd section contains two concatenated parts,
<filename index='false'
>early_cpio
</filename>
293 and
<filename index='false'
>initramfs-
6.0.9-
300.fc37.x86_64.img
</filename>.
294 The policy embedded in the
<literal>.pcrsig
</literal> section will be signed for the initrd (the
295 <constant>enter-initrd
</constant> phase) with the key
296 <filename index='false'
>pcr-private-initrd-key.pem
</filename>, and for the main system (phases
297 <constant>leave-initrd
</constant>,
<constant>sysinit
</constant>,
<constant>ready
</constant>) with the
298 key
<filename index='false'
>pcr-private-system-key.pem
</filename>. The Linux binary and the resulting
299 combined image will be signed with the SecureBoot key
<filename index='false'
>sb.key
</filename>.
</para>
303 <title>Kernel command line auxiliary PE
</title>
305 <programlisting>ukify \
306 --secureboot-private-key=sb.key \
307 --secureboot-certificate=sb.cert \
309 --output=debug.cmdline.efi
312 <para>This creates a signed PE binary that contains an additional kernel command line parameter.
</para>
317 <title>See Also
</title>
319 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
320 <citerefentry><refentrytitle>systemd-stub
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
321 <citerefentry><refentrytitle>systemd-boot
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
322 <citerefentry><refentrytitle>systemd-pcrphase.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>