diff options
Diffstat (limited to 'man/systemd-stub.xml')
| -rw-r--r-- | man/systemd-stub.xml | 125 |
1 files changed, 89 insertions, 36 deletions
diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml index 6e85333..2724c57 100644 --- a/man/systemd-stub.xml +++ b/man/systemd-stub.xml @@ -1,6 +1,6 @@ <?xml version='1.0'?> <!--*-nxml-*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> <refentry id="systemd-stub" conditional='ENABLE_BOOTLOADER' @@ -25,14 +25,18 @@ </refnamediv> <refsynopsisdiv> - <para><filename>/usr/lib/systemd/boot/efi/linuxx64.efi.stub</filename></para> - <para><filename>/usr/lib/systemd/boot/efi/linuxia32.efi.stub</filename></para> - <para><filename>/usr/lib/systemd/boot/efi/linuxaa64.efi.stub</filename></para> - <para><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.addon.efi</filename></para> - <para><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.cred</filename></para> - <para><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.raw</filename></para> - <para><filename><replaceable>ESP</replaceable>/loader/addons/*.addon.efi</filename></para> - <para><filename><replaceable>ESP</replaceable>/loader/credentials/*.cred</filename></para> + <para><simplelist> + <member><filename>/usr/lib/systemd/boot/efi/linuxx64.efi.stub</filename></member> + <member><filename>/usr/lib/systemd/boot/efi/linuxia32.efi.stub</filename></member> + <member><filename>/usr/lib/systemd/boot/efi/linuxaa64.efi.stub</filename></member> + <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.addon.efi</filename></member> + <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.cred</filename></member> + <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.raw</filename></member> + <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.sysext.raw</filename></member> + <member><filename><replaceable>ESP</replaceable>/.../<replaceable>foo</replaceable>.efi.extra.d/*.confext.raw</filename></member> + <member><filename><replaceable>ESP</replaceable>/loader/addons/*.addon.efi</filename></member> + <member><filename><replaceable>ESP</replaceable>/loader/credentials/*.cred</filename></member> + </simplelist></para> </refsynopsisdiv> <refsect1> @@ -66,6 +70,9 @@ <listitem><para>An <literal>.initrd</literal> section with the initrd.</para></listitem> + <listitem><para>A <literal>.ucode</literal> section with an initrd containing microcode, to be handed + to the kernel before any other initrd. This initrd must not be compressed.</para></listitem> + <listitem><para>A <literal>.splash</literal> section with an image (in the Windows <filename>.BMP</filename> format) to show on screen before invoking the kernel.</para></listitem> @@ -85,7 +92,7 @@ specific key.</para></listitem> <listitem><para>A <literal>.pcrpkey</literal> section with a public key in the PEM format matching the - signature data in the the <literal>.pcrsig</literal> section.</para></listitem> + signature data in the <literal>.pcrsig</literal> section.</para></listitem> </itemizedlist> <para>If UEFI SecureBoot is enabled and the <literal>.cmdline</literal> section is present in the executed @@ -151,14 +158,28 @@ details on encrypted credentials. The generated <command>cpio</command> archive is measured into TPM PCR 12 (if a TPM is present).</para></listitem> - <listitem><para>Similarly, files <filename><replaceable>foo</replaceable>.efi.extra.d/*.raw</filename> - are packed up in a <command>cpio</command> archive and placed in the <filename>/.extra/sysext/</filename> - directory in the initrd file hierarchy. This is supposed to be used to pass additional system extension - images to the initrd. See + <listitem><para>Similarly, files + <filename><replaceable>foo</replaceable>.efi.extra.d/*.sysext.raw</filename> are packed up in a + <command>cpio</command> archive and placed in the <filename>/.extra/sysext/</filename> directory in the + initrd file hierarchy. This is supposed to be used to pass additional system extension images to the + initrd. See <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details on system extension images. The generated <command>cpio</command> archive containing these system extension images is measured into TPM PCR 13 (if a TPM is present).</para></listitem> + <!-- Note: the actual suffix we look for for sysexts is just *.raw (not *.sysext.raw), for + compatibility reasons with old versions. But we want people to name their system extensions + properly, hence we document the *.sysext.raw suffix only. --> + + <listitem><para>Similarly, files + <filename><replaceable>foo</replaceable>.efi.extra.d/*.confext.raw</filename> are packed up in a + <command>cpio</command> archive and placed in the <filename>/.extra/confext/</filename> directory in + the initrd file hierarchy. This is supposed to be used to pass additional configuration extension + images to the initrd. See + <citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry> for + details on configuration extension images. The generated <command>cpio</command> archive containing + these system extension images is measured into TPM PCR 12 (if a TPM is present).</para></listitem> + <listitem><para>Similarly, files <filename><replaceable>foo</replaceable>.efi.extra.d/*.addon.efi</filename> are loaded and verified as PE binaries, and a <literal>.cmdline</literal> section is parsed from them. Addons are supposed to be @@ -167,7 +188,7 @@ configuration.</para> <para>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 <literal>.uname</literal> section, the addon will be rejected if they do not match exactly. It is recommended to always add a <literal>.sbat</literal> 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).</para> <para>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:</para> + 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:</para> <table> <title>OS Resource PCR Summary</title> @@ -256,6 +278,11 @@ </row> <row> + <entry>Microcode initrd (embedded in unified PE binary)</entry> + <entry>4 + 9 + 11</entry> + </row> + + <row> <entry>Default kernel command line (embedded in unified PE binary)</entry> <entry>4 + 11</entry> </row> @@ -289,6 +316,11 @@ <entry>System Extensions (synthesized initrd from companion files)</entry> <entry>9 + 13</entry> </row> + + <row> + <entry>Configuration Extensions (synthesized initrd from companion files)</entry> + <entry>9 + 12</entry> + </row> </tbody> </tgroup> </table> @@ -369,13 +401,24 @@ <varlistentry> <term><varname>StubPcrInitRDSysExts</varname></term> - <listitem><para>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. + <listitem><para>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. <literal>13</literal>). This variable is set if a measurement was successfully completed, and remains unset otherwise.</para> <xi:include href="version-info.xml" xpointer="v252"/></listitem> </varlistentry> + + <varlistentry> + <term><varname>StubPcrInitRDConfExts</varname></term> + + <listitem><para>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. + <literal>12</literal>). This variable is set if a measurement was successfully completed, and remains + unset otherwise.</para> + + <xi:include href="version-info.xml" xpointer="v255"/></listitem> + </varlistentry> </variablelist> <para>Note that some of the variables above may also be set by the boot loader. The stub will only set @@ -420,15 +463,24 @@ </varlistentry> <varlistentry> - <term><filename>/.extra/sysext/*.raw</filename></term> - <listitem><para>System extension image files (suffix <literal>.raw</literal>) that are placed next to - the unified kernel image (as described above) are copied into the + <term><filename>/.extra/sysext/*.sysext.raw</filename></term> + <listitem><para>System extension image files (suffix <literal>.sysext.raw</literal>) that are placed + next to the unified kernel image (as described above) are copied into the <filename>/.extra/sysext/</filename> directory in the initrd execution environment.</para> <xi:include href="version-info.xml" xpointer="v252"/></listitem> </varlistentry> <varlistentry> + <term><filename>/.extra/confext/*.confext.raw</filename></term> + <listitem><para>Configuration extension image files (suffix <literal>.confext.raw</literal>) that are + placed next to the unified kernel image (as described above) are copied into the + <filename>/.extra/confext/</filename> directory in the initrd execution environment.</para> + + <xi:include href="version-info.xml" xpointer="v255"/></listitem> + </varlistentry> + + <varlistentry> <term><filename>/.extra/tpm2-pcr-signature.json</filename></term> <listitem><para>The TPM2 PCR signature JSON object included in the <literal>.pcrsig</literal> PE section of the unified kernel image is copied into the @@ -459,7 +511,8 @@ <title>SMBIOS Type 11 Strings</title> <para><command>systemd-stub</command> can be configured using SMBIOS Type 11 strings. Applicable strings - consist of a name, followed by <literal>=</literal>, followed by the value. + consist of a name, followed by <literal>=</literal>, followed by the value. Unless + <command>systemd-stub</command> detects it is running inside a confidential computing environment, <command>systemd-stub</command> will search the table for a string with a specific name, and if found, use its value. The following strings are read:</para> @@ -483,16 +536,16 @@ <refsect1> <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>, - <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>, - <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink> - </para> + <para><simplelist type="inline"> + <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member> + <member><ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink></member> + <member><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink></member> + </simplelist></para> </refsect1> </refentry> |