man/systemd-boot: describe which keys use EFI variables

Some keys have only a transient effect, e.g. 'e', but some have a persistent
effect, e.g. 'd'. This is important informations, but the reader might be
forgiven for not finding that at all obvious when reading the descriptions of
the keys.

Also, mention in loader.conf man page that the settings there might be overriden
by EFI variables. This is another thing that is important but not obvious.

(cherry picked from commit 7a800a66561490d12483053e28c57deae6bedcd4)

diff --git a/man/loader.conf.xml b/man/loader.conf.xml
index 6b34302ecd2bfa3c8f8dc2f1fc4566d57fd8f47a..6c450f71a311e6b5630f57de0eec301f78bbfc58 100644 (file)
--- a/man/loader.conf.xml
+++ b/man/loader.conf.xml
@@ -53,6 +53,12 @@
     Those files are described by the
     <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
     Specification</ulink>.</para>
+
+    <para>Note: the behaviour of <command>systemd-boot</command> is also influenced by EFI variables. Some of
+    the settings specified in this file can be overridden by those, for example the default boot menu entry
+    or the menu timeouts. See
+    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+    details.</para>
   </refsect1>
 
   <refsect1>

diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml
index 90a035fd557adbb70165b85ab00000bec9022e5d..83ef95008834921396cbd70b68808afeac69ec5a 100644 (file)
--- a/man/systemd-boot.xml
+++ b/man/systemd-boot.xml
@@ -149,6 +149,8 @@
         <term><keycap>d</keycap></term>
         <listitem><para>Make selected entry the default</para>
 
+        <para>An EFI variable is set to allow this setting to persist.</para>
+
         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
       </varlistentry>
 
@@ -164,6 +166,8 @@
         <term><keycap>t</keycap></term>
         <listitem><para>Increase the timeout before default entry is booted</para>
 
+        <para>An EFI variable is set to allow this setting to persist.</para>
+
         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
       </varlistentry>
 
@@ -172,6 +176,8 @@
         <term><keycap>T</keycap></term>
         <listitem><para>Decrease the timeout</para>
 
+        <para>An EFI variable is set to allow this setting to persist.</para>
+
         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
       </varlistentry>
 
@@ -179,6 +185,8 @@
         <term><keycap>r</keycap></term>
         <listitem><para>Change screen resolution, skipping any unsupported modes.</para>
 
+        <para>An EFI variable is set to allow this setting to persist.</para>
+
         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
       </varlistentry>
 
@@ -186,6 +194,8 @@
         <term><keycap>R</keycap></term>
         <listitem><para>Reset screen resolution to firmware or configuration file default.</para>
 
+        <para>An EFI variable is set to allow this setting to persist.</para>
+
         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
       </varlistentry>
 
@@ -389,9 +399,9 @@
   <refsect1>
     <title>EFI Variables</title>
 
-    <para>The following EFI variables are defined, set and read by <command>systemd-boot</command>, under the
-    vendor UUID <literal>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</literal>, for communication between the boot
-    loader and the OS:</para>
+    <para>The following EFI variables are defined, and may be set or read by <command>systemd-boot</command>
+    for communication between the boot loader and the OS. The vendor UUID
+    <literal>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</literal> is used in all cases.</para>
 
     <variablelist class='efi-variables'>
       <varlistentry>
@@ -454,13 +464,13 @@
         <term><varname>LoaderEntryDefault</varname></term>
         <term><varname>LoaderEntryOneShot</varname></term>
 
-        <listitem><para>The identifier of the default boot loader entry. Set primarily by the OS and read by the boot
+        <listitem><para>The identifier of the default boot loader entry. Can be set in the OS and the boot
         loader. <varname>LoaderEntryOneShot</varname> sets the default entry for the next boot only, while
-        <varname>LoaderEntryDefault</varname> sets it persistently for all future
-        boots. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
-        <option>set-default</option> and <option>set-oneshot</option> commands make use of these variables. The boot
-        loader modifies <varname>LoaderEntryDefault</varname> on request, when the <keycap>d</keycap> key is used, see
-        above.</para>
+        <varname>LoaderEntryDefault</varname> sets it persistently for all future boots.
+        <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+        <option>set-default</option> and <option>set-oneshot</option> commands make use of these variables.
+        The boot loader modifies <varname>LoaderEntryDefault</varname> on request, when the
+        <keycap>d</keycap> key is used, see above.</para>
 
         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
       </varlistentry>