X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsystemd-stub.xml;h=2724c57ef92688233b5da7838c36d8590ce5f8aa;hb=HEAD;hp=6e853336c224fec713b5960b4a4d5f839ae6f342;hpb=8add4a9801a207d47e36271e3708392d0697f54a;p=thirdparty%2Fsystemd.git diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml index 6e853336c22..2724c57ef92 100644 --- a/man/systemd-stub.xml +++ b/man/systemd-stub.xml @@ -1,6 +1,6 @@ + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - /usr/lib/systemd/boot/efi/linuxx64.efi.stub - /usr/lib/systemd/boot/efi/linuxia32.efi.stub - /usr/lib/systemd/boot/efi/linuxaa64.efi.stub - ESP/.../foo.efi.extra.d/*.addon.efi - ESP/.../foo.efi.extra.d/*.cred - ESP/.../foo.efi.extra.d/*.raw - ESP/loader/addons/*.addon.efi - ESP/loader/credentials/*.cred + + /usr/lib/systemd/boot/efi/linuxx64.efi.stub + /usr/lib/systemd/boot/efi/linuxia32.efi.stub + /usr/lib/systemd/boot/efi/linuxaa64.efi.stub + ESP/.../foo.efi.extra.d/*.addon.efi + ESP/.../foo.efi.extra.d/*.cred + ESP/.../foo.efi.extra.d/*.raw + ESP/.../foo.efi.extra.d/*.sysext.raw + ESP/.../foo.efi.extra.d/*.confext.raw + ESP/loader/addons/*.addon.efi + ESP/loader/credentials/*.cred + @@ -66,6 +70,9 @@ An .initrd section with the initrd. + A .ucode section with an initrd containing microcode, to be handed + to the kernel before any other initrd. This initrd must not be compressed. + A .splash section with an image (in the Windows .BMP format) to show on screen before invoking the kernel. @@ -85,7 +92,7 @@ specific key. A .pcrpkey section with a public key in the PEM format matching the - signature data in the the .pcrsig section. + signature data in the .pcrsig section. If UEFI SecureBoot is enabled and the .cmdline section is present in the executed @@ -151,14 +158,28 @@ details on encrypted credentials. The generated cpio archive is measured into TPM PCR 12 (if a TPM is present). - Similarly, files foo.efi.extra.d/*.raw - are packed up in a cpio archive and placed in the /.extra/sysext/ - directory in the initrd file hierarchy. This is supposed to be used to pass additional system extension - images to the initrd. See + Similarly, files + foo.efi.extra.d/*.sysext.raw are packed up in a + cpio archive and placed in the /.extra/sysext/ directory in the + initrd file hierarchy. This is supposed to be used to pass additional system extension images to the + initrd. See systemd-sysext8 for details on system extension images. The generated cpio archive containing these system extension images is measured into TPM PCR 13 (if a TPM is present). + + + Similarly, files + foo.efi.extra.d/*.confext.raw are packed up in a + cpio archive and placed in the /.extra/confext/ directory in + the initrd file hierarchy. This is supposed to be used to pass additional configuration extension + images to the initrd. See + systemd-confext8 for + details on configuration extension images. The generated cpio archive containing + these system extension images is measured into TPM PCR 12 (if a TPM is present). + Similarly, files foo.efi.extra.d/*.addon.efi are loaded and verified as PE binaries, and a .cmdline section is parsed from them. Addons are supposed to be @@ -167,7 +188,7 @@ configuration. In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim's DB or - Shim's MOK, and will be rejected otherwise. Additionally, if the both the addon and the UKI contain a a + Shim's MOK, and will be rejected otherwise. Additionally, if both the addon and the UKI contain a .uname section, the addon will be rejected if they do not match exactly. It is recommended to always add a .sbat section to all signed addons, so that they may be revoked with a SBAT policy update, without requiring blocklisting via DBX/MOKX. The @@ -215,10 +236,11 @@ core kernel, the embedded initrd and kernel command line (see above for a full list). Also note that the Linux kernel will measure all initrds it receives into TPM PCR 9. This means - every type of initrd will be measured two or three times: the initrd embedded in the kernel image will be - measured to PCR 4, PCR 9 and PCR 11; the initrd synthesized from credentials 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's summarize the OS resources and the PCRs they are measured to: + every type of initrd will 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's summarize the OS resources and the PCRs + they are measured to: OS Resource PCR Summary @@ -255,6 +277,11 @@ 4 + 9 + 11 + + Microcode initrd (embedded in unified PE binary) + 4 + 9 + 11 + + Default kernel command line (embedded in unified PE binary) 4 + 11 @@ -289,6 +316,11 @@ System Extensions (synthesized initrd from companion files) 9 + 13 + + + Configuration Extensions (synthesized initrd from companion files) + 9 + 12 +
@@ -369,13 +401,24 @@ StubPcrInitRDSysExts - The PCR register index the systemd 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. + 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. 13). This variable is set if a measurement was successfully completed, and remains unset otherwise. + + + StubPcrInitRDConfExts + + 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. + 12). This variable is set if a measurement was successfully completed, and remains + unset otherwise. + + + Note that some of the variables above may also be set by the boot loader. The stub will only set @@ -420,14 +463,23 @@ - /.extra/sysext/*.raw - System extension image files (suffix .raw) that are placed next to - the unified kernel image (as described above) are copied into the + /.extra/sysext/*.sysext.raw + System extension image files (suffix .sysext.raw) that are placed + next to the unified kernel image (as described above) are copied into the /.extra/sysext/ directory in the initrd execution environment. + + /.extra/confext/*.confext.raw + Configuration extension image files (suffix .confext.raw) that are + placed next to the unified kernel image (as described above) are copied into the + /.extra/confext/ directory in the initrd execution environment. + + + + /.extra/tpm2-pcr-signature.json The TPM2 PCR signature JSON object included in the .pcrsig PE @@ -459,7 +511,8 @@ SMBIOS Type 11 Strings systemd-stub can be configured using SMBIOS Type 11 strings. Applicable strings - consist of a name, followed by =, followed by the value. + consist of a name, followed by =, followed by the value. Unless + systemd-stub detects it is running inside a confidential computing environment, systemd-stub will search the table for a string with a specific name, and if found, use its value. The following strings are read: @@ -483,16 +536,16 @@ See Also - - systemd-boot7, - systemd.exec5, - systemd-creds1, - systemd-sysext8, - Boot Loader Specification, - Boot Loader Interface, - ukify1, - systemd-measure1, - TPM2 PCR Measurements Made by systemd - + + systemd-boot7 + systemd.exec5 + systemd-creds1 + systemd-sysext8 + Boot Loader Specification + Boot Loader Interface + ukify1 + systemd-measure1 + TPM2 PCR Measurements Made by systemd +