]>
Commit | Line | Data |
---|---|---|
3f9a615d LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
3f9a615d LP |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
5 | ||
dfca5587 | 6 | <refentry id="systemd-stub" conditional='ENABLE_BOOTLOADER' |
3f9a615d LP |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
8 | <refentryinfo> | |
9 | <title>systemd-stub</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>systemd-stub</refentrytitle> | |
15 | <manvolnum>7</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>systemd-stub</refname> | |
838f094c | 20 | <refname>sd-stub</refname> |
3f9a615d LP |
21 | <refname>linuxx64.efi.stub</refname> |
22 | <refname>linuxia32.efi.stub</refname> | |
23 | <refname>linuxaa64.efi.stub</refname> | |
24 | <refpurpose>A simple UEFI kernel boot stub</refpurpose> | |
25 | </refnamediv> | |
26 | ||
27 | <refsynopsisdiv> | |
73e97bb0 ZJS |
28 | <para><simplelist> |
29 | <member><filename>/usr/lib/systemd/boot/efi/linuxx64.efi.stub</filename></member> | |
30 | <member><filename>/usr/lib/systemd/boot/efi/linuxia32.efi.stub</filename></member> | |
31 | <member><filename>/usr/lib/systemd/boot/efi/linuxaa64.efi.stub</filename></member> | |
32 | <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.addon.efi</filename></member> | |
33 | <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.cred</filename></member> | |
34 | <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.raw</filename></member> | |
39e0c237 LP |
35 | <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.sysext.raw</filename></member> |
36 | <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.confext.raw</filename></member> | |
73e97bb0 ZJS |
37 | <member><filename><replaceable>ESP</replaceable>/loader/addons/*.addon.efi</filename></member> |
38 | <member><filename><replaceable>ESP</replaceable>/loader/credentials/*.cred</filename></member> | |
39 | </simplelist></para> | |
3f9a615d LP |
40 | </refsynopsisdiv> |
41 | ||
42 | <refsect1> | |
43 | <title>Description</title> | |
44 | ||
45 | <para><command>systemd-stub</command> (stored in per-architecture files | |
46 | <filename>linuxx64.efi.stub</filename>, <filename>linuxia32.efi.stub</filename>, | |
47 | <filename>linuxaa64.efi.stub</filename> on disk) is a simple UEFI boot stub. An UEFI boot stub is | |
48 | attached to a Linux kernel binary image, and is a piece of code that runs in the UEFI firmware | |
49 | environment before transitioning into the Linux kernel environment. The UEFI boot stub ensures a Linux | |
50 | kernel is executable as regular UEFI binary, and is able to do various preparations before switching the | |
51 | system into the Linux world.</para> | |
52 | ||
53 | <para>The UEFI boot stub looks for various resources for the kernel invocation inside the UEFI PE binary | |
6d856e26 LP |
54 | itself. This allows combining various resources inside a single PE binary image (usually called "Unified |
55 | Kernel Image", or "UKI" for short), which may then be signed via UEFI SecureBoot as a whole, covering all | |
56 | individual resources at once. Specifically it may include:</para> | |
3f9a615d LP |
57 | |
58 | <itemizedlist> | |
ef3e110a LP |
59 | <!-- Let's keep this in the canonical order we also measure the sections by, i.e. as in |
60 | src/fundamental/uki.h's UnifiedSection enum --> | |
61 | ||
963ea30a | 62 | <listitem><para>A <literal>.linux</literal> section with the ELF Linux kernel image.</para></listitem> |
3f9a615d | 63 | |
963ea30a ZJS |
64 | <listitem><para>An <literal>.osrel</literal> section with OS release information, i.e. the contents of |
65 | the <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file | |
66 | of the OS the kernel belongs to.</para></listitem> | |
72c97c19 | 67 | |
963ea30a ZJS |
68 | <listitem><para>A <literal>.cmdline</literal> section with the kernel command line to pass to the |
69 | invoked kernel.</para></listitem> | |
ef3e110a | 70 | |
963ea30a | 71 | <listitem><para>An <literal>.initrd</literal> section with the initrd.</para></listitem> |
b6f2e686 | 72 | |
aea81bc0 TF |
73 | <listitem><para>A <literal>.ucode</literal> section with an initrd containing microcode, to be handed |
74 | to the kernel before any other initrd. This initrd must not be compressed.</para></listitem> | |
75 | ||
963ea30a ZJS |
76 | <listitem><para>A <literal>.splash</literal> section with an image (in the Windows |
77 | <filename>.BMP</filename> format) to show on screen before invoking the kernel.</para></listitem> | |
3f9a615d | 78 | |
963ea30a | 79 | <listitem><para>A <literal>.dtb</literal> section with a compiled binary DeviceTree.</para></listitem> |
111c9ba6 | 80 | |
963ea30a ZJS |
81 | <listitem><para>A <literal>.uname</literal> section with the kernel version information, i.e. the |
82 | output of <command>uname -r</command> for the kernel included in the <literal>.linux</literal> | |
83 | section.</para></listitem> | |
2c90b5ec | 84 | |
963ea30a ZJS |
85 | <listitem><para>An <literal>.sbat</literal> section with |
86 | <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">SBAT</ulink> revocation | |
87 | metadata.</para></listitem> | |
2deca517 | 88 | |
963ea30a ZJS |
89 | <listitem><para>A <literal>.pcrsig</literal> section with a set of cryptographic signatures for the |
90 | expected TPM2 PCR values after the kernel has been booted, in JSON format. This is useful for | |
91 | implementing TPM2 policies that bind disk encryption and similar to kernels that are signed by a | |
92 | specific key.</para></listitem> | |
2deca517 | 93 | |
963ea30a | 94 | <listitem><para>A <literal>.pcrpkey</literal> section with a public key in the PEM format matching the |
c309b9e9 | 95 | signature data in the <literal>.pcrsig</literal> section.</para></listitem> |
3f9a615d LP |
96 | </itemizedlist> |
97 | ||
98 | <para>If UEFI SecureBoot is enabled and the <literal>.cmdline</literal> section is present in the executed | |
99 | image, any attempts to override the kernel command line by passing one as invocation parameters to the | |
100 | EFI binary are ignored. Thus, in order to allow overriding the kernel command line, either disable UEFI | |
101 | SecureBoot, or don't include a kernel command line PE section in the kernel image file. If a command line | |
ebf3ee41 | 102 | is accepted via EFI invocation parameters to the EFI binary it is measured into TPM PCR 12 (if a TPM is |
3f9a615d | 103 | present).</para> |
111c9ba6 MR |
104 | |
105 | <para>If a DeviceTree is embedded in the <literal>.dtb</literal> section, it replaces an existing | |
106 | DeviceTree in the corresponding EFI configuration table. systemd-stub will ask the firmware via the | |
107 | <literal>EFI_DT_FIXUP_PROTOCOL</literal> for hardware specific fixups to the DeviceTree.</para> | |
72c97c19 | 108 | |
963ea30a ZJS |
109 | <para>The contents of eight of these nine sections are measured into TPM PCR 11. It is otherwise not used |
110 | and thus the result can be pre-calculated without too much effort. The <literal>.pcrsig</literal> section | |
111 | is not included in this PCR measurement, since it is supposed to contain signatures for the output of the | |
112 | measurement operation, and thus cannot also be input to it.</para> | |
2deca517 | 113 | |
963ea30a ZJS |
114 | <para>When <literal>.pcrsig</literal> and/or <literal>.pcrpkey</literal> sections are present in a |
115 | unified kernel image their contents are passed to the booted kernel in an synthetic initrd cpio archive | |
116 | that places them in the <filename>/.extra/tpm2-pcr-signature.json</filename> and | |
2deca517 LP |
117 | <filename>/.extra/tpm2-pcr-public-key.pem</filename> files. Typically, a |
118 | <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> line then | |
119 | ensures they are copied into <filename>/run/systemd/tpm2-pcr-signature.json</filename> and | |
120 | <filename>/run/systemd/tpm2-pcr-public-key.pem</filename> where they remain accessible even after the | |
121 | system transitions out of the initrd environment into the host file system. Tools such | |
122 | <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
123 | <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
124 | and <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
125 | will automatically use files present under these paths to unlock protected resources (encrypted storage | |
126 | or credentials) or bind encryption to booted kernels.</para> | |
652d2bfb LP |
127 | |
128 | <para>For further details about the UKI concept, see the <ulink | |
129 | url="https://uapi-group.org/specifications/specs/unified_kernel_image/">UKI specification</ulink>.</para> | |
3f9a615d LP |
130 | </refsect1> |
131 | ||
132 | <refsect1> | |
133 | <title>Companion Files</title> | |
134 | ||
e75386bd | 135 | <para>The <command>systemd-stub</command> UEFI boot stub automatically collects three types of auxiliary |
f3b6f333 AV |
136 | companion files optionally placed in drop-in directories on the same partition as the EFI binary, |
137 | dynamically generates <command>cpio</command> initrd archives from them, and passes them to the kernel. | |
138 | Specifically:</para> | |
3f9a615d LP |
139 | |
140 | <itemizedlist> | |
f3b6f333 | 141 | <listitem><para>For a kernel binary called <filename><replaceable>foo</replaceable>.efi</filename>, it |
3f9a615d | 142 | will look for files with the <filename>.cred</filename> suffix in a directory named |
7a876307 VD |
143 | <filename><replaceable>foo</replaceable>.efi.extra.d/</filename> next to it. If the kernel binary |
144 | uses a counter for the purpose of | |
145 | <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink>, this | |
146 | counter will be ignored. For example, <filename><replaceable>foo</replaceable>+3-0.efi</filename> | |
147 | will look in directory <filename><replaceable>foo</replaceable>.efi.extra.d/</filename>. | |
148 | A <command>cpio</command> | |
3f9a615d LP |
149 | archive is generated from all files found that way, placing them in the |
150 | <filename>/.extra/credentials/</filename> directory of the initrd file hierarchy. The main initrd may | |
151 | then access them in this directory. This is supposed to be used to store auxiliary, encrypted, | |
152 | authenticated credentials for use with <varname>LoadCredentialEncrypted=</varname> in the UEFI System | |
153 | Partition. See | |
fe003f02 ZJS |
154 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
155 | and | |
156 | <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
157 | for | |
3f9a615d | 158 | details on encrypted credentials. The generated <command>cpio</command> archive is measured into TPM |
ebf3ee41 | 159 | PCR 12 (if a TPM is present).</para></listitem> |
3f9a615d | 160 | |
39e0c237 LP |
161 | <listitem><para>Similarly, files |
162 | <filename><replaceable>foo</replaceable>.efi.extra.d/*.sysext.raw</filename> are packed up in a | |
163 | <command>cpio</command> archive and placed in the <filename>/.extra/sysext/</filename> directory in the | |
164 | initrd file hierarchy. This is supposed to be used to pass additional system extension images to the | |
165 | initrd. See | |
3f9a615d LP |
166 | <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> for |
167 | details on system extension images. The generated <command>cpio</command> archive containing these | |
de7ad6d4 | 168 | system extension images is measured into TPM PCR 13 (if a TPM is present).</para></listitem> |
f3b6f333 | 169 | |
39e0c237 LP |
170 | <!-- Note: the actual suffix we look for for sysexts is just *.raw (not *.sysext.raw), for |
171 | compatibility reasons with old versions. But we want people to name their system extensions | |
172 | properly, hence we document the *.sysext.raw suffix only. --> | |
173 | ||
174 | <listitem><para>Similarly, files | |
175 | <filename><replaceable>foo</replaceable>.efi.extra.d/*.confext.raw</filename> are packed up in a | |
176 | <command>cpio</command> archive and placed in the <filename>/.extra/confext/</filename> directory in | |
177 | the initrd file hierarchy. This is supposed to be used to pass additional configuration extension | |
178 | images to the initrd. See | |
179 | <citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry> for | |
180 | details on configuration extension images. The generated <command>cpio</command> archive containing | |
181 | these system extension images is measured into TPM PCR 12 (if a TPM is present).</para></listitem> | |
182 | ||
05c9f9c2 | 183 | <listitem><para>Similarly, files |
0155b065 ZJS |
184 | <filename><replaceable>foo</replaceable>.efi.extra.d/*.addon.efi</filename> are loaded and verified as |
185 | PE binaries, and a <literal>.cmdline</literal> section is parsed from them. Addons are supposed to be | |
186 | used to pass additional kernel command line parameters or Devicetree blobs, regardless of the kernel | |
187 | image being booted, for example to allow platform vendors to ship platform-specific | |
188 | configuration.</para> | |
189 | ||
190 | <para>In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim's DB or | |
d72835f8 | 191 | Shim's MOK, and will be rejected otherwise. Additionally, if both the addon and the UKI contain a |
0155b065 | 192 | <literal>.uname</literal> section, the addon will be rejected if they do not match exactly. It is |
05c9f9c2 LB |
193 | recommended to always add a <literal>.sbat</literal> section to all signed addons, so that they may be |
194 | revoked with a SBAT policy update, without requiring blocklisting via DBX/MOKX. The | |
0155b065 ZJS |
195 | <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool will add |
196 | a SBAT policy by default if none is passed when building addons. For more information on SBAT see | |
197 | <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>.</para> | |
198 | ||
199 | <para>Addon files are sorted, loaded, and measured into TPM PCR 12 (if a TPM is present) and appended | |
200 | to the kernel command line. UKI command line options are listed first, then options from addons in | |
201 | <filename>/loader/addons/*.addon.efi</filename>, and finally UKI-specific addons. Device tree blobs are | |
202 | loaded and measured following the same algorithm. Addons are always loaded in the same order based on | |
203 | the filename, so that, given the same set of addons, the same set of measurements can be expected in | |
204 | PCR12. However, note that the filename is not protected by the PE signature, and as such an attacker | |
205 | with write access to the ESP could potentially rename these files to change the order in which they are | |
206 | loaded, in a way that could alter the functionality of the kernel, as some options might be | |
207 | order-dependent. If you sign such addons, you should pay attention to the PCR12 values and make use of | |
208 | an attestation service so that improper use of your signed addons can be detected and dealt with using | |
209 | one of the aforementioned revocation mechanisms.</para></listitem> | |
05c9f9c2 | 210 | |
f3b6f333 AV |
211 | <listitem><para>Files <filename>/loader/credentials/*.cred</filename> are packed up in a |
212 | <command>cpio</command> archive and placed in the <filename>/.extra/global_credentials/</filename> | |
213 | directory of the initrd file hierarchy. This is supposed to be used to pass additional credentials to | |
214 | the initrd, regardless of the kernel being booted. The generated <command>cpio</command> archive is | |
966dd752 | 215 | measured into TPM PCR 12 (if a TPM is present).</para></listitem> |
05c9f9c2 LB |
216 | |
217 | <listitem><para>Additionally, files <filename>/loader/addons/*.addon.efi</filename> are loaded and | |
68f85761 LB |
218 | verified as PE binaries, and <literal>.cmdline</literal> and/or <literal>.dtb</literal> sections are |
219 | parsed from them. This is supposed to be used to pass additional command line parameters or Devicetree | |
220 | blobs to the kernel, regardless of the kernel being booted.</para></listitem> | |
3f9a615d LP |
221 | </itemizedlist> |
222 | ||
f3b6f333 | 223 | <para>These mechanisms may be used to parameterize and extend trusted (i.e. signed), immutable initrd |
3f9a615d LP |
224 | images in a reasonably safe way: all data they contain is measured into TPM PCRs. On access they should be |
225 | further validated: in case of the credentials case by encrypting/authenticating them via TPM, as exposed | |
226 | by <command>systemd-creds encrypt -T</command> (see | |
227 | <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry> for | |
228 | details); in case of the system extension images by using signed Verity images.</para> | |
229 | </refsect1> | |
230 | ||
ebf3ee41 | 231 | <refsect1> |
4889e809 | 232 | <title>TPM PCR Notes</title> |
ebf3ee41 LP |
233 | |
234 | <para>Note that when a unified kernel using <command>systemd-stub</command> is invoked the firmware will | |
235 | measure it as a whole to TPM PCR 4, covering all embedded resources, such as the stub code itself, the | |
236 | core kernel, the embedded initrd and kernel command line (see above for a full list).</para> | |
237 | ||
238 | <para>Also note that the Linux kernel will measure all initrds it receives into TPM PCR 9. This means | |
aea81bc0 | 239 | every type of initrd will be measured two or three times: the initrds embedded in the kernel image will be |
39e0c237 LP |
240 | measured to PCR 4, PCR 9 and PCR 11; the initrd synthesized from credentials (and the one synthesized |
241 | from configuration extensions) will be measured to both PCR 9 and PCR 12; the initrd synthesized from | |
242 | system extensions will be measured to both PCR 4 and PCR 9. Let's summarize the OS resources and the PCRs | |
243 | they are measured to:</para> | |
ebf3ee41 LP |
244 | |
245 | <table> | |
246 | <title>OS Resource PCR Summary</title> | |
247 | ||
248 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> | |
249 | <colspec colname="pcr" /> | |
250 | <colspec colname="definition" /> | |
251 | ||
252 | <thead> | |
253 | <row> | |
254 | <entry>OS Resource</entry> | |
255 | <entry>Measurement PCR</entry> | |
256 | </row> | |
257 | </thead> | |
258 | ||
259 | <tbody> | |
260 | <row> | |
261 | <entry><command>systemd-stub</command> code (the entry point of the unified PE binary)</entry> | |
262 | <entry>4</entry> | |
263 | </row> | |
264 | ||
265 | <row> | |
2deca517 | 266 | <entry>Core kernel code (embedded in unified PE binary)</entry> |
72c97c19 | 267 | <entry>4 + 11</entry> |
ebf3ee41 LP |
268 | </row> |
269 | ||
270 | <row> | |
2deca517 | 271 | <entry>OS release information (embedded in the unified PE binary)</entry> |
72c97c19 | 272 | <entry>4 + 11</entry> |
ebf3ee41 LP |
273 | </row> |
274 | ||
275 | <row> | |
276 | <entry>Main initrd (embedded in unified PE binary)</entry> | |
72c97c19 | 277 | <entry>4 + 9 + 11</entry> |
ebf3ee41 LP |
278 | </row> |
279 | ||
aea81bc0 TF |
280 | <row> |
281 | <entry>Microcode initrd (embedded in unified PE binary)</entry> | |
282 | <entry>4 + 9 + 11</entry> | |
283 | </row> | |
284 | ||
ebf3ee41 LP |
285 | <row> |
286 | <entry>Default kernel command line (embedded in unified PE binary)</entry> | |
72c97c19 | 287 | <entry>4 + 11</entry> |
ebf3ee41 LP |
288 | </row> |
289 | ||
290 | <row> | |
8ac6b05b | 291 | <entry>Overridden kernel command line</entry> |
ebf3ee41 LP |
292 | <entry>12</entry> |
293 | </row> | |
294 | ||
2deca517 LP |
295 | <row> |
296 | <entry>Boot splash (embedded in the unified PE binary)</entry> | |
297 | <entry>4 + 11</entry> | |
298 | </row> | |
299 | ||
300 | <row> | |
301 | <entry>TPM2 PCR signature JSON (embedded in unified PE binary, synthesized into initrd)</entry> | |
302 | <entry>4 + 9</entry> | |
303 | </row> | |
304 | ||
305 | <row> | |
306 | <entry>TPM2 PCR PEM public key (embedded in unified PE binary, synthesized into initrd)</entry> | |
307 | <entry>4 + 9 + 11</entry> | |
308 | </row> | |
309 | ||
ebf3ee41 LP |
310 | <row> |
311 | <entry>Credentials (synthesized initrd from companion files)</entry> | |
599fe002 | 312 | <entry>9 + 12</entry> |
ebf3ee41 LP |
313 | </row> |
314 | ||
315 | <row> | |
316 | <entry>System Extensions (synthesized initrd from companion files)</entry> | |
de7ad6d4 | 317 | <entry>9 + 13</entry> |
ebf3ee41 | 318 | </row> |
39e0c237 LP |
319 | |
320 | <row> | |
321 | <entry>Configuration Extensions (synthesized initrd from companion files)</entry> | |
322 | <entry>9 + 12</entry> | |
323 | </row> | |
ebf3ee41 LP |
324 | </tbody> |
325 | </tgroup> | |
326 | </table> | |
327 | </refsect1> | |
328 | ||
3f9a615d LP |
329 | <refsect1> |
330 | <title>EFI Variables</title> | |
331 | ||
332 | <para>The following EFI variables are defined, set and read by <command>systemd-stub</command>, under the | |
333 | vendor UUID <literal>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</literal>, for communication between the boot | |
334 | stub and the OS:</para> | |
335 | ||
336 | <variablelist class='efi-variables'> | |
337 | <varlistentry> | |
338 | <term><varname>LoaderDevicePartUUID</varname></term> | |
339 | ||
340 | <listitem><para>Contains the partition UUID of the EFI System Partition the EFI image was run | |
341 | from. <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
342 | uses this information to automatically find the disk booted from, in order to discover various other | |
ec07c3c8 AK |
343 | partitions on the same disk automatically.</para> |
344 | ||
345 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
3f9a615d LP |
346 | </varlistentry> |
347 | ||
348 | <varlistentry> | |
349 | <term><varname>LoaderFirmwareInfo</varname></term> | |
350 | <term><varname>LoaderFirmwareType</varname></term> | |
351 | ||
352 | <listitem><para>Brief firmware information. Use | |
353 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this | |
ec07c3c8 AK |
354 | data.</para> |
355 | ||
356 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
3f9a615d LP |
357 | </varlistentry> |
358 | ||
359 | <varlistentry> | |
360 | <term><varname>LoaderImageIdentifier</varname></term> | |
361 | ||
362 | <listitem><para>The path of EFI executable, relative to the EFI System Partition's root | |
363 | directory. Use | |
364 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view | |
ec07c3c8 AK |
365 | this data.</para> |
366 | ||
367 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
3f9a615d LP |
368 | </varlistentry> |
369 | ||
370 | <varlistentry> | |
371 | <term><varname>StubInfo</varname></term> | |
372 | ||
373 | <listitem><para>Brief stub information. Use | |
374 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view | |
ec07c3c8 AK |
375 | this data.</para> |
376 | ||
377 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
3f9a615d | 378 | </varlistentry> |
599fe002 | 379 | |
72c97c19 LP |
380 | <varlistentry> |
381 | <term><varname>StubPcrKernelImage</varname></term> | |
382 | ||
b66a6e1a ZJS |
383 | <listitem><para>The PCR register index the kernel image, initrd image, boot splash, devicetree |
384 | database, and the embedded command line are measured into, formatted as decimal ASCII string (e.g. | |
385 | <literal>11</literal>). This variable is set if a measurement was successfully completed, and remains | |
ec07c3c8 AK |
386 | unset otherwise.</para> |
387 | ||
388 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
72c97c19 LP |
389 | </varlistentry> |
390 | ||
599fe002 LP |
391 | <varlistentry> |
392 | <term><varname>StubPcrKernelParameters</varname></term> | |
393 | ||
394 | <listitem><para>The PCR register index the kernel command line and credentials are measured into, | |
b66a6e1a | 395 | formatted as decimal ASCII string (e.g. <literal>12</literal>). This variable is set if a measurement |
ec07c3c8 AK |
396 | was successfully completed, and remains unset otherwise.</para> |
397 | ||
398 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
599fe002 | 399 | </varlistentry> |
de7ad6d4 LP |
400 | |
401 | <varlistentry> | |
402 | <term><varname>StubPcrInitRDSysExts</varname></term> | |
403 | ||
39e0c237 LP |
404 | <listitem><para>The PCR register index the system extensions for the initrd, which are picked up from |
405 | the file system the kernel image is located on. Formatted as decimal ASCII string (e.g. | |
b66a6e1a | 406 | <literal>13</literal>). This variable is set if a measurement was successfully completed, and remains |
ec07c3c8 AK |
407 | unset otherwise.</para> |
408 | ||
409 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
de7ad6d4 | 410 | </varlistentry> |
39e0c237 LP |
411 | |
412 | <varlistentry> | |
413 | <term><varname>StubPcrInitRDConfExts</varname></term> | |
414 | ||
415 | <listitem><para>The PCR register index the configuration extensions for the initrd, which are picked | |
416 | up from the file system the kernel image is located on. Formatted as decimal ASCII string (e.g. | |
417 | <literal>12</literal>). This variable is set if a measurement was successfully completed, and remains | |
418 | unset otherwise.</para> | |
419 | ||
420 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
421 | </varlistentry> | |
3f9a615d LP |
422 | </variablelist> |
423 | ||
424 | <para>Note that some of the variables above may also be set by the boot loader. The stub will only set | |
425 | them if they aren't set already. Some of these variables are defined by the <ulink | |
426 | url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para> | |
427 | </refsect1> | |
428 | ||
2deca517 LP |
429 | <refsect1> |
430 | <title>initrd Resources</title> | |
431 | ||
432 | <para>The following resources are passed as initrd cpio archives to the booted kernel, and thus make up | |
433 | the initial file system hierarchy in the initrd execution environment:</para> | |
434 | ||
435 | <variablelist> | |
436 | <varlistentry> | |
437 | <term><filename>/</filename></term> | |
438 | ||
963ea30a ZJS |
439 | <listitem><para>The main initrd from the <literal>.initrd</literal> PE section of the unified kernel |
440 | image.</para> | |
ec07c3c8 AK |
441 | |
442 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
2deca517 LP |
443 | </varlistentry> |
444 | ||
445 | <varlistentry> | |
446 | <term><filename>/.extra/credentials/*.cred</filename></term> | |
447 | <listitem><para>Credential files (suffix <literal>.cred</literal>) that are placed next to the | |
448 | unified kernel image (as described above) are copied into the | |
449 | <filename>/.extra/credentials/</filename> directory in the initrd execution | |
ec07c3c8 AK |
450 | environment.</para> |
451 | ||
452 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
2deca517 LP |
453 | </varlistentry> |
454 | ||
455 | <varlistentry> | |
456 | <term><filename>/.extra/global_credentials/*.cred</filename></term> | |
963ea30a ZJS |
457 | <listitem><para>Similarly, credential files in the <filename>/loader/credentials/</filename> |
458 | directory in the file system the unified kernel image is placed in are copied into the | |
2deca517 | 459 | <filename>/.extra/global_credentials/</filename> directory in the initrd execution |
ec07c3c8 AK |
460 | environment.</para> |
461 | ||
462 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
2deca517 LP |
463 | </varlistentry> |
464 | ||
465 | <varlistentry> | |
39e0c237 LP |
466 | <term><filename>/.extra/sysext/*.sysext.raw</filename></term> |
467 | <listitem><para>System extension image files (suffix <literal>.sysext.raw</literal>) that are placed | |
468 | next to the unified kernel image (as described above) are copied into the | |
ec07c3c8 AK |
469 | <filename>/.extra/sysext/</filename> directory in the initrd execution environment.</para> |
470 | ||
471 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
2deca517 LP |
472 | </varlistentry> |
473 | ||
39e0c237 LP |
474 | <varlistentry> |
475 | <term><filename>/.extra/confext/*.confext.raw</filename></term> | |
476 | <listitem><para>Configuration extension image files (suffix <literal>.confext.raw</literal>) that are | |
477 | placed next to the unified kernel image (as described above) are copied into the | |
478 | <filename>/.extra/confext/</filename> directory in the initrd execution environment.</para> | |
479 | ||
480 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
481 | </varlistentry> | |
482 | ||
2deca517 LP |
483 | <varlistentry> |
484 | <term><filename>/.extra/tpm2-pcr-signature.json</filename></term> | |
485 | <listitem><para>The TPM2 PCR signature JSON object included in the <literal>.pcrsig</literal> PE | |
486 | section of the unified kernel image is copied into the | |
963ea30a | 487 | <filename>/.extra/tpm2-pcr-signature.json</filename> file in the initrd execution environment.</para> |
ec07c3c8 AK |
488 | |
489 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
2deca517 LP |
490 | </varlistentry> |
491 | ||
492 | <varlistentry> | |
493 | <term><filename>/.extra/tpm2-pcr-pkey.pem</filename></term> | |
494 | <listitem><para>The PEM public key included in the <literal>.pcrpkey</literal> PE section of the | |
495 | unified kernel image is copied into the <filename>/.extra/tpm2-pcr-public-key.pem</filename> file in | |
ec07c3c8 AK |
496 | the initrd execution environment.</para> |
497 | ||
498 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
2deca517 LP |
499 | </varlistentry> |
500 | </variablelist> | |
501 | ||
502 | <para>Note that all these files are located in the <literal>tmpfs</literal> file system the kernel sets | |
503 | up for the initrd file hierarchy and are thus lost when the system transitions from the initrd execution | |
504 | environment into the host file system. If these resources shall be kept around over this transition they | |
505 | need to be copied to a place that survives the transition first, for example via a suitable | |
506 | <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> line. By | |
507 | default, this is done for the TPM2 PCR signature and public key files.</para> | |
508 | </refsect1> | |
509 | ||
717af0de DDM |
510 | <refsect1> |
511 | <title>SMBIOS Type 11 Strings</title> | |
512 | ||
513 | <para><command>systemd-stub</command> can be configured using SMBIOS Type 11 strings. Applicable strings | |
f7100379 DDM |
514 | consist of a name, followed by <literal>=</literal>, followed by the value. Unless |
515 | <command>systemd-stub</command> detects it is running inside a confidential computing environment, | |
717af0de DDM |
516 | <command>systemd-stub</command> will search the table for a string with a specific name, and if found, |
517 | use its value. The following strings are read:</para> | |
518 | ||
519 | <variablelist> | |
520 | <varlistentry> | |
521 | <term><varname>io.systemd.stub.kernel-cmdline-extra</varname></term> | |
522 | <listitem><para>If set, the value of this string is added to the list of kernel command line | |
ec07c3c8 AK |
523 | arguments that are measured in PCR12 and passed to the kernel.</para> |
524 | ||
525 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
717af0de DDM |
526 | </varlistentry> |
527 | </variablelist> | |
528 | </refsect1> | |
529 | ||
3f9a615d LP |
530 | <refsect1> |
531 | <title>Assembling Kernel Images</title> | |
532 | ||
e069c57f JJ |
533 | <para>In order to assemble a bootable Unified Kernel Image from various components as described above, use |
534 | <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> | |
3f9a615d LP |
535 | </refsect1> |
536 | ||
537 | <refsect1> | |
538 | <title>See Also</title> | |
13a69c12 DT |
539 | <para><simplelist type="inline"> |
540 | <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
541 | <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
542 | <member><citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
543 | <member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
544 | <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member> | |
545 | <member><ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink></member> | |
546 | <member><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
547 | <member><citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
548 | <member><ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink></member> | |
549 | </simplelist></para> | |
3f9a615d LP |
550 | </refsect1> |
551 | </refentry> |