Debian Codegraph @

upstream/debian-trixie/man7/systemd-stub.7

raw
1 '\" t
2 .TH "SYSTEMD\-STUB" "7" "" "systemd 257.13" "systemd-stub"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-stub, sd-stub, linuxx64.efi.stub, linuxia32.efi.stub, linuxaa64.efi.stub \- A simple UEFI kernel boot stub
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 /usr/lib/systemd/boot/efi/linuxx64\&.efi\&.stub
28 .RE
29 .RS 4
30 /usr/lib/systemd/boot/efi/linuxia32\&.efi\&.stub
31 .RE
32 .RS 4
33 /usr/lib/systemd/boot/efi/linuxaa64\&.efi\&.stub
34 .RE
35 .RS 4
36 \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.addon\&.efi
37 .RE
38 .RS 4
39 \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.cred
40 .RE
41 .RS 4
42 \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.raw
43 .RE
44 .RS 4
45 \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.sysext\&.raw
46 .RE
47 .RS 4
48 \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.confext\&.raw
49 .RE
50 .RS 4
51 \fIESP\fR/loader/addons/*\&.addon\&.efi
52 .RE
53 .RS 4
54 \fIESP\fR/loader/credentials/*\&.cred
55 .RE
56 .SH "DESCRIPTION"
57 .PP
58 \fBsystemd\-stub\fR
59 (stored in per\-architecture files
60 linuxx64\&.efi\&.stub,
61 linuxia32\&.efi\&.stub,
62 linuxaa64\&.efi\&.stub
63 on disk) is a simple UEFI boot stub\&. An UEFI boot stub is attached to a Linux kernel binary image, and is a piece of code that runs in the UEFI firmware environment before transitioning into the Linux kernel environment\&. The UEFI boot stub ensures a Linux kernel is executable as regular UEFI binary, and is able to do various preparations before switching the system into the Linux world\&.
64 .PP
65 The UEFI boot stub looks for various resources for the kernel invocation inside the UEFI PE binary itself\&. This allows combining various resources inside a single PE binary image (a "Unified Kernel Image" or "UKI" for short), which may then be signed via UEFI SecureBoot as a whole, covering all individual resources at once\&. Specifically it may include the following PE sections:
66 .sp
67 .RS 4
68 .ie n \{\
69 \h'-04'\(bu\h'+03'\c
70 .\}
71 .el \{\
72 .sp -1
73 .IP \(bu 2.3
74 .\}
75 A
76 "\&.linux"
77 section with the ELF Linux kernel image\&. This section is required\&.
78 .RE
79 .sp
80 .RS 4
81 .ie n \{\
82 \h'-04'\(bu\h'+03'\c
83 .\}
84 .el \{\
85 .sp -1
86 .IP \(bu 2.3
87 .\}
88 An optional
89 "\&.osrel"
90 section with OS release information, i\&.e\&. the contents of the
91 \fBos-release\fR(5)
92 file of the OS the kernel belongs to\&.
93 .RE
94 .sp
95 .RS 4
96 .ie n \{\
97 \h'-04'\(bu\h'+03'\c
98 .\}
99 .el \{\
100 .sp -1
101 .IP \(bu 2.3
102 .\}
103 An optional
104 "\&.cmdline"
105 section with the kernel command line to pass to the invoked kernel\&.
106 .RE
107 .sp
108 .RS 4
109 .ie n \{\
110 \h'-04'\(bu\h'+03'\c
111 .\}
112 .el \{\
113 .sp -1
114 .IP \(bu 2.3
115 .\}
116 An optional
117 "\&.initrd"
118 section with the initrd\&.
119 .RE
120 .sp
121 .RS 4
122 .ie n \{\
123 \h'-04'\(bu\h'+03'\c
124 .\}
125 .el \{\
126 .sp -1
127 .IP \(bu 2.3
128 .\}
129 An optional
130 "\&.ucode"
131 section with an initrd containing microcode, to be handed to the kernel before any other initrd\&. This initrd must not be compressed\&.
132 .RE
133 .sp
134 .RS 4
135 .ie n \{\
136 \h'-04'\(bu\h'+03'\c
137 .\}
138 .el \{\
139 .sp -1
140 .IP \(bu 2.3
141 .\}
142 An optional
143 "\&.splash"
144 section with an image (in the Windows
145 \&.BMP
146 format) to show on screen before invoking the kernel\&.
147 .RE
148 .sp
149 .RS 4
150 .ie n \{\
151 \h'-04'\(bu\h'+03'\c
152 .\}
153 .el \{\
154 .sp -1
155 .IP \(bu 2.3
156 .\}
157 An optional
158 "\&.dtb"
159 section with a compiled binary DeviceTree\&.
160 .RE
161 .sp
162 .RS 4
163 .ie n \{\
164 \h'-04'\(bu\h'+03'\c
165 .\}
166 .el \{\
167 .sp -1
168 .IP \(bu 2.3
169 .\}
170 Zero or more
171 "\&.dtbauto"
172 sections\&.
173 systemd\-stub
174 will always use the first matching one\&. The match is performed by taking the first DeviceTree\*(Aqs
175 \fIcompatible\fR
176 string supplied by the firmware in configuration tables and comparing it with the first
177 \fIcompatible\fR
178 string from each of the
179 "\&.dtbauto"
180 sections\&. If the firmware does not provide a DeviceTree, the match is done using the
181 \fI\&.hwids\fR
182 section instead\&. After selecting a
183 "\&.hwids"
184 section (see the description below), the
185 \fIcompatible\fR
186 string from that section will be used to perform the same matching procedure\&. If a match is found, that
187 "\&.dtbauto"
188 section will be loaded and will override
189 \fI\&.dtb\fR
190 if present\&.
191 .RE
192 .sp
193 .RS 4
194 .ie n \{\
195 \h'-04'\(bu\h'+03'\c
196 .\}
197 .el \{\
198 .sp -1
199 .IP \(bu 2.3
200 .\}
201 Zero or more
202 "\&.hwids"
203 sections with hardware IDs of the machines to match DeviceTrees\&.
204 systemd\-stub
205 will use the SMBIOS data to calculate hardware IDs of the machine (as per
206 \m[blue]\fBspecification\fR\m[]\&\s-2\u[1]\d\s+2), and then it will try to find any of them in each of the
207 "\&.hwids"
208 sections\&. The first matching section will be used\&.
209 .RE
210 .sp
211 .RS 4
212 .ie n \{\
213 \h'-04'\(bu\h'+03'\c
214 .\}
215 .el \{\
216 .sp -1
217 .IP \(bu 2.3
218 .\}
219 An optional
220 "\&.uname"
221 section with the kernel version information, i\&.e\&. the output of
222 \fBuname \-r\fR
223 for the kernel included in the
224 "\&.linux"
225 section\&.
226 .RE
227 .sp
228 .RS 4
229 .ie n \{\
230 \h'-04'\(bu\h'+03'\c
231 .\}
232 .el \{\
233 .sp -1
234 .IP \(bu 2.3
235 .\}
236 An optional
237 "\&.sbat"
238 section with
239 \m[blue]\fBSBAT\fR\m[]\&\s-2\u[2]\d\s+2
240 revocation metadata\&.
241 .RE
242 .sp
243 .RS 4
244 .ie n \{\
245 \h'-04'\(bu\h'+03'\c
246 .\}
247 .el \{\
248 .sp -1
249 .IP \(bu 2.3
250 .\}
251 An optional
252 "\&.pcrsig"
253 section with a set of cryptographic signatures for the expected TPM2 PCR values after the kernel has been booted, in JSON format\&. This is useful for implementing TPM2 policies that bind disk encryption and similar to kernels that are signed by a specific key\&.
254 .RE
255 .sp
256 .RS 4
257 .ie n \{\
258 \h'-04'\(bu\h'+03'\c
259 .\}
260 .el \{\
261 .sp -1
262 .IP \(bu 2.3
263 .\}
264 An optional
265 "\&.pcrpkey"
266 section with a public key in the PEM format matching the signature data in the
267 "\&.pcrsig"
268 section\&.
269 .RE
270 .PP
271 In a basic UKI, the sections listed above appear at most once, with the exception of
272 "\&.dtbauto"
273 and
274 "\&.hwids"
275 sections\&. In a multi\-profile UKI, multiple sets of these sections are present in a single file and form "profiles", one of which can be selected at boot\&. For this, the PE section
276 "\&.profile"
277 is defined to be used as the separator between sets of sections\&. The
278 "\&.profile"
279 section itself may contain meta\-information about the section, and follows a similar structure as the contents of the
280 "\&.osrel"
281 section\&. For further details about multi\-profile UKIs, see below\&.
282 .PP
283 If UEFI SecureBoot is enabled and the
284 "\&.cmdline"
285 section is present in the executed image, any attempts to override the kernel command line by passing one as invocation parameters to the EFI binary are ignored\&. Thus, in order to allow overriding the kernel command line, either disable UEFI SecureBoot, or do not include a kernel command line PE section in the kernel image file\&. If a command line is accepted via EFI invocation parameters to the EFI binary it is measured into TPM PCR 12 (if a TPM is present)\&.
286 .PP
287 If a DeviceTree is embedded in the
288 "\&.dtb"
289 section, it replaces an existing DeviceTree in the corresponding EFI configuration table\&.
290 \fBsystemd\-stub\fR
291 will ask the firmware via the
292 "EFI_DT_FIXUP_PROTOCOL"
293 for hardware specific fixups to the DeviceTree\&.
294 .PP
295 The contents of 11 of these 12 sections are measured into TPM PCR 11\&. It is otherwise not used and thus the result can be pre\-calculated without too much effort\&. The
296 "\&.pcrsig"
297 section is not included in this PCR measurement, since it is supposed to contain signatures for the output of the measurement operation, and thus cannot also be input to it\&. If an UKI contains multiple profiles, only the PE sections of the selected profile (and those of the base profile, except if overridden) are measured\&.
298 .PP
299 If non\-zero, the selected numeric profile is measured into PCR 12\&.
300 .PP
301 When
302 "\&.pcrsig"
303 and/or
304 "\&.pcrpkey"
305 sections are present in a unified kernel image their contents are passed to the booted kernel in an synthetic initrd cpio archive that places them in the
306 /\&.extra/tpm2\-pcr\-signature\&.json
307 and
308 /\&.extra/tpm2\-pcr\-public\-key\&.pem
309 files\&. Typically, a
310 \fBtmpfiles.d\fR(5)
311 line then ensures they are copied into
312 /run/systemd/tpm2\-pcr\-signature\&.json
313 and
314 /run/systemd/tpm2\-pcr\-public\-key\&.pem
315 where they remain accessible even after the system transitions out of the initrd environment into the host file system\&. Tools such
316 \[email protected]\fR(8),
317 \fBsystemd-cryptenroll\fR(1)
318 and
319 \fBsystemd-creds\fR(1)
320 will automatically use files present under these paths to unlock protected resources (encrypted storage or credentials) or bind encryption to booted kernels\&.
321 .PP
322 For further details about the UKI concept, see the
323 \m[blue]\fBUKI specification\fR\m[]\&\s-2\u[3]\d\s+2\&.
324 .SH "COMPANION FILES"
325 .PP
326 The
327 \fBsystemd\-stub\fR
328 UEFI boot stub automatically collects three types of auxiliary companion files optionally placed in drop\-in directories on the same partition as the EFI binary, dynamically generates
329 \fBcpio\fR
330 initrd archives from them, and passes them to the kernel\&. Specifically:
331 .sp
332 .RS 4
333 .ie n \{\
334 \h'-04'\(bu\h'+03'\c
335 .\}
336 .el \{\
337 .sp -1
338 .IP \(bu 2.3
339 .\}
340 For a kernel binary called
341 \fIfoo\fR\&.efi, it will look for files with the
342 \&.cred
343 suffix in a directory named
344 \fIfoo\fR\&.efi\&.extra\&.d/
345 next to it\&. If the kernel binary uses a counter for the purpose of
346 \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[4]\d\s+2, this counter will be ignored\&. For example,
347 \fIfoo\fR+3\-0\&.efi
348 will look in directory
349 \fIfoo\fR\&.efi\&.extra\&.d/\&. A
350 \fBcpio\fR
351 archive is generated from all files found that way, placing them in the
352 /\&.extra/credentials/
353 directory of the initrd file hierarchy\&. The main initrd may then access them in this directory\&. This is supposed to be used to store auxiliary, encrypted, authenticated credentials for use with
354 \fILoadCredentialEncrypted=\fR
355 in the UEFI System Partition\&. See
356 \fBsystemd.exec\fR(5)
357 and
358 \fBsystemd-creds\fR(1)
359 for details on encrypted credentials\&. The generated
360 \fBcpio\fR
361 archive is measured into TPM PCR 12 (if a TPM is present)\&.
362 .RE
363 .sp
364 .RS 4
365 .ie n \{\
366 \h'-04'\(bu\h'+03'\c
367 .\}
368 .el \{\
369 .sp -1
370 .IP \(bu 2.3
371 .\}
372 Similarly, files
373 \fIfoo\fR\&.efi\&.extra\&.d/*\&.sysext\&.raw
374 are packed up in a
375 \fBcpio\fR
376 archive and placed in the
377 /\&.extra/sysext/
378 directory in the initrd file hierarchy\&. This is supposed to be used to pass additional system extension images to the initrd\&. See
379 \fBsystemd-sysext\fR(8)
380 for details on system extension images\&. The generated
381 \fBcpio\fR
382 archive containing these system extension images is measured into TPM PCR 13 (if a TPM is present)\&.
383 .RE
384 .sp
385 .RS 4
386 .ie n \{\
387 \h'-04'\(bu\h'+03'\c
388 .\}
389 .el \{\
390 .sp -1
391 .IP \(bu 2.3
392 .\}
393 Similarly, files
394 \fIfoo\fR\&.efi\&.extra\&.d/*\&.confext\&.raw
395 are packed up in a
396 \fBcpio\fR
397 archive and placed in the
398 /\&.extra/confext/
399 directory in the initrd file hierarchy\&. This is supposed to be used to pass additional configuration extension images to the initrd\&. See
400 \fBsystemd-confext\fR(8)
401 for details on configuration extension images\&. The generated
402 \fBcpio\fR
403 archive containing these configuration extension images is measured into TPM PCR 12 (if a TPM is present)\&.
404 .RE
405 .sp
406 .RS 4
407 .ie n \{\
408 \h'-04'\(bu\h'+03'\c
409 .\}
410 .el \{\
411 .sp -1
412 .IP \(bu 2.3
413 .\}
414 Similarly, files
415 \fIfoo\fR\&.efi\&.extra\&.d/*\&.addon\&.efi
416 are loaded and verified as PE binaries and specific sections are loaded from them\&. Addons are used to pass additional kernel command line parameters ("\&.cmdline"
417 section), or DeviceTree blobs ("\&.dtb"
418 section), additional initrds ("\&.initrd"
419 section), and microcode updates ("\&.ucode"
420 section)\&. Addons allow those resources to be passed regardless of the kernel version being booted, for example allowing platform vendors to ship platform\-specific configuration\&.
421 .sp
422 In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim\*(Aqs DB or Shim\*(Aqs MOK, and only loaded if the check passes\&. Additionally, if both the addon and the UKI contain a
423 "\&.uname"
424 section, the addon will be rejected if they do not match exactly\&. It is recommended to always add a
425 "\&.sbat"
426 section to all signed addons, so that they may be revoked with a SBAT policy update, without requiring blocklisting via DBX/MOKX\&. The
427 \fBukify\fR(1)
428 tool will add a SBAT policy by default if none is passed when building addons\&. For more information on SBAT see
429 \m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
430 .sp
431 Addon files are sorted, loaded, and measured into TPM PCR 12 (if a TPM is present) and appended to the kernel command line\&. UKI command line options are listed first, then options from addons in
432 /loader/addons/*\&.addon\&.efi, and finally UKI\-specific addons\&. Device tree blobs are loaded and measured following the same algorithm\&. Microcode addons are passed to the kernel in inverse order (UKI specific addons, global addons, UKI embedded section)\&. This is because the microcode update driver stops on the first matching filename\&. Addons are always loaded in the same order based on the filename, so that, given the same set of addons, the same set of measurements can be expected in PCR12\&. However, note that the filename is not protected by the PE signature, and as such an attacker with write access to the ESP could potentially rename these files to change the order in which they are loaded, in a way that could alter the functionality of the kernel, as some options might be order\-dependent\&. If you sign such addons, you should pay attention to the PCR12 values and make use of an attestation service so that improper use of your signed addons can be detected and dealt with using one of the aforementioned revocation mechanisms\&.
433 .RE
434 .sp
435 .RS 4
436 .ie n \{\
437 \h'-04'\(bu\h'+03'\c
438 .\}
439 .el \{\
440 .sp -1
441 .IP \(bu 2.3
442 .\}
443 Files
444 /loader/credentials/*\&.cred
445 are packed up in a
446 \fBcpio\fR
447 archive and placed in the
448 /\&.extra/global_credentials/
449 directory of the initrd file hierarchy\&. This is supposed to be used to pass additional credentials to the initrd, regardless of the kernel version being booted\&. The generated
450 \fBcpio\fR
451 archive is measured into TPM PCR 12 (if a TPM is present)\&.
452 .RE
453 .sp
454 .RS 4
455 .ie n \{\
456 \h'-04'\(bu\h'+03'\c
457 .\}
458 .el \{\
459 .sp -1
460 .IP \(bu 2.3
461 .\}
462 Additionally, files
463 /loader/addons/*\&.addon\&.efi
464 are loaded and verified as PE binaries, and
465 "\&.cmdline",
466 "\&.dtb",
467 "\&.initrd", and
468 "\&.ucode"
469 sections are parsed from them\&. This is supposed to be used to pass additional command line parameters, DeviceTree blobs, initrds, and microcode updates to the kernel, regardless of the kernel version being booted\&.
470 .RE
471 .PP
472 These mechanisms may be used to parameterize and extend trusted (i\&.e\&. signed), immutable initrd images in a reasonably safe way: all data they contain is measured into TPM PCRs\&. On access they should be further validated: in case of the credentials case by encrypting/authenticating them via TPM, as exposed by
473 \fBsystemd\-creds encrypt \-T\fR
474 (see
475 \fBsystemd-creds\fR(1)
476 for details); in case of the system extension images by using signed Verity images\&.
477 .SH "MULTI\-PROFILE UKIS"
478 .PP
479 In many contexts it is useful to allow invocation of a single UKI in multiple different modes (or "profiles") without compromising the cryptographic integrity, measurements and so on of the boot process\&. For example, a single UKI might provide three distinct profiles: a regular boot one, one that invokes a "factory reset" operation, and one that boots into a storage target mode (as in
480 \fBsystemd-storagetm.service\fR(8))\&. Each profile would then use the same
481 "\&.linux"
482 and
483 "\&.initrd"
484 sections, but would have a separate
485 "\&.cmdline"
486 section\&. For example the latter two profiles would extend the regular kernel command line with
487 "systemd\&.unit=factory\-reset\&.target"
488 or
489 "rd\&.systemd\&.unit=storagetm\&.target"\&.
490 .PP
491 A single UKI may support multiple profiles by means of the special
492 "\&.profile"
493 PE section\&. This section acts as separator between the PE sections of the individual profiles\&.
494 "\&.profile"
495 PE sections hence may appear multiple times in a single UKI, and the other PE sections listed above may appear multiple times too, if
496 "\&.profile"
497 are used, but only once before the first
498 "\&.profile"
499 section, once between each subsequent pair, and once after the last appearance of
500 "\&.profile"\&. The sections listed before the first
501 "\&.profile"
502 are considered the "base" profile of the UKI\&. Each
503 "\&.profile"
504 section then introduces a new profile, which are numbered starting from zero\&. The PE sections following each
505 "\&.profile"
506 are specific to that profile\&. When booting into a specific profile, the base section\*(Aqs profiles are used in combination with the specific profile\*(Aqs sections: if the same section is defined in both, the per\-profile section overrides the base profile\*(Aqs version, otherwise the base profile sections are used\&.
507 .PP
508 A UKI that contains no
509 "\&.profile"
510 is consider equivalent to one that just contains a single
511 "\&.profile", as having only a single profile
512 "@0"\&.
513 .PP
514 Here\*(Aqs a simple example for a multi\-profile UKI\*(Aqs sections, inspired by the setup suggested above:
515 .sp
516 .it 1 an-trap
517 .nr an-no-space-flag 1
518 .nr an-break-flag 1
519 .br
520 .B Table\ \&1.\ \&Multi\-Profile UKI Example
521 .TS
522 allbox tab(:);
523 lB lB.
524 T{
525 Section
526 T}:T{
527 Profile
528 T}
529 .T&
530 l l
531 l ^
532 l ^
533 l ^
534 l l
535 l l
536 l ^
537 l l
538 l ^.
539 T{
540 "\&.linux"
541 T}:T{
542 Base profile
543 T}
544 T{
545 "\&.osrel"
546 T}:
547 T{
548 "\&.cmdline"
549 T}:
550 T{
551 "\&.initrd"
552 T}:
553 T{
554 "\&.profile"
555 T}:T{
556 Profile @0
557 T}
558 T{
559 "\&.profile"
560 T}:T{
561 Profile @1
562 T}
563 T{
564 "\&.cmdline"
565 T}:
566 T{
567 "\&.profile"
568 T}:T{
569 Profile @2
570 T}
571 T{
572 "\&.cmdline"
573 T}:
574 .TE
575 .sp 1
576 .PP
577 The section list above would define three profiles\&. The first four sections make up the base profile\&. A
578 "\&.profile"
579 section then introduces profile @0\&. It does not override any sections (or add any) from the base section, hence it is immediately followed by another
580 "\&.profile"
581 section that then introduces section @1\&. This profile overrides the kernel command line\&. Finally, the last two sections define section @2, again overriding the command line\&. (Note that in this example the first
582 "\&.cmdline"
583 could also moved behind the first
584 "\&.profile"
585 with equivalent effect\&. To keep things nicely extensible, it is probably a good idea to keep the generic command line in the base section instead of profile 0, in case later added profiles might want to reuse it\&.)
586 .PP
587 The profile to boot may be controlled via the UKI\*(Aqs own command line: if the first argument starts with
588 "@", followed by a positive integer number in decimal, it selects the profile to boot into\&. If the first argument is not specified like that, the UKI will automatically boot into profile 0\&.
589 .PP
590 A
591 "\&.profile"
592 section may contain meta\-information about the profile\&. It follows a similar format as
593 "\&.osrel"
594 (i\&.e\&. an environment\-variable\-assignment\-block\-like list of newline separated strings)\&. Currently two fields are defined:
595 "ID="
596 is supposed to carry a short identifying string that identifies the profile (e\&.g\&.
597 "ID=factory\-reset")\&.
598 "TITLE="
599 should contain a human readable string that may appear in the boot menu entry for this profile (e\&.g\&.
600 "TITLE=\*(AqFactory Reset this Device\*(Aq")\&.
601 .SH "TPM PCR NOTES"
602 .PP
603 Note that when a unified kernel using
604 \fBsystemd\-stub\fR
605 is invoked the firmware will measure it as a whole to TPM PCR 4, covering all embedded resources, such as the stub code itself, the core kernel, the embedded initrd and kernel command line (see above for a full list), including all UKI profiles\&.
606 .PP
607 Also note that when
608 \fBsystemd\-stub\fR
609 measures a PE section, it will measure the amount of bytes that the section takes up in memory (\fIVirtualSize\fR) and not the amount of bytes that the section takes up on disk (\fISizeOfRawData\fR)\&. This means that if the size in memory is larger than the size on disk,
610 \fBsystemd\-stub\fR
611 will end up measuring extra zeroes\&. To avoid this from happening, it is recommended to make sure that the size in memory of each section that is measured by
612 \fBsystemd\-stub\fR
613 is always smaller than or equal to the size on disk\&.
614 \fBukify\fR
615 automatically makes sure this is the case when building UKIs or addons\&.
616 .PP
617 Also note that the Linux kernel will measure all initrds it receives into TPM PCR 9\&. This means every type of initrd (of the selected UKI profile) will possibly be measured two or three times: the initrds embedded in the kernel image will be measured to PCR 4, PCR 9 and PCR 11; the initrd synthesized from credentials (and the one synthesized from configuration extensions) will be measured to both PCR 9 and PCR 12; the initrd synthesized from system extensions will be measured to both PCR 4 and PCR 9\&. Let\*(Aqs summarize the OS resources and the PCRs they are measured to:
618 .sp
619 .it 1 an-trap
620 .nr an-no-space-flag 1
621 .nr an-break-flag 1
622 .br
623 .B Table\ \&2.\ \&OS Resource PCR Summary
624 .TS
625 allbox tab(:);
626 lB lB.
627 T{
628 OS Resource
629 T}:T{
630 Measurement PCR
631 T}
632 .T&
633 l l
634 l l
635 l l
636 l l
637 l l
638 l l
639 l l
640 l l
641 l l
642 l l
643 l l
644 l l
645 l l
646 l l.
647 T{
648 \fBsystemd\-stub\fR code (the entry point of the unified PE binary)
649 T}:T{
650 4
651 T}
652 T{
653 Core kernel code (embedded in unified PE binary)
654 T}:T{
655 4 + 11
656 T}
657 T{
658 OS release information (embedded in the unified PE binary)
659 T}:T{
660 4 + 11
661 T}
662 T{
663 Main initrd (embedded in unified PE binary)
664 T}:T{
665 4 + 9 + 11
666 T}
667 T{
668 Microcode initrd (embedded in unified PE binary)
669 T}:T{
670 4 + 9 + 11
671 T}
672 T{
673 Default kernel command line (embedded in unified PE binary)
674 T}:T{
675 4 + 11
676 T}
677 T{
678 Overridden kernel command line
679 T}:T{
680 12
681 T}
682 T{
683 Boot splash (embedded in the unified PE binary)
684 T}:T{
685 4 + 11
686 T}
687 T{
688 TPM2 PCR signature JSON (embedded in unified PE binary, synthesized into initrd)
689 T}:T{
690 4 + 9
691 T}
692 T{
693 TPM2 PCR PEM public key (embedded in unified PE binary, synthesized into initrd)
694 T}:T{
695 4 + 9 + 11
696 T}
697 T{
698 Credentials (synthesized initrd from companion files)
699 T}:T{
700 9 + 12
701 T}
702 T{
703 System Extensions (synthesized initrd from companion files)
704 T}:T{
705 9 + 13
706 T}
707 T{
708 Configuration Extensions (synthesized initrd from companion files)
709 T}:T{
710 9 + 12
711 T}
712 T{
713 Selected profile unless zero
714 T}:T{
715 12
716 T}
717 .TE
718 .sp 1
719 .SH "EFI VARIABLES"
720 .PP
721 The following EFI variables are defined, set and read by
722 \fBsystemd\-stub\fR, under the vendor UUID
723 "4a67b082\-0a4c\-41cf\-b6c7\-440b29bb8c4f", for communication between the boot stub and the OS:
724 .PP
725 \fILoaderDevicePartUUID\fR
726 .RS 4
727 Contains the partition UUID of the partition the boot loader has been started from on the current boot (usually a EFI System Partition)\&. If already set by the boot loader, this will remain untouched by
728 \fBsystemd\-stub\fR\&. If not set yet, this will be set to the partition UUID of the partition the unified kernel is started from, in order to support systems that directly boot into a unified kernel image, bypassing any boot loader\&.
729 \fBsystemd-gpt-auto-generator\fR(8)
730 uses this information to automatically find the disk booted from, in order to discover various other partitions on the same disk automatically\&.
731 .sp
732 Added in version 224\&.
733 .RE
734 .PP
735 \fILoaderFirmwareInfo\fR, \fILoaderFirmwareType\fR
736 .RS 4
737 Brief firmware information\&. Use
738 \fBbootctl\fR(1)
739 to view this data\&.
740 .sp
741 Added in version 250\&.
742 .RE
743 .PP
744 \fILoaderImageIdentifier\fR
745 .RS 4
746 The file system path to the EFI executable of the boot loader for the current boot, relative to the partition\*(Aqs root directory (i\&.e\&. relative to the partition indicated by
747 \fILoaderDevicePartUUID\fR, see above)\&. If not set yet, this will be set to the file system path of the EFI executable of the booted unified kernel, in order to support systems that directly boot into a unified kernel image, bypassing any boot loader\&. Use
748 \fBbootctl\fR(1)
749 to view this data\&.
750 .sp
751 Added in version 237\&.
752 .RE
753 .PP
754 \fIStubDevicePartUUID\fR, \fIStubImageIdentifier\fR
755 .RS 4
756 Similar to
757 \fILoaderDevicePartUUID\fR
758 and
759 \fILoaderImageIdentifier\fR, but indicates the location of the unified kernel image EFI binary rather than the location of the boot loader binary, regardless if booted via a boot loader or not\&.
760 .sp
761 Added in version 257\&.
762 .RE
763 .PP
764 \fIStubInfo\fR
765 .RS 4
766 Brief stub information\&. Use
767 \fBbootctl\fR(1)
768 to view this data\&.
769 .sp
770 Added in version 250\&.
771 .RE
772 .PP
773 \fIStubPcrKernelImage\fR
774 .RS 4
775 The PCR register index the kernel image, initrd image, boot splash, devicetree database, and the embedded command line are measured into, formatted as decimal ASCII string (e\&.g\&.
776 "11")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
777 .sp
778 Added in version 252\&.
779 .RE
780 .PP
781 \fIStubPcrKernelParameters\fR
782 .RS 4
783 The PCR register index the kernel command line and credentials are measured into, formatted as decimal ASCII string (e\&.g\&.
784 "12")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
785 .sp
786 Added in version 252\&.
787 .RE
788 .PP
789 \fIStubPcrInitRDSysExts\fR
790 .RS 4
791 The PCR register index the system extensions for the initrd, which are picked up from the file system the kernel image is located on\&. Formatted as decimal ASCII string (e\&.g\&.
792 "13")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
793 .sp
794 Added in version 252\&.
795 .RE
796 .PP
797 \fIStubPcrInitRDConfExts\fR
798 .RS 4
799 The PCR register index the configuration extensions for the initrd, which are picked up from the file system the kernel image is located on\&. Formatted as decimal ASCII string (e\&.g\&.
800 "12")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
801 .sp
802 Added in version 255\&.
803 .RE
804 .PP
805 \fIStubProfile\fR
806 .RS 4
807 The numeric index of the selected profile, without the
808 "@", formatted as decimal string\&. Set both on single\-profile and multi\-profile UKIs\&. (In the former case this variable will be set to
809 "0"
810 unconditionally\&.)
811 .sp
812 Added in version 257\&.
813 .RE
814 .PP
815 Note that some of the variables above may also be set by the boot loader\&. The stub will only set them if they are not set already\&. Some of these variables are defined by the
816 \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[5]\d\s+2\&.
817 .SH "INITRD RESOURCES"
818 .PP
819 The following resources are passed as initrd cpio archives to the booted kernel, and thus make up the initial file system hierarchy in the initrd execution environment:
820 .PP
821 /
822 .RS 4
823 The main initrd from the
824 "\&.initrd"
825 PE section of the unified kernel image\&.
826 .sp
827 Added in version 252\&.
828 .RE
829 .PP
830 /\&.extra/credentials/*\&.cred
831 .RS 4
832 Credential files (suffix
833 "\&.cred") that are placed next to the unified kernel image (as described above) are copied into the
834 /\&.extra/credentials/
835 directory in the initrd execution environment\&.
836 .sp
837 Added in version 252\&.
838 .RE
839 .PP
840 /\&.extra/global_credentials/*\&.cred
841 .RS 4
842 Similarly, credential files in the
843 /loader/credentials/
844 directory in the file system the unified kernel image is placed in are copied into the
845 /\&.extra/global_credentials/
846 directory in the initrd execution environment\&.
847 .sp
848 Added in version 252\&.
849 .RE
850 .PP
851 /\&.extra/sysext/*\&.sysext\&.raw
852 .RS 4
853 System extension image files (suffix
854 "\&.sysext\&.raw") that are placed next to the unified kernel image (as described above) are copied into the
855 /\&.extra/sysext/
856 directory in the initrd execution environment\&.
857 .sp
858 Added in version 252\&.
859 .RE
860 .PP
861 /\&.extra/confext/*\&.confext\&.raw
862 .RS 4
863 Configuration extension image files (suffix
864 "\&.confext\&.raw") that are placed next to the unified kernel image (as described above) are copied into the
865 /\&.extra/confext/
866 directory in the initrd execution environment\&.
867 .sp
868 Added in version 255\&.
869 .RE
870 .PP
871 /\&.extra/tpm2\-pcr\-signature\&.json
872 .RS 4
873 The TPM2 PCR signature JSON object included in the
874 "\&.pcrsig"
875 PE section of the unified kernel image is copied into the
876 /\&.extra/tpm2\-pcr\-signature\&.json
877 file in the initrd execution environment\&.
878 .sp
879 Added in version 252\&.
880 .RE
881 .PP
882 /\&.extra/tpm2\-pcr\-public\-key\&.pem
883 .RS 4
884 The PEM public key included in the
885 "\&.pcrpkey"
886 PE section of the unified kernel image is copied into the
887 /\&.extra/tpm2\-pcr\-public\-key\&.pem
888 file in the initrd execution environment\&.
889 .sp
890 Added in version 252\&.
891 .RE
892 .PP
893 /\&.extra/profile, /\&.extra/os\-release
894 .RS 4
895 The contents of the
896 "\&.profile"
897 and
898 "\&.osrel"
899 sections of the selected profile, if any\&.
900 .sp
901 Added in version 257\&.
902 .RE
903 .PP
904 Note that all these files are located in the
905 "tmpfs"
906 file system the kernel sets up for the initrd file hierarchy and are thus lost when the system transitions from the initrd execution environment into the host file system\&. If these resources shall be kept around over this transition they need to be copied to a place that survives the transition first, for example via a suitable
907 \fBtmpfiles.d\fR(5)
908 line\&. By default, this is done for the TPM2 PCR signature and public key files\&.
909 .SH "SMBIOS TYPE 11 STRINGS"
910 .PP
911 \fBsystemd\-stub\fR
912 can be configured using SMBIOS Type 11 strings\&. Applicable strings consist of a name, followed by
913 "=", followed by the value\&. Unless
914 \fBsystemd\-stub\fR
915 detects it is running inside a confidential computing environment,
916 \fBsystemd\-stub\fR
917 will search the table for a string with a specific name, and if found, use its value\&. The following strings are read:
918 .PP
919 \fIio\&.systemd\&.stub\&.kernel\-cmdline\-extra\fR
920 .RS 4
921 If set, the value of this string is added to the list of kernel command line arguments that are measured in PCR12 and passed to the kernel\&.
922 .sp
923 Added in version 254\&.
924 .RE
925 .SH "ASSEMBLING KERNEL IMAGES"
926 .PP
927 In order to assemble a bootable Unified Kernel Image from various components as described above, use
928 \fBukify\fR(1)\&.
929 .SH "SEE ALSO"
930 .PP
931 \fBsystemd-boot\fR(7), \fBsystemd.exec\fR(5), \fBsystemd-creds\fR(1), \fBsystemd-sysext\fR(8), \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[6]\d\s+2, \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[5]\d\s+2, \fBukify\fR(1), \fBsystemd-measure\fR(1), \m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[7]\d\s+2
932 .SH "NOTES"
933 .IP " 1." 4
934 specification
935 .RS 4
936 \%https://learn.microsoft.com/en-us/windows-hardware/drivers/install/specifying-hardware-ids-for-a-computer
937 .RE
938 .IP " 2." 4
939 SBAT
940 .RS 4
941 \%https://github.com/rhboot/shim/blob/main/SBAT.md
942 .RE
943 .IP " 3." 4
944 UKI specification
945 .RS 4
946 \%https://uapi-group.org/specifications/specs/unified_kernel_image/
947 .RE
948 .IP " 4." 4
949 Automatic Boot Assessment
950 .RS 4
951 \%https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
952 .RE
953 .IP " 5." 4
954 Boot Loader Interface
955 .RS 4
956 \%https://systemd.io/BOOT_LOADER_INTERFACE
957 .RE
958 .IP " 6." 4
959 Boot Loader Specification
960 .RS 4
961 \%https://uapi-group.org/specifications/specs/boot_loader_specification
962 .RE
963 .IP " 7." 4
964 TPM2 PCR Measurements Made by systemd
965 .RS 4
966 \%https://systemd.io/TPM2_PCR_MEASUREMENTS
967 .RE