Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-STUB" "7" "" "systemd 261~rc3" "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 .RS 4
57 \fIESP\fR/loader/extensions/*\&.raw
58 .RE
59 .RS 4
60 \fIESP\fR/loader/extensions/*\&.sysext\&.raw
61 .RE
62 .RS 4
63 \fIESP\fR/loader/extensions/*\&.confext\&.raw
64 .RE
65 .SH "DESCRIPTION"
66 .PP
67 \fBsystemd\-stub\fR
68 (stored in per\-architecture files
69 linuxx64\&.efi\&.stub,
70 linuxia32\&.efi\&.stub,
71 linuxaa64\&.efi\&.stub
72 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\&.
73 .PP
74 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:
75 .sp
76 .RS 4
77 .ie n \{\
78 \h'-04'\(bu\h'+03'\c
79 .\}
80 .el \{\
81 .sp -1
82 .IP \(bu 2.3
83 .\}
84 A
85 "\&.linux"
86 section with the ELF Linux kernel image\&. This section is required\&.
87 .RE
88 .sp
89 .RS 4
90 .ie n \{\
91 \h'-04'\(bu\h'+03'\c
92 .\}
93 .el \{\
94 .sp -1
95 .IP \(bu 2.3
96 .\}
97 An optional
98 "\&.osrel"
99 section with OS release information, i\&.e\&. the contents of the
100 \fBos-release\fR(5)
101 file of the OS the kernel belongs to\&.
102 .RE
103 .sp
104 .RS 4
105 .ie n \{\
106 \h'-04'\(bu\h'+03'\c
107 .\}
108 .el \{\
109 .sp -1
110 .IP \(bu 2.3
111 .\}
112 An optional
113 "\&.cmdline"
114 section with the kernel command line to pass to the invoked kernel\&.
115 .RE
116 .sp
117 .RS 4
118 .ie n \{\
119 \h'-04'\(bu\h'+03'\c
120 .\}
121 .el \{\
122 .sp -1
123 .IP \(bu 2.3
124 .\}
125 An optional
126 "\&.initrd"
127 section with the initrd\&.
128 .RE
129 .sp
130 .RS 4
131 .ie n \{\
132 \h'-04'\(bu\h'+03'\c
133 .\}
134 .el \{\
135 .sp -1
136 .IP \(bu 2.3
137 .\}
138 An optional
139 "\&.ucode"
140 section with an initrd containing microcode, to be handed to the kernel before any other initrd\&. This initrd must not be compressed\&.
141 .RE
142 .sp
143 .RS 4
144 .ie n \{\
145 \h'-04'\(bu\h'+03'\c
146 .\}
147 .el \{\
148 .sp -1
149 .IP \(bu 2.3
150 .\}
151 An optional
152 "\&.splash"
153 section with an image (in the Windows
154 \&.BMP
155 format) to show on screen before invoking the kernel\&.
156 .RE
157 .sp
158 .RS 4
159 .ie n \{\
160 \h'-04'\(bu\h'+03'\c
161 .\}
162 .el \{\
163 .sp -1
164 .IP \(bu 2.3
165 .\}
166 An optional
167 "\&.dtb"
168 section with a compiled binary DeviceTree\&.
169 .RE
170 .sp
171 .RS 4
172 .ie n \{\
173 \h'-04'\(bu\h'+03'\c
174 .\}
175 .el \{\
176 .sp -1
177 .IP \(bu 2.3
178 .\}
179 Zero or more
180 "\&.dtbauto"
181 sections\&.
182 \fBsystemd\-stub\fR
183 will always use the first matching one\&. The match is performed by taking the first DeviceTree\*(Aqs
184 "compatible"
185 string supplied by the firmware in configuration tables and comparing it with the first
186 "compatible"
187 string from each of the
188 "\&.dtbauto"
189 sections\&. If the firmware does not provide a DeviceTree, the match is done using the
190 "\&.hwids"
191 section instead\&. After selecting a
192 "\&.hwids"
193 section (see the description below), the
194 "compatible"
195 string from that section will be used to perform the same matching procedure\&. If a match is found, that
196 "\&.dtbauto"
197 section will be loaded and will override
198 "\&.dtb"
199 if present\&.
200 .RE
201 .sp
202 .RS 4
203 .ie n \{\
204 \h'-04'\(bu\h'+03'\c
205 .\}
206 .el \{\
207 .sp -1
208 .IP \(bu 2.3
209 .\}
210 Zero or more
211 "\&.efifw"
212 sections for the firmware image\&. It works in many ways similar to
213 "\&.dtbauto"
214 sections\&.
215 \fBsystemd\-stub\fR
216 will always use the first matching one\&. The match is performed by first selecting the most appropriate entry in the
217 "\&.hwids"
218 section based on the hardware IDs supplied by SMBIOS (see below)\&. If a suitable entry is found, the
219 "fwid"
220 string from that entry will be used to perform the matching procedure for firmware blobs in
221 "\&.efifw"
222 section\&. The first matching firmware will be loaded\&.
223 .RE
224 .sp
225 .RS 4
226 .ie n \{\
227 \h'-04'\(bu\h'+03'\c
228 .\}
229 .el \{\
230 .sp -1
231 .IP \(bu 2.3
232 .\}
233 Zero or more
234 "\&.hwids"
235 sections with hardware IDs of the machines to match DeviceTrees\&.
236 \fBsystemd\-stub\fR
237 will use the SMBIOS data to calculate hardware IDs of the machine (as per
238 \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
239 "\&.hwids"
240 sections\&. The first matching section will be used\&.
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 "\&.uname"
253 section with the kernel version information, i\&.e\&. the output of
254 \fBuname \-r\fR
255 for the kernel included in the
256 "\&.linux"
257 section\&.
258 .RE
259 .sp
260 .RS 4
261 .ie n \{\
262 \h'-04'\(bu\h'+03'\c
263 .\}
264 .el \{\
265 .sp -1
266 .IP \(bu 2.3
267 .\}
268 An optional
269 "\&.sbat"
270 section with
271 \m[blue]\fBSBAT\fR\m[]\&\s-2\u[2]\d\s+2
272 revocation metadata\&.
273 .RE
274 .sp
275 .RS 4
276 .ie n \{\
277 \h'-04'\(bu\h'+03'\c
278 .\}
279 .el \{\
280 .sp -1
281 .IP \(bu 2.3
282 .\}
283 An optional
284 "\&.pcrsig"
285 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\&.
286 .RE
287 .sp
288 .RS 4
289 .ie n \{\
290 \h'-04'\(bu\h'+03'\c
291 .\}
292 .el \{\
293 .sp -1
294 .IP \(bu 2.3
295 .\}
296 An optional
297 "\&.pcrpkey"
298 section with a public key in the PEM format matching the signature data in the
299 "\&.pcrsig"
300 section\&.
301 .RE
302 .PP
303 In a basic UKI, the sections listed above appear at most once, with the exception of
304 "\&.dtbauto"
305 and
306 "\&.hwids"
307 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
308 "\&.profile"
309 is defined to be used as the separator between sets of sections\&. The
310 "\&.profile"
311 section itself may contain meta\-information about the section, and follows a similar structure as the contents of the
312 "\&.osrel"
313 section\&. For further details about multi\-profile UKIs, see below\&.
314 .PP
315 If UEFI SecureBoot is enabled and the
316 "\&.cmdline"
317 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)\&.
318 .PP
319 If a DeviceTree is embedded in the
320 "\&.dtb"
321 section, it replaces an existing DeviceTree in the corresponding EFI configuration table\&.
322 \fBsystemd\-stub\fR
323 will ask the firmware via the
324 "EFI_DT_FIXUP_PROTOCOL"
325 for hardware specific fixups to the DeviceTree\&.
326 .PP
327 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
328 "\&.pcrsig"
329 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\&.
330 .PP
331 If non\-zero, the selected numeric profile is measured into PCR 12\&.
332 .PP
333 When
334 "\&.pcrsig"
335 and/or
336 "\&.pcrpkey"
337 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
338 /\&.extra/tpm2\-pcr\-signature\&.json
339 and
340 /\&.extra/tpm2\-pcr\-public\-key\&.pem
341 files\&. Typically, a
342 \fBtmpfiles.d\fR(5)
343 line then ensures they are copied into
344 /run/systemd/tpm2\-pcr\-signature\&.json
345 and
346 /run/systemd/tpm2\-pcr\-public\-key\&.pem
347 where they remain accessible even after the system transitions out of the initrd environment into the host file system\&. Tools such
348 \[email protected]\fR(8),
349 \fBsystemd-cryptenroll\fR(1)
350 and
351 \fBsystemd-creds\fR(1)
352 will automatically use files present under these paths to unlock protected resources (encrypted storage or credentials) or bind encryption to booted kernels\&.
353 .PP
354 For further details about the UKI concept, see the
355 \m[blue]\fBUAPI\&.5 UKI specification\fR\m[]\&\s-2\u[3]\d\s+2\&.
356 .SH "COMPANION FILES"
357 .PP
358 The
359 \fBsystemd\-stub\fR
360 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
361 \fBcpio\fR
362 initrd archives from them, and passes them to the kernel\&. Specifically:
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 For a kernel binary called
373 \fIfoo\fR\&.efi, it will look for files with the
374 \&.cred
375 suffix in a directory named
376 \fIfoo\fR\&.efi\&.extra\&.d/
377 next to it\&. If the kernel binary uses a counter for the purpose of
378 \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[4]\d\s+2, this counter will be ignored\&. For example,
379 \fIfoo\fR+3\-0\&.efi
380 will look in directory
381 \fIfoo\fR\&.efi\&.extra\&.d/\&. A
382 \fBcpio\fR
383 archive is generated from all files found that way, placing them in the
384 /\&.extra/credentials/
385 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
386 \fILoadCredentialEncrypted\fR
387 in the UEFI System Partition\&. See
388 \fBsystemd.exec\fR(5)
389 and
390 \fBsystemd-creds\fR(1)
391 for details on encrypted credentials\&. The generated
392 \fBcpio\fR
393 archive is measured into TPM PCR 12 (if a TPM is present)\&.
394 .RE
395 .sp
396 .RS 4
397 .ie n \{\
398 \h'-04'\(bu\h'+03'\c
399 .\}
400 .el \{\
401 .sp -1
402 .IP \(bu 2.3
403 .\}
404 Similarly, files
405 \fIfoo\fR\&.efi\&.extra\&.d/*\&.sysext\&.raw
406 are packed up in a
407 \fBcpio\fR
408 archive and placed in the
409 /\&.extra/sysext/
410 directory in the initrd file hierarchy\&. This is supposed to be used to pass additional UKI\-specific system extension images to the initrd\&. See
411 \fBsystemd-sysext\fR(8)
412 for details on system extension images\&. The generated
413 \fBcpio\fR
414 archive containing these system extension images is measured into TPM PCR 13 (if a TPM is present)\&.
415 .RE
416 .sp
417 .RS 4
418 .ie n \{\
419 \h'-04'\(bu\h'+03'\c
420 .\}
421 .el \{\
422 .sp -1
423 .IP \(bu 2.3
424 .\}
425 Similarly, files
426 /loader/extensions/*\&.sysext\&.raw
427 are packed up in a
428 \fBcpio\fR
429 archive and placed in the
430 /\&.extra/global_sysext/
431 directory in the initrd file hierarchy\&. This is supposed to be used to pass additional global system extension images to the initrd\&. See
432 \fBsystemd-sysext\fR(8)
433 for details on system extension images\&. The generated
434 \fBcpio\fR
435 archive containing these system extension images is measured into TPM PCR 13 (if a TPM is present)\&.
436 .RE
437 .sp
438 .RS 4
439 .ie n \{\
440 \h'-04'\(bu\h'+03'\c
441 .\}
442 .el \{\
443 .sp -1
444 .IP \(bu 2.3
445 .\}
446 Similarly, files
447 \fIfoo\fR\&.efi\&.extra\&.d/*\&.confext\&.raw
448 are packed up in a
449 \fBcpio\fR
450 archive and placed in the
451 /\&.extra/confext/
452 directory in the initrd file hierarchy\&. This is supposed to be used to pass additional UKI\-specific configuration extension images to the initrd\&. See
453 \fBsystemd-confext\fR(8)
454 for details on configuration extension images\&. The generated
455 \fBcpio\fR
456 archive containing these configuration extension images is measured into TPM PCR 12 (if a TPM is present)\&.
457 .RE
458 .sp
459 .RS 4
460 .ie n \{\
461 \h'-04'\(bu\h'+03'\c
462 .\}
463 .el \{\
464 .sp -1
465 .IP \(bu 2.3
466 .\}
467 Similarly, files
468 /loader/extensions/*\&.confext\&.raw
469 are packed up in a
470 \fBcpio\fR
471 archive and placed in the
472 /\&.extra/global_confext/
473 directory in the initrd file hierarchy\&. This is supposed to be used to pass additional global configuration extension images to the initrd\&. See
474 \fBsystemd-confext\fR(8)
475 for details on configuration extension images\&. The generated
476 \fBcpio\fR
477 archive containing these configuration extension images is measured into TPM PCR 12 (if a TPM is present)\&.
478 .RE
479 .sp
480 .RS 4
481 .ie n \{\
482 \h'-04'\(bu\h'+03'\c
483 .\}
484 .el \{\
485 .sp -1
486 .IP \(bu 2.3
487 .\}
488 Similarly, files
489 \fIfoo\fR\&.efi\&.extra\&.d/*\&.addon\&.efi
490 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"
491 section), or DeviceTree blobs ("\&.dtb"
492 section), additional initrds ("\&.initrd"
493 section), and microcode updates ("\&.ucode"
494 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\&.
495 .sp
496 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
497 "\&.uname"
498 section, the addon will be rejected if they do not match exactly\&. It is recommended to always add a
499 "\&.sbat"
500 section to all signed addons, so that they may be revoked with a SBAT policy update, without requiring blocklisting via DBX/MOKX\&. The
501 \fBukify\fR(1)
502 tool will add a SBAT policy by default if none is passed when building addons\&. For more information on SBAT see
503 \m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
504 .sp
505 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
506 /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\&.
507 .RE
508 .sp
509 .RS 4
510 .ie n \{\
511 \h'-04'\(bu\h'+03'\c
512 .\}
513 .el \{\
514 .sp -1
515 .IP \(bu 2.3
516 .\}
517 Files
518 /loader/credentials/*\&.cred
519 are packed up in a
520 \fBcpio\fR
521 archive and placed in the
522 /\&.extra/global_credentials/
523 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
524 \fBcpio\fR
525 archive is measured into TPM PCR 12 (if a TPM is present)\&.
526 .RE
527 .sp
528 .RS 4
529 .ie n \{\
530 \h'-04'\(bu\h'+03'\c
531 .\}
532 .el \{\
533 .sp -1
534 .IP \(bu 2.3
535 .\}
536 Additionally, files
537 /loader/addons/*\&.addon\&.efi
538 are loaded and verified as PE binaries, and
539 "\&.cmdline",
540 "\&.dtb",
541 "\&.initrd", and
542 "\&.ucode"
543 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\&.
544 .RE
545 .PP
546 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
547 \fBsystemd\-creds encrypt \-T\fR
548 (see
549 \fBsystemd-creds\fR(1)
550 for details); in case of the system extension images by using signed Verity images\&.
551 .PP
552 Note that earlier components of the boot process might register additional initrds, and thus additional "companion" resources such as system extensions, configuration extensions and credentials for consumption by the kernel and OS eventually booted\&. For example,
553 \fBsystemd-boot\fR(7)
554 does this for resources configured in UAPI\&.1 Type #1
555 "extra"
556 lines\&.
557 systemd\-stub
558 will combine any resources provided that way with the companion file resources it acquires itself\&.
559 .SH "MULTI\-PROFILE UKIS"
560 .PP
561 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
562 \fBsystemd-storagetm.service\fR(8))\&. Each profile would then use the same
563 "\&.linux"
564 and
565 "\&.initrd"
566 sections, but would have a separate
567 "\&.cmdline"
568 section\&. For example the latter two profiles would extend the regular kernel command line with
569 "systemd\&.unit=factory\-reset\&.target"
570 or
571 "rd\&.systemd\&.unit=storagetm\&.target"\&.
572 .PP
573 A single UKI may support multiple profiles by means of the special
574 "\&.profile"
575 PE section\&. This section acts as separator between the PE sections of the individual profiles\&.
576 "\&.profile"
577 PE sections hence may appear multiple times in a single UKI, and the other PE sections listed above may appear multiple times too, if
578 "\&.profile"
579 are used, but only once before the first
580 "\&.profile"
581 section, once between each subsequent pair, and once after the last appearance of
582 "\&.profile"\&. The sections listed before the first
583 "\&.profile"
584 are considered the "base" profile of the UKI\&. Each
585 "\&.profile"
586 section then introduces a new profile, which are numbered starting from zero\&. The PE sections following each
587 "\&.profile"
588 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\&.
589 .PP
590 A UKI that contains no
591 "\&.profile"
592 is consider equivalent to one that just contains a single
593 "\&.profile", as having only a single profile
594 "@0"\&.
595 .PP
596 Here\*(Aqs a simple example for a multi\-profile UKI\*(Aqs sections, inspired by the setup suggested above:
597 .sp
598 .it 1 an-trap
599 .nr an-no-space-flag 1
600 .nr an-break-flag 1
601 .br
602 .B Table\ \&1.\ \&Multi\-Profile UKI Example
603 .TS
604 allbox tab(:);
605 lB lB.
606 T{
607 Section
608 T}:T{
609 Profile
610 T}
611 .T&
612 l l
613 l ^
614 l ^
615 l ^
616 l l
617 l l
618 l ^
619 l l
620 l ^.
621 T{
622 "\&.linux"
623 T}:T{
624 Base profile
625 T}
626 T{
627 "\&.osrel"
628 T}:
629 T{
630 "\&.cmdline"
631 T}:
632 T{
633 "\&.initrd"
634 T}:
635 T{
636 "\&.profile"
637 T}:T{
638 Profile @0
639 T}
640 T{
641 "\&.profile"
642 T}:T{
643 Profile @1
644 T}
645 T{
646 "\&.cmdline"
647 T}:
648 T{
649 "\&.profile"
650 T}:T{
651 Profile @2
652 T}
653 T{
654 "\&.cmdline"
655 T}:
656 .TE
657 .sp 1
658 .PP
659 The section list above would define three profiles\&. The first four sections make up the base profile\&. A
660 "\&.profile"
661 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
662 "\&.profile"
663 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
664 "\&.cmdline"
665 could also moved behind the first
666 "\&.profile"
667 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\&.)
668 .PP
669 The profile to boot may be controlled via the UKI\*(Aqs own command line: if the first argument starts with
670 "@", 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\&.
671 .PP
672 A
673 "\&.profile"
674 section may contain meta\-information about the profile\&. It follows a similar format as
675 "\&.osrel"
676 (i\&.e\&. an environment\-variable\-assignment\-block\-like list of newline separated strings)\&. Currently two fields are defined:
677 "ID="
678 is supposed to carry a short identifying string that identifies the profile (e\&.g\&.
679 "ID=factory\-reset")\&.
680 "TITLE="
681 should contain a human\-readable string that may appear in the boot menu entry for this profile (e\&.g\&.
682 "TITLE=\*(AqFactory Reset this Device\*(Aq")\&.
683 .SH "TPM PCR NOTES"
684 .PP
685 Note that when a unified kernel using
686 \fBsystemd\-stub\fR
687 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\&.
688 .PP
689 Also note that when
690 \fBsystemd\-stub\fR
691 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,
692 \fBsystemd\-stub\fR
693 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
694 \fBsystemd\-stub\fR
695 is always smaller than or equal to the size on disk\&.
696 \fBukify\fR
697 automatically makes sure this is the case when building UKIs or addons\&.
698 .PP
699 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:
700 .sp
701 .it 1 an-trap
702 .nr an-no-space-flag 1
703 .nr an-break-flag 1
704 .br
705 .B Table\ \&2.\ \&OS Resource PCR Summary
706 .TS
707 allbox tab(:);
708 lB lB.
709 T{
710 OS Resource
711 T}:T{
712 Measurement PCR
713 T}
714 .T&
715 l l
716 l l
717 l l
718 l l
719 l l
720 l l
721 l l
722 l l
723 l l
724 l l
725 l l
726 l l
727 l l
728 l l.
729 T{
730 \fBsystemd\-stub\fR code (the entry point of the unified PE binary)
731 T}:T{
732 4
733 T}
734 T{
735 Core kernel code (embedded in unified PE binary)
736 T}:T{
737 4 + 11
738 T}
739 T{
740 OS release information (embedded in the unified PE binary)
741 T}:T{
742 4 + 11
743 T}
744 T{
745 Main initrd (embedded in unified PE binary)
746 T}:T{
747 4 + 9 + 11
748 T}
749 T{
750 Microcode initrd (embedded in unified PE binary)
751 T}:T{
752 4 + 9 + 11
753 T}
754 T{
755 Default kernel command line (embedded in unified PE binary)
756 T}:T{
757 4 + 11
758 T}
759 T{
760 Overridden kernel command line
761 T}:T{
762 12
763 T}
764 T{
765 Boot splash (embedded in the unified PE binary)
766 T}:T{
767 4 + 11
768 T}
769 T{
770 TPM2 PCR signature JSON (embedded in unified PE binary, synthesized into initrd)
771 T}:T{
772 4 + 9
773 T}
774 T{
775 TPM2 PCR PEM public key (embedded in unified PE binary, synthesized into initrd)
776 T}:T{
777 4 + 9 + 11
778 T}
779 T{
780 Credentials (synthesized initrd from companion files)
781 T}:T{
782 9 + 12
783 T}
784 T{
785 System Extensions (synthesized initrd from companion files)
786 T}:T{
787 9 + 13
788 T}
789 T{
790 Configuration Extensions (synthesized initrd from companion files)
791 T}:T{
792 9 + 12
793 T}
794 T{
795 Selected profile unless zero
796 T}:T{
797 12
798 T}
799 .TE
800 .sp 1
801 .SH "EFI VARIABLES"
802 .PP
803 The following EFI variables are defined, set and read by
804 \fBsystemd\-stub\fR, under the vendor UUID
805 "4a67b082\-0a4c\-41cf\-b6c7\-440b29bb8c4f", for communication between the boot stub and the OS:
806 .PP
807 \fILoaderDevicePartUUID\fR
808 .RS 4
809 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
810 \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\&.
811 \fBsystemd-gpt-auto-generator\fR(8)
812 uses this information to automatically find the disk booted from, in order to discover various other partitions on the same disk automatically\&.
813 .sp
814 Added in version 224\&.
815 .RE
816 .PP
817 \fILoaderFirmwareInfo\fR, \fILoaderFirmwareType\fR
818 .RS 4
819 Brief firmware information\&. Use
820 \fBbootctl\fR(1)
821 to view this data\&.
822 .sp
823 Added in version 250\&.
824 .RE
825 .PP
826 \fILoaderTpm2ActivePcrBanks\fR
827 .RS 4
828 Hexadecimal string representation of a bitmask with values defined by the TCG EFI Protocol Specification for TPM 2\&.0 as EFI_TCG2_BOOT_HASH_ALG_*\&. If no TPM2 support or no active banks were detected, will be set to
829 \fB0\fR\&. Set by the boot loader\&. Use
830 \fBsystemd-analyze\fR(1)
831 to view this data\&.
832 .sp
833 Added in version 258\&.
834 .RE
835 .PP
836 \fILoaderImageIdentifier\fR
837 .RS 4
838 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
839 \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
840 \fBbootctl\fR(1)
841 to view this data\&.
842 .sp
843 Added in version 237\&.
844 .RE
845 .PP
846 \fIStubDevicePartUUID\fR, \fIStubImageIdentifier\fR
847 .RS 4
848 Similar to
849 \fILoaderDevicePartUUID\fR
850 and
851 \fILoaderImageIdentifier\fR, but indicates the location of the unified kernel image EFI binary rather than the location of the boot loader binary, regardless of whether booted via a boot loader or not\&.
852 .sp
853 Added in version 257\&.
854 .RE
855 .PP
856 \fIStubDeviceURL\fR
857 .RS 4
858 If the kernel image has been invoked via network booting this variable contains the originating URL\&. This may be used to automatically acquire additional resources from the same source\&.
859 .sp
860 Added in version 258\&.
861 .RE
862 .PP
863 \fIStubInfo\fR
864 .RS 4
865 Brief stub information\&. Use
866 \fBbootctl\fR(1)
867 to view this data\&.
868 .sp
869 Added in version 250\&.
870 .RE
871 .PP
872 \fIStubPcrKernelImage\fR
873 .RS 4
874 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\&.
875 "11")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
876 .sp
877 Added in version 252\&.
878 .RE
879 .PP
880 \fIStubPcrKernelParameters\fR
881 .RS 4
882 The PCR register index the kernel command line and credentials are measured into, formatted as decimal ASCII string (e\&.g\&.
883 "12")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
884 .sp
885 Added in version 252\&.
886 .RE
887 .PP
888 \fIStubPcrInitRDSysExts\fR
889 .RS 4
890 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\&.
891 "13")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
892 .sp
893 Added in version 252\&.
894 .RE
895 .PP
896 \fIStubPcrInitRDConfExts\fR
897 .RS 4
898 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\&.
899 "12")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
900 .sp
901 Added in version 255\&.
902 .RE
903 .PP
904 \fIStubProfile\fR
905 .RS 4
906 The numeric index of the selected profile, without the
907 "@", formatted as decimal string\&. Set both on single\-profile and multi\-profile UKIs\&. (In the former case this variable will be set to
908 "0"
909 unconditionally\&.)
910 .sp
911 Added in version 257\&.
912 .RE
913 .PP
914 \fILoaderPcrSMBIOS\fR
915 .RS 4
916 The PCR register index select SMBIOS structures are measured into \(em type 1 (system information, with the volatile "Wake\-up Type" field zeroed out), type 2 (baseboard information) and type 11 (OEM strings)\&. Formatted as decimal ASCII string (e\&.g\&.
917 "1")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&.
918 \fBsystemd\-stub\fR
919 performs this measurement only if it has not already been done in the same boot (e\&.g\&. by the boot loader), as indicated by this variable being set already\&.
920 .sp
921 Added in version 261\&.
922 .RE
923 .PP
924 \fILoaderBootSecret\fR
925 .RS 4
926 A non\-volatile EFI variable only accessible from the pre\-boot environment (i\&.e\&. access from the OS is not permitted) that contains a per\-system secret\&. It is set automatically by
927 \fBsystemd\-stub\fR
928 if not present already\&. A secret derived from the value of this EFI variable is passed to the OS in
929 /\&.extra/boot\-secret, see below\&.
930 .sp
931 Added in version 261\&.
932 .RE
933 .PP
934 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
935 \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[5]\d\s+2\&.
936 .SH "INITRD RESOURCES"
937 .PP
938 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:
939 .PP
940 /
941 .RS 4
942 The main initrd from the
943 "\&.initrd"
944 PE section of the unified kernel image\&.
945 .sp
946 Added in version 252\&.
947 .RE
948 .PP
949 /\&.extra/credentials/*\&.cred
950 .RS 4
951 Credential files (suffix
952 "\&.cred") that are placed next to the unified kernel image (as described above) are copied into the
953 /\&.extra/credentials/
954 directory in the initrd execution environment\&.
955 .sp
956 Added in version 252\&.
957 .RE
958 .PP
959 /\&.extra/global_credentials/*\&.cred
960 .RS 4
961 Similarly, credential files in the
962 /loader/credentials/
963 directory in the file system the unified kernel image is placed in are copied into the
964 /\&.extra/global_credentials/
965 directory in the initrd execution environment\&.
966 .sp
967 Added in version 252\&.
968 .RE
969 .PP
970 /\&.extra/sysext/*\&.sysext\&.raw
971 .RS 4
972 System extension image files (suffix
973 "\&.sysext\&.raw") that are placed next to the unified kernel image (as described above) are copied into the
974 /\&.extra/sysext/
975 directory in the initrd execution environment\&.
976 .sp
977 Added in version 252\&.
978 .RE
979 .PP
980 /\&.extra/global_sysext/*\&.sysext\&.raw
981 .RS 4
982 Similarly, system extension image files (suffix
983 "\&.sysext\&.raw") that are placed in the
984 /loader/extensions/
985 directory in the file system the unified kernel image is placed in are copied into the
986 /\&.extra/global_sysext/
987 directory in the initrd execution environment\&.
988 .sp
989 Added in version 258\&.
990 .RE
991 .PP
992 /\&.extra/confext/*\&.confext\&.raw
993 .RS 4
994 Configuration extension image files (suffix
995 "\&.confext\&.raw") that are placed next to the unified kernel image (as described above) are copied into the
996 /\&.extra/confext/
997 directory in the initrd execution environment\&.
998 .sp
999 Added in version 255\&.
1000 .RE
1001 .PP
1002 /\&.extra/global_confext/*\&.confext\&.raw
1003 .RS 4
1004 Similarly, configuration extension image files (suffix
1005 "\&.confext\&.raw") that are placed in the
1006 /loader/extensions/
1007 directory in the file system the unified kernel image is placed in are copied into the
1008 /\&.extra/global_confext/
1009 directory in the initrd execution environment\&.
1010 .sp
1011 Added in version 258\&.
1012 .RE
1013 .PP
1014 /\&.extra/tpm2\-pcr\-signature\&.json
1015 .RS 4
1016 The TPM2 PCR signature JSON object included in the
1017 "\&.pcrsig"
1018 PE section of the unified kernel image is copied into the
1019 /\&.extra/tpm2\-pcr\-signature\&.json
1020 file in the initrd execution environment\&.
1021 .sp
1022 Added in version 252\&.
1023 .RE
1024 .PP
1025 /\&.extra/tpm2\-pcr\-public\-key\&.pem
1026 .RS 4
1027 The PEM public key included in the
1028 "\&.pcrpkey"
1029 PE section of the unified kernel image is copied into the
1030 /\&.extra/tpm2\-pcr\-public\-key\&.pem
1031 file in the initrd execution environment\&.
1032 .sp
1033 Added in version 252\&.
1034 .RE
1035 .PP
1036 /\&.extra/profile, /\&.extra/os\-release
1037 .RS 4
1038 The contents of the
1039 "\&.profile"
1040 and
1041 "\&.osrel"
1042 sections of the selected profile, if any\&.
1043 .sp
1044 Added in version 257\&.
1045 .RE
1046 .PP
1047 /\&.extra/boot\-secret
1048 .RS 4
1049 A 32 byte per\-system secret which is derived from a 32 byte secret stored in an EFI variable (\fILoaderBootSecret\fR, see above), which itself is only accessible to the pre\-boot environment\&. This may be used for various early\-boot cryptographic purposes, and OS file system access to it is restricted to root\&. The
1050 \fIIMAGE_ID=\fR/\fIID=\fR
1051 data from the
1052 "\&.osrel"
1053 is hashed into the secret, to ensure that different images get a distinct secret passed\&. Moreover, a randomized 32 byte value stored in the ESP in the
1054 "/loader/boot\-secret\-mixin"
1055 file is hashed in as well, ensuring that distinct disks will result in different boot secrets\&.
1056 .sp
1057 Note: this boot secret is ultimately protected only by firmware\-enforced access controls on the EFI variable\&. This is generally a much weaker protection than TPM\-based approaches have, and it is hence strongly recommended to use the TPM on systems that possess one\&. The boot secret is primarily intended to be a lower\-security fallback for cases where a TPM is not available\&.
1058 .sp
1059 Applications should never protect resources directly with this secret, but derive their own secret from it (by hashing it together with some application ID, in HMAC mode for example), in order not to accidentally leak the primary boot secret\&.
1060 .sp
1061 Note that the boot secret is only available if the pre\-boot environment had a suitable RNG source at the current boot or an earlier one\&. This source can be an initialized on\-disk random seed or the EFI RNG support, or both\&.
1062 .sp
1063 Added in version 261\&.
1064 .RE
1065 .PP
1066 Note that all these files are located in the
1067 "tmpfs"
1068 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
1069 \fBtmpfiles.d\fR(5)
1070 line\&. By default, this is done for the TPM2 PCR signature and public key files\&.
1071 .SH "SMBIOS TYPE 11 STRINGS"
1072 .PP
1073 \fBsystemd\-stub\fR
1074 can be configured using SMBIOS Type 11 strings\&. Applicable strings consist of a name, followed by
1075 "=", followed by the value\&. Unless
1076 \fBsystemd\-stub\fR
1077 detects it is running inside a confidential computing environment,
1078 \fBsystemd\-stub\fR
1079 will search the table for a string with a specific name, and if found, use its value\&. The following strings are read:
1080 .PP
1081 \fIio\&.systemd\&.stub\&.kernel\-cmdline\-extra\fR
1082 .RS 4
1083 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\&.
1084 .sp
1085 Added in version 254\&.
1086 .RE
1087 .PP
1088 \fIio\&.systemd\&.boot\&.loglevel\fR
1089 .RS 4
1090 If set, the value of this string is used as log level\&. Valid values (from most to least critical) are
1091 "emerg",
1092 "alert",
1093 "crit",
1094 "err",
1095 "warning",
1096 "notice",
1097 "info", and
1098 "debug"\&.
1099 .sp
1100 Added in version 261\&.
1101 .RE
1102 .SH "ASSEMBLING KERNEL IMAGES"
1103 .PP
1104 In order to assemble a bootable Unified Kernel Image from various components as described above, use
1105 \fBukify\fR(1)\&.
1106 .SH "SEE ALSO"
1107 .PP
1108 \fBsystemd-boot\fR(7), \fBsystemd.exec\fR(5), \fBsystemd-creds\fR(1), \fBsystemd-sysext\fR(8), \m[blue]\fBUAPI\&.1 Boot 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
1109 .SH "NOTES"
1110 .IP " 1." 4
1111 specification
1112 .RS 4
1113 \%https://learn.microsoft.com/en-us/windows-hardware/drivers/install/specifying-hardware-ids-for-a-computer
1114 .RE
1115 .IP " 2." 4
1116 SBAT
1117 .RS 4
1118 \%https://github.com/rhboot/shim/blob/main/SBAT.md
1119 .RE
1120 .IP " 3." 4
1121 UAPI.5 UKI specification
1122 .RS 4
1123 \%https://uapi-group.org/specifications/specs/unified_kernel_image/
1124 .RE
1125 .IP " 4." 4
1126 Automatic Boot Assessment
1127 .RS 4
1128 \%https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
1129 .RE
1130 .IP " 5." 4
1131 Boot Loader Interface
1132 .RS 4
1133 \%https://systemd.io/BOOT_LOADER_INTERFACE
1134 .RE
1135 .IP " 6." 4
1136 UAPI.1 Boot Loader Specification
1137 .RS 4
1138 \%https://uapi-group.org/specifications/specs/boot_loader_specification
1139 .RE
1140 .IP " 7." 4
1141 TPM2 PCR Measurements Made by systemd
1142 .RS 4
1143 \%https://systemd.io/TPM2_PCR_MEASUREMENTS
1144 .RE