]>
Commit | Line | Data |
---|---|---|
0fdf4e18 ZJS |
1 | <?xml version="1.0"?> |
2 | <!--*-nxml-*--> | |
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 --> | |
9c45bfb2 | 6 | <refentry id="ukify" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='ENABLE_UKIFY'> |
0fdf4e18 ZJS |
7 | |
8 | <refentryinfo> | |
9 | <title>ukify</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>ukify</refentrytitle> | |
15 | <manvolnum>1</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>ukify</refname> | |
00e5933f | 20 | <refpurpose>Combine components into a signed Unified Kernel Image for UEFI systems</refpurpose> |
0fdf4e18 ZJS |
21 | </refnamediv> |
22 | ||
23 | <refsynopsisdiv> | |
24 | <cmdsynopsis> | |
25 | <command>/usr/lib/systemd/ukify</command> | |
00e5933f LB |
26 | <arg choice="opt"><replaceable>LINUX</replaceable></arg> |
27 | <arg choice="opt" rep="repeat"><replaceable>INITRD</replaceable></arg> | |
0fdf4e18 ZJS |
28 | <arg choice="opt" rep="repeat">OPTIONS</arg> |
29 | </cmdsynopsis> | |
30 | </refsynopsisdiv> | |
31 | ||
32 | <refsect1> | |
33 | <title>Description</title> | |
34 | ||
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> | |
37 | ||
00e5933f LB |
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 | |
0fdf4e18 ZJS |
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> | |
44 | ||
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> | |
54 | below.</para> | |
55 | ||
00e5933f LB |
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> | |
58 | ||
0fdf4e18 ZJS |
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> | |
64 | ||
65 | <para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with | |
048bcb9d | 66 | the <option>--phases=</option> option. If not specified, the default provided by |
0fdf4e18 ZJS |
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> | |
73 | ||
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>. | |
78 | </para> | |
79 | </refsect1> | |
80 | ||
81 | <refsect1> | |
82 | <title>Options</title> | |
83 | ||
00e5933f LB |
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> | |
0fdf4e18 ZJS |
87 | |
88 | <para>The following options are understood:</para> | |
89 | ||
90 | <variablelist> | |
91 | <varlistentry> | |
92 | <term><option>--cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
93 | ||
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> | |
97 | </varlistentry> | |
98 | ||
99 | <varlistentry> | |
100 | <term><option>--os-release=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
101 | ||
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> | |
106 | </varlistentry> | |
107 | ||
108 | <varlistentry> | |
109 | <term><option>--devicetree=<replaceable>PATH</replaceable></option></term> | |
110 | ||
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> | |
114 | </varlistentry> | |
115 | ||
116 | <varlistentry> | |
117 | <term><option>--splash=<replaceable>PATH</replaceable></option></term> | |
118 | ||
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. | |
121 | </para></listitem> | |
122 | </varlistentry> | |
123 | ||
124 | <varlistentry> | |
125 | <term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term> | |
126 | ||
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> | |
130 | </varlistentry> | |
131 | ||
132 | <varlistentry> | |
133 | <term><option>--uname=<replaceable>VERSION</replaceable></option></term> | |
134 | ||
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> | |
140 | </varlistentry> | |
141 | ||
142 | <varlistentry> | |
143 | <term><option>--section=<replaceable>NAME</replaceable>:<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
144 | ||
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> | |
151 | </varlistentry> | |
152 | ||
153 | <varlistentry> | |
154 | <term><option>--pcr-private-key=<replaceable>PATH</replaceable></option></term> | |
155 | ||
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> | |
158 | </varlistentry> | |
159 | ||
160 | <varlistentry> | |
161 | <term><option>--pcr-public-key=<replaceable>PATH</replaceable></option></term> | |
162 | ||
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> | |
167 | </varlistentry> | |
168 | ||
169 | <varlistentry> | |
170 | <term><option>--phases=<replaceable>LIST</replaceable></option></term> | |
171 | ||
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> | |
178 | </varlistentry> | |
179 | ||
180 | <varlistentry> | |
181 | <term><option>--pcr-banks=<replaceable>PATH</replaceable></option></term> | |
182 | ||
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> | |
187 | </varlistentry> | |
188 | ||
189 | <varlistentry> | |
190 | <term><option>--secureboot-private-key=<replaceable>SB_KEY</replaceable></option></term> | |
191 | ||
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> | |
195 | </varlistentry> | |
196 | ||
197 | <varlistentry> | |
198 | <term><option>--secureboot-certificate=<replaceable>SB_CERT</replaceable></option></term> | |
199 | ||
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> | |
203 | </varlistentry> | |
204 | ||
205 | <varlistentry> | |
206 | <term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term> | |
207 | ||
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 | |
f37f0f35 | 210 | <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>. |
0fdf4e18 ZJS |
211 | </para></listitem> |
212 | </varlistentry> | |
213 | ||
214 | <varlistentry> | |
215 | <term><option>--sign-kernel</option></term> | |
216 | <term><option>--no-sign-kernel</option></term> | |
217 | ||
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> | |
223 | </varlistentry> | |
224 | ||
225 | <varlistentry> | |
22ad038a | 226 | <term><option>--tools=<replaceable>DIRS</replaceable></option></term> |
0fdf4e18 | 227 | |
22ad038a DDM |
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> | |
0fdf4e18 ZJS |
231 | </varlistentry> |
232 | ||
233 | <varlistentry> | |
234 | <term><option>--measure</option></term> | |
235 | <term><option>--no-measure</option></term> | |
236 | ||
2208d966 | 237 | <listitem><para>Enable or disable a call to <command>systemd-measure</command> to print |
0fdf4e18 ZJS |
238 | pre-calculated PCR values. Defaults to false.</para></listitem> |
239 | </varlistentry> | |
240 | ||
241 | <varlistentry> | |
242 | <term><option>--output=<replaceable>FILENAME</replaceable></option></term> | |
243 | ||
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> | |
248 | </varlistentry> | |
249 | ||
250 | <xi:include href="standard-options.xml" xpointer="help" /> | |
251 | <xi:include href="standard-options.xml" xpointer="version" /> | |
252 | </variablelist> | |
253 | </refsect1> | |
254 | ||
255 | <refsect1> | |
256 | <title>Examples</title> | |
257 | ||
258 | <example> | |
259 | <title>Minimal invocation</title> | |
260 | ||
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 \ | |
264 | --cmdline='quiet rw' | |
265 | </programlisting> | |
266 | ||
267 | <para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para> | |
268 | </example> | |
269 | ||
270 | <example> | |
271 | <title>All the bells and whistles</title> | |
272 | ||
273 | <programlisting>/usr/lib/systemd/ukify \ | |
274 | /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ | |
54c84c8a | 275 | early_cpio \ |
0fdf4e18 ZJS |
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 \ | |
287 | --sign-kernel \ | |
288 | --cmdline='quiet rw rhgb' | |
289 | </programlisting> | |
290 | ||
291 | <para>This creates a signed UKI <filename index='false'>./vmlinuz.signed.efi</filename>. | |
54c84c8a ZJS |
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>. | |
0fdf4e18 ZJS |
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> | |
300 | </example> | |
00e5933f LB |
301 | |
302 | <example> | |
303 | <title>Kernel command line auxiliary PE</title> | |
304 | ||
305 | <programlisting>ukify \ | |
306 | --secureboot-private-key=sb.key \ | |
307 | --secureboot-certificate=sb.cert \ | |
308 | --cmdline='debug' \ | |
309 | --output=debug.cmdline.efi | |
310 | </programlisting> | |
311 | ||
312 | <para>This creates a signed PE binary that contains an additional kernel command line parameter.</para> | |
313 | </example> | |
0fdf4e18 ZJS |
314 | </refsect1> |
315 | ||
316 | <refsect1> | |
317 | <title>See Also</title> | |
318 | <para> | |
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>, | |
9e60dc0d | 322 | <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
0fdf4e18 ZJS |
323 | </para> |
324 | </refsect1> | |
325 | ||
326 | </refentry> |