From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Mon, 28 Jul 2025 12:57:09 +0000 (+0200)
Subject: man/systemd-boot: describe which keys use EFI variables
X-Git-Tag: v258-rc2~50^2~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7a800a66561490d12483053e28c57deae6bedcd4;p=thirdparty%2Fsystemd.git

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.
---

diff --git a/man/loader.conf.xml b/man/loader.conf.xml
index 3bd85971648..1d441654f81 100644
--- 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 34829688121..14e5cd6f960 100644
--- 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>
@@ -465,13 +475,13 @@
         <term><varname>LoaderEntrySysFail</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>