Adding upstream version 252.22.upstream/252.22upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 359 insertions, 0 deletions

diff --git a/man/loader.conf.xml b/man/loader.conf.xml
new file mode 100644
index 0000000..6dfb6c0
--- /dev/null
+++ b/man/loader.conf.xml
@@ -0,0 +1,359 @@
+<?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">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="loader.conf" conditional='HAVE_GNU_EFI'
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+  <refentryinfo>
+    <title>loader.conf</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>loader.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>loader.conf</refname>
+    <refpurpose>Configuration file for systemd-boot</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>,
+    <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename>
+    <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/*.conf</filename>
+    </para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> will
+    read <filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>, and any files with the
+    <literal>.conf</literal> extension under
+    <filename><replaceable>ESP</replaceable>/loader/entries/</filename> on the EFI system partition (ESP),
+    and <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/</filename> on the extended boot loader
+    partition (XBOOTLDR) as defined by <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
+    Specification</ulink>.
+    </para>
+
+    <para>Each of these configuration files must consist of series of newline (i.e. ASCII code 10) separated
+    lines, each consisting of an option name, followed by whitespace, and the option
+    value. <literal>#</literal> may be used to start a comment line. Empty and comment lines are ignored. The
+    files use UTF-8 encoding.</para>
+
+    <para>Boolean arguments may be written as
+    <literal>yes</literal>/<literal>y</literal>/<literal>true</literal>/<literal>t</literal>/<literal>on</literal>/<literal>1</literal> or
+    <literal>no</literal>/<literal>n</literal>/<literal>false</literal>/<literal>f</literal>/<literal>off</literal>/<literal>0</literal>.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>The configuration options supported by
+    <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename> and
+    <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/*.conf</filename> files are defined as part
+    of the <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
+    Specification</ulink>.</para>
+
+    <para>The following configuration are supported by the <filename>loader.conf</filename> configuration
+    file:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>default</term>
+
+        <listitem><para>A glob pattern to select the default entry. The default entry
+        may be changed in the boot menu itself, in which case the name of the
+        selected entry will be stored as an EFI variable, overriding this option.
+        </para>
+
+        <para>If set to <literal>@saved</literal> the chosen entry will be saved as an EFI variable
+        on every boot and automatically selected the next time the boot loader starts.</para>
+
+        <table>
+          <title>Automatically detected entries will use the following names:</title>
+
+          <tgroup cols='2'>
+            <colspec colname='name' />
+            <colspec colname='expl' />
+            <thead>
+              <row>
+                <entry>Name</entry>
+                <entry>Description</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry>auto-efi-default</entry>
+                <entry>EFI Default Loader</entry>
+              </row>
+              <row>
+                <entry>auto-efi-shell</entry>
+                <entry>EFI Shell</entry>
+              </row>
+              <row>
+                <entry>auto-osx</entry>
+                <entry>macOS</entry>
+              </row>
+              <row>
+                <entry>auto-reboot-to-firmware-setup</entry>
+                <entry>Reboot Into Firmware Interface</entry>
+              </row>
+              <row>
+                <entry>auto-windows</entry>
+                <entry>Windows Boot Manager</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>
+
+        <para>Supported glob wildcard patterns are <literal>?</literal>, <literal>*</literal>, and
+        <literal>[…]</literal> (including ranges). Note that these patterns use the same syntax as
+        <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+        but do not support all features. In particular, set negation and named character classes are not
+        supported. The matching is done case-insensitively on the entry ID (as shown by <command>bootctl
+        list</command>).</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>timeout</term>
+
+        <listitem><para>How long the boot menu should be shown before the default
+        entry is booted, in seconds. This may be changed in the boot menu itself and
+        will be stored as an EFI variable in that case, overriding this option.
+        </para>
+
+        <para>If set to <literal>menu-hidden</literal> or <literal>0</literal> (the default) no menu
+        is shown and the default entry will be booted immediately. The menu can be shown
+        by pressing and holding a key before systemd-boot is launched. Setting this to
+        <literal>menu-force</literal> disables the timeout while always showing the menu.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>console-mode</term>
+
+        <listitem><para>This option configures the resolution of the console. Takes a
+        number or one of the special values listed below. The following values may be
+        used:</para>
+
+        <variablelist>
+          <varlistentry>
+            <term>0</term>
+            <listitem>
+              <para>Standard UEFI 80x25 mode</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>1</term>
+            <listitem>
+              <para>80x50 mode, not supported by all devices</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>2</term>
+            <listitem>
+              <para>the first non-standard mode provided by the device
+              firmware, if any</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>auto</term>
+            <listitem>
+              <para>Pick a suitable mode automatically using heuristics</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>max</term>
+            <listitem>
+              <para>Pick the highest-numbered available mode</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>keep</term>
+            <listitem>
+              <para>Keep the mode selected by firmware (the default)</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>editor</term>
+
+        <listitem><para>Takes a boolean argument. Enable (the default) or disable the
+        editor. The editor should be disabled if the machine can be accessed by
+        unauthorized persons.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>auto-entries</term>
+
+        <listitem><para>Takes a boolean argument. Enable (the default) or disable
+        entries for other boot entries found on the boot partition. In particular,
+        this may be useful when loader entries are created to show replacement
+        descriptions for those entries.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>auto-firmware</term>
+
+        <listitem><para>A boolean controlling the presence of the "Reboot into firmware" entry
+        (enabled by default). If this is disabled, the firmware interface may still be reached
+        by using the <keycap>f</keycap> key.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>beep</term>
+
+        <listitem><para>Takes a boolean argument. If timeout enabled beep every second, otherwise beep n times when n-th entry in boot menu is selected (default disabled).
+        Currently, only x86 is supported, where it uses the PC speaker.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>secure-boot-enroll</term>
+
+        <listitem><para>Danger: this feature might soft-brick your device if used improperly.</para>
+
+        <para>Takes one of <literal>off</literal>, <literal>manual</literal> or <literal>force</literal>.
+        Controls the enrollment of secure boot keys. If set to <literal>off</literal>, no action whatsoever
+        is taken. If set to <literal>manual</literal> (the default) and the UEFI firmware is in setup-mode
+        then entries to manually enroll Secure Boot variables are created in the boot menu. If set to
+        <literal>force</literal>, in addition, if a directory named <filename>/loader/keys/auto/</filename>
+        exists on the ESP then the keys in that directory are enrolled automatically.</para>
+
+        <para>The different sets of variables can be set up under <filename>/loader/keys/<replaceable>NAME</replaceable></filename>
+        where <replaceable>NAME</replaceable> is the name that is going to be used as the name of the entry.
+        This allows one to ship multiple sets of Secure Boot variables and choose which one to enroll at runtime.</para>
+
+        <para>Supported secure boot variables are one database for authorized images, one key exchange key (KEK)
+        and one platform key (PK). For more information, refer to the <ulink url="https://uefi.org/specifications">UEFI specification</ulink>,
+        under Secure Boot and Driver Signing. Another resource that describe the interplay of the different variables is the
+        <ulink url="https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/uefi_secure_boot">
+        EDK2 documentation</ulink>.</para>
+
+        <para>A complete set of UEFI variable includes <filename>db.auth</filename>, <filename>KEK.auth</filename>
+        and <filename>PK.auth</filename>. Note that these files need to be authenticated UEFI variables. See
+        below for an example of how to generate them from regular X.509 keys.</para>
+
+        <programlisting>uuid=$(systemd-id128 new --uuid)
+for key in PK KEK db; do
+  openssl req -new -x509 -subj "/CN=${key}/" -keyout "${key}.key" -out "${key}.crt"
+  openssl x509 -outform DER -in "${key}.crt" -out "${key}.cer"
+  cert-to-efi-sig-list -g "${uuid}" "${key}.crt" "${key}.esl"
+done
+
+for key in MicWinProPCA2011_2011-10-19.crt MicCorUEFCA2011_2011-06-27.crt MicCorKEKCA2011_2011-06-24.crt; do
+  curl "https://www.microsoft.com/pkiops/certs/${key}" --output "${key}"
+  sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output "${key%crt}esl" "${key}"
+done
+
+# Optionally add Microsoft Windows Production CA 2011 (needed to boot into Windows).
+cat MicWinProPCA2011_2011-10-19.esl >> db.esl
+
+# Optionally add Microsoft Corporation UEFI CA 2011 (for firmware drivers / option ROMs
+# and third-party boot loaders (including shim). This is highly recommended on real
+# hardware as not including this may soft-brick your device (see next paragraph).
+cat MicCorUEFCA2011_2011-06-27.esl >> db.esl
+
+# Optionally add Microsoft Corporation KEK CA 2011. Recommended if either of the
+# Microsoft keys is used as the official UEFI revocation database is signed with this
+# key. The revocation database can be updated with <citerefentry project='man-pages'><refentrytitle>fwupdmgr</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+cat MicCorKEKCA2011_2011-06-24.esl >> KEK.esl
+
+sign-efi-sig-list -c PK.crt -k PK.key PK PK.esl PK.auth
+sign-efi-sig-list -c PK.crt -k PK.key KEK KEK.esl KEK.auth
+sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth
+        </programlisting>
+
+        <para>This feature is considered dangerous because even if all the required files are signed with the
+        keys being loaded, some files necessary for the system to function properly still won't be. This
+        is especially the case with Option ROMs (e.g. for storage controllers or graphics cards). See
+        <ulink url="https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom">Secure Boot and Option ROMs</ulink>
+        for more details.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>reboot-for-bitlocker</term>
+
+        <listitem><para>Caveat: This feature is experimental, and is likely to be changed (or removed in its
+        current form) in a future version of systemd.</para>
+
+        <para>Work around BitLocker requiring a recovery key when the boot loader was
+        updated (disabled by default).</para>
+
+        <para>Try to detect BitLocker encrypted drives along with an active TPM. If both are found
+        and Windows Boot Manager is selected in the boot menu, set the <literal>BootNext</literal>
+        EFI variable and restart the system. The firmware will then start Windows Boot Manager
+        directly, leaving the TPM PCRs in expected states so that Windows can unseal the encryption
+        key. This allows systemd-boot to be updated without having to provide the recovery key for
+        BitLocker drive unlocking.</para>
+
+        <para>Note that the PCRs that Windows uses can be configured with the
+        <literal>Configure TPM platform validation profile for native UEFI firmware configurations</literal>
+        group policy under <literal>Computer Configuration\Administrative Templates\Windows Components\BitLocker Drive Encryption</literal>.
+        When secure boot is enabled, changing this to PCRs <literal>0,2,7,11</literal> should be safe.
+        The TPM key protector needs to be removed and then added back for the PCRs on an already
+        encrypted drive to change. If PCR 4 is not measured, this setting can be disabled to speed
+        up booting into Windows.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>random-seed-mode</term>
+
+        <listitem><para>Takes one of <literal>off</literal>, <literal>with-system-token</literal> and
+        <literal>always</literal>. If <literal>off</literal> no random seed data is read off the ESP, nor
+        passed to the OS. If <literal>with-system-token</literal> (the default)
+        <command>systemd-boot</command> will read a random seed from the ESP (from the file
+        <filename>/loader/random-seed</filename>) only if the <varname>LoaderSystemToken</varname> EFI
+        variable is set, and then derive the random seed to pass to the OS from the combination. If
+        <literal>always</literal> the boot loader will do so even if <varname>LoaderSystemToken</varname> is
+        not set. This mode is useful in environments where protection against OS image reuse is not a
+        concern, and the random seed shall be used even with no further setup in place. Use <command>bootctl
+        random-seed</command> to initialize both the random seed file in the ESP and the system token EFI
+        variable.</para>
+
+        <para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further
+        information.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
+
+    <programlisting># /boot/efi/loader/loader.conf
+timeout 0
+default 01234567890abcdef1234567890abdf0-*
+editor no
+    </programlisting>
+
+    <para>The menu will not be shown by default (the menu can still be shown by
+    pressing and holding a key during boot). One of the entries with files with a
+    name starting with <literal>01234567890abcdef1234567890abdf0-</literal> will be
+    selected by default. If more than one entry matches, the one with the highest
+    priority will be selected (generally the one with the highest version number).
+    The editor will be disabled, so it is not possible to alter the kernel command
+    line.</para>
+  </refsect1>
+
+  <refsect1>
+      <title>See Also</title>
+      <para>
+        <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      </para>
+  </refsect1>
+</refentry>