]>
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> | |
20 | <refpurpose>Combine kernel and initrd into a signed Unified Kernel Image</refpurpose> | |
21 | </refnamediv> | |
22 | ||
23 | <refsynopsisdiv> | |
24 | <cmdsynopsis> | |
25 | <command>/usr/lib/systemd/ukify</command> | |
26 | <arg choice="plain"><replaceable>LINUX</replaceable></arg> | |
54c84c8a | 27 | <arg choice="plain" 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 | ||
38 | <para><command>ukify</command> is a tool that combines 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> | |
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 | ||
56 | <para>If PCR signing keys are provided via the <option>--pcr-public-key=</option> and | |
57 | <option>--pcr-private-key=</option> options, PCR values that will be seen after booting with the given | |
58 | kernel, initrd, and other sections, will be calculated, signed, and embedded in the UKI. | |
59 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> is | |
60 | used to perform this calculation and signing.</para> | |
61 | ||
62 | <para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with | |
63 | <option>--phases=</option> option. If not specified, the default provided by | |
64 | <command>systemd-measure</command> is used. It is also possible to specify the | |
65 | <option>--pcr-private-key=</option>, <option>--pcr-public-key=</option>, and <option>--phases=</option> | |
66 | arguments more than once. Signatures will be then performed with each of the specified keys. When both | |
67 | <option>--phases=</option> and <option>--pcr-private-key=</option> are used, they must be specified the | |
68 | same number of times, and then the n-th boot phase path set will be signed by the n-th key. This can be | |
69 | used to build different trust policies for different phases of the boot.</para> | |
70 | ||
71 | <para>If a SecureBoot signing key is provided via the <option>--secureboot-private-key=</option> option, | |
72 | the resulting PE binary will be signed as a whole, allowing the resulting UKI to be trusted by | |
73 | SecureBoot. Also see the discussion of automatic enrollment in | |
74 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>. | |
75 | </para> | |
76 | </refsect1> | |
77 | ||
78 | <refsect1> | |
79 | <title>Options</title> | |
80 | ||
54c84c8a ZJS |
81 | <para>Note that the <replaceable>LINUX</replaceable> positional argument is mandatory. The |
82 | <replaceable>INITRD</replaceable> positional arguments are optional. If more than one is specified, they | |
83 | will all be combined into a single PE section. This is useful to for example prepend microcode before the | |
84 | actual initrd.</para> | |
0fdf4e18 ZJS |
85 | |
86 | <para>The following options are understood:</para> | |
87 | ||
88 | <variablelist> | |
89 | <varlistentry> | |
90 | <term><option>--cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
91 | ||
92 | <listitem><para>Specify the kernel command line (the <literal>.cmdline</literal> section). The | |
93 | argument may be a literal string, or <literal>@</literal> followed by a path name. If not specified, | |
94 | no command line will be embedded.</para></listitem> | |
95 | </varlistentry> | |
96 | ||
97 | <varlistentry> | |
98 | <term><option>--os-release=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
99 | ||
100 | <listitem><para>Specify the os-release description (the <literal>.osrel</literal> section). The | |
101 | argument may be a literal string, or <literal>@</literal> followed by a path name. If not specified, | |
102 | the <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
103 | file will be picked up from the host system.</para></listitem> | |
104 | </varlistentry> | |
105 | ||
106 | <varlistentry> | |
107 | <term><option>--devicetree=<replaceable>PATH</replaceable></option></term> | |
108 | ||
109 | <listitem><para>Specify the devicetree description (the <literal>.dtb</literal> section). The | |
110 | argument is a path to a compiled binary DeviceTree file. If not specified, the section will not be | |
111 | present.</para></listitem> | |
112 | </varlistentry> | |
113 | ||
114 | <varlistentry> | |
115 | <term><option>--splash=<replaceable>PATH</replaceable></option></term> | |
116 | ||
117 | <listitem><para>Specify a picture to display during boot (the <literal>.splash</literal> section). | |
118 | The argument is a path to a BMP file. If not specified, the section will not be present. | |
119 | </para></listitem> | |
120 | </varlistentry> | |
121 | ||
122 | <varlistentry> | |
123 | <term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term> | |
124 | ||
125 | <listitem><para>Specify a path to a public key to embed in the <literal>.pcrpkey</literal> section. | |
126 | If not specified, and there's exactly one <option>--pcr-public-key=</option> argument, that key will | |
127 | be used. Otherwise, the section will not be present.</para></listitem> | |
128 | </varlistentry> | |
129 | ||
130 | <varlistentry> | |
131 | <term><option>--uname=<replaceable>VERSION</replaceable></option></term> | |
132 | ||
133 | <listitem><para>Specify the kernel version (as in <command>uname -r</command>, the | |
134 | <literal>.uname</literal> section). If not specified, an attempt will be made to extract the version | |
135 | string from the kernel image. It is recommended to pass this explicitly if known, because the | |
136 | extraction is based on heuristics and not very reliable. If not specified and extraction fails, the | |
137 | section will not be present.</para></listitem> | |
138 | </varlistentry> | |
139 | ||
140 | <varlistentry> | |
141 | <term><option>--section=<replaceable>NAME</replaceable>:<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term> | |
142 | ||
143 | <listitem><para>Specify an arbitrary additional section | |
144 | <literal><replaceable>NAME</replaceable></literal>. Note that the name is used as-is, and if the | |
145 | section name should start with a dot, it must be included in <replaceable>NAME</replaceable>. The | |
146 | argument may be a literal string, or <literal>@</literal> followed by a path name. This option may be | |
147 | specified more than once. Any sections specified in this fashion will be inserted (in order) before | |
148 | the <literal>.linux</literal> section which is always last.</para></listitem> | |
149 | </varlistentry> | |
150 | ||
151 | <varlistentry> | |
152 | <term><option>--pcr-private-key=<replaceable>PATH</replaceable></option></term> | |
153 | ||
154 | <listitem><para>Specify a private key to use for signing PCR policies. This option may be specified | |
155 | more than once, in which case multiple signatures will be made.</para></listitem> | |
156 | </varlistentry> | |
157 | ||
158 | <varlistentry> | |
159 | <term><option>--pcr-public-key=<replaceable>PATH</replaceable></option></term> | |
160 | ||
161 | <listitem><para>Specify a public key to use for signing PCR policies. This option may be specified | |
162 | more than once, similarly to the <option>--pcr-private-key=</option> option. If not present, the | |
163 | public keys will be extracted from the private keys. If present, the this option must be specified | |
164 | the same number of times as the <option>--pcr-private-key=</option> option.</para></listitem> | |
165 | </varlistentry> | |
166 | ||
167 | <varlistentry> | |
168 | <term><option>--phases=<replaceable>LIST</replaceable></option></term> | |
169 | ||
170 | <listitem><para>A comma or space-separated list of colon-separated phase paths to sign a policy for. | |
171 | If not present, the default of | |
172 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
173 | will be used. When this argument is present, it must appear the same number of times as the | |
174 | <option>--pcr-private-key=</option> option. Each set of boot phase paths will be signed with the | |
175 | corresponding private key.</para></listitem> | |
176 | </varlistentry> | |
177 | ||
178 | <varlistentry> | |
179 | <term><option>--pcr-banks=<replaceable>PATH</replaceable></option></term> | |
180 | ||
181 | <listitem><para>A comma or space-separated list of PCR banks to sign a policy for. If not present, | |
182 | all known banks will be used (<literal>sha1</literal>, <literal>sha256</literal>, | |
183 | <literal>sha384</literal>, <literal>sha512</literal>), which will fail if not supported by the | |
184 | system.</para></listitem> | |
185 | </varlistentry> | |
186 | ||
187 | <varlistentry> | |
188 | <term><option>--secureboot-private-key=<replaceable>SB_KEY</replaceable></option></term> | |
189 | ||
190 | <listitem><para>A path to a private key to use for signing of the resulting binary. If the | |
191 | <option>--signing-engine=</option> option is used, this may also be an engine-specific | |
192 | designation.</para></listitem> | |
193 | </varlistentry> | |
194 | ||
195 | <varlistentry> | |
196 | <term><option>--secureboot-certificate=<replaceable>SB_CERT</replaceable></option></term> | |
197 | ||
198 | <listitem><para>A path to a certificate to use for signing of the resulting binary. If the | |
199 | <option>--signing-engine=</option> option is used, this may also be an engine-specific | |
200 | designation.</para></listitem> | |
201 | </varlistentry> | |
202 | ||
203 | <varlistentry> | |
204 | <term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term> | |
205 | ||
206 | <listitem><para>An "engine" to for signing of the resulting binary. This option is currently passed | |
207 | verbatim to the <option>--engine=</option> option of | |
f37f0f35 | 208 | <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>. |
0fdf4e18 ZJS |
209 | </para></listitem> |
210 | </varlistentry> | |
211 | ||
212 | <varlistentry> | |
213 | <term><option>--sign-kernel</option></term> | |
214 | <term><option>--no-sign-kernel</option></term> | |
215 | ||
216 | <listitem><para>Override the detection of whether to sign the Linux binary itself before it is | |
217 | embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is | |
218 | provided via the <option>--secureboot-private-key=</option> option and the binary has not already | |
219 | been signed. If <option>--sign-kernel</option> is specified, and the binary has already been signed, | |
220 | the signature will be appended anyway.</para></listitem> | |
221 | </varlistentry> | |
222 | ||
223 | <varlistentry> | |
22ad038a | 224 | <term><option>--tools=<replaceable>DIRS</replaceable></option></term> |
0fdf4e18 | 225 | |
22ad038a DDM |
226 | <listitem><para>Specify one or more directories with helper tools. <command>ukify</command> will look |
227 | for helper tools in those directories first, and if not found, try to load them from | |
228 | <varname>$PATH</varname> in the usual fashion.</para></listitem> | |
0fdf4e18 ZJS |
229 | </varlistentry> |
230 | ||
231 | <varlistentry> | |
232 | <term><option>--measure</option></term> | |
233 | <term><option>--no-measure</option></term> | |
234 | ||
2208d966 | 235 | <listitem><para>Enable or disable a call to <command>systemd-measure</command> to print |
0fdf4e18 ZJS |
236 | pre-calculated PCR values. Defaults to false.</para></listitem> |
237 | </varlistentry> | |
238 | ||
239 | <varlistentry> | |
240 | <term><option>--output=<replaceable>FILENAME</replaceable></option></term> | |
241 | ||
242 | <listitem><para>The output filename. If not specified, the name of the | |
243 | <replaceable>LINUX</replaceable> argument, with the suffix <literal>.unsigned.efi</literal> or | |
244 | <literal>.signed.efi</literal> will be used, depending on whether signing for SecureBoot was | |
245 | performed.</para></listitem> | |
246 | </varlistentry> | |
247 | ||
248 | <xi:include href="standard-options.xml" xpointer="help" /> | |
249 | <xi:include href="standard-options.xml" xpointer="version" /> | |
250 | </variablelist> | |
251 | </refsect1> | |
252 | ||
253 | <refsect1> | |
254 | <title>Examples</title> | |
255 | ||
256 | <example> | |
257 | <title>Minimal invocation</title> | |
258 | ||
259 | <programlisting>ukify \ | |
260 | /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ | |
261 | /some/path/initramfs-6.0.9-300.fc37.x86_64.img \ | |
262 | --cmdline='quiet rw' | |
263 | </programlisting> | |
264 | ||
265 | <para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para> | |
266 | </example> | |
267 | ||
268 | <example> | |
269 | <title>All the bells and whistles</title> | |
270 | ||
271 | <programlisting>/usr/lib/systemd/ukify \ | |
272 | /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ | |
54c84c8a | 273 | early_cpio \ |
0fdf4e18 ZJS |
274 | /some/path/initramfs-6.0.9-300.fc37.x86_64.img \ |
275 | --pcr-private-key=pcr-private-initrd-key.pem \ | |
276 | --pcr-public-key=pcr-public-initrd-key.pem \ | |
277 | --phases='enter-initrd' \ | |
278 | --pcr-private-key=pcr-private-system-key.pem \ | |
279 | --pcr-public-key=pcr-public-system-key.pem \ | |
280 | --phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \ | |
281 | enter-initrd:leave-initrd:sysinit:ready' \ | |
282 | --pcr-banks=sha384,sha512 \ | |
283 | --secureboot-private-key=sb.key \ | |
284 | --secureboot-certificate=sb.cert \ | |
285 | --sign-kernel \ | |
286 | --cmdline='quiet rw rhgb' | |
287 | </programlisting> | |
288 | ||
289 | <para>This creates a signed UKI <filename index='false'>./vmlinuz.signed.efi</filename>. | |
54c84c8a ZJS |
290 | The initrd section contains two concatenated parts, <filename index='false'>early_cpio</filename> |
291 | and <filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>. | |
0fdf4e18 ZJS |
292 | The policy embedded in the <literal>.pcrsig</literal> section will be signed for the initrd (the |
293 | <constant>enter-initrd</constant> phase) with the key | |
294 | <filename index='false'>pcr-private-initrd-key.pem</filename>, and for the main system (phases | |
295 | <constant>leave-initrd</constant>, <constant>sysinit</constant>, <constant>ready</constant>) with the | |
296 | key <filename index='false'>pcr-private-system-key.pem</filename>. The Linux binary and the resulting | |
297 | combined image will be signed with the SecureBoot key <filename index='false'>sb.key</filename>.</para> | |
298 | </example> | |
299 | </refsect1> | |
300 | ||
301 | <refsect1> | |
302 | <title>See Also</title> | |
303 | <para> | |
304 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
305 | <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
306 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
9e60dc0d | 307 | <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
0fdf4e18 ZJS |
308 | </para> |
309 | </refsect1> | |
310 | ||
311 | </refentry> |