From 57684a255400574084c446803f5ad0bba74c17b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 28 Jul 2025 14:32:03 +0200 Subject: [PATCH 1/6] bootctl: print location/status of loader.conf The usual pattern of using colors to distinguish the mount path (/efi/) and the rest is used. If the file cannot be read for reasons other than -ENOENT, the error message is highlighted. I considered a few places where to add this, but this section seems the most reaosonable. We already print the 'token' there, which is also part of the configuration. Boot Loader Entry Locations: ESP: /efi (/dev/disk/by-partuuid/31659406-5a17-46ec-8195-0dea1667db58) config: /efi//loader/loader.conf XBOOTLDR: /boot (/dev/disk/by-partuuid/4f8a8fe9-4b45-4070-9e9b-a681be51c902, $BOOT) token: fedora --- src/bootctl/bootctl-status.c | 11 +++++++++++ src/shared/bootspec.c | 1 + src/shared/bootspec.h | 2 ++ 3 files changed, 14 insertions(+) diff --git a/src/bootctl/bootctl-status.c b/src/bootctl/bootctl-status.c index d8609d8ffd..2c3208a471 100644 --- a/src/bootctl/bootctl-status.c +++ b/src/bootctl/bootctl-status.c @@ -83,6 +83,17 @@ static int status_entries( printf(", %s$BOOT%s", ansi_green(), ansi_normal()); printf(")"); + if (config->loader_conf_status != 0) { + assert(esp_path); + printf("\n config: %s%s/%s%s", + ansi_grey(), esp_path, ansi_normal(), "/loader/loader.conf"); + if (config->loader_conf_status < 0) + printf(": %s%s%s", + config->loader_conf_status == -ENOENT ? ansi_grey() : ansi_highlight_yellow(), + STRERROR(config->loader_conf_status), + ansi_normal()); + } + if (xbootldr_path) { printf("\n XBOOTLDR: %s (", xbootldr_path); if (!sd_id128_is_null(xbootldr_partition_uuid)) diff --git a/src/shared/bootspec.c b/src/shared/bootspec.c index b0196f996d..a0bbb7c17d 100644 --- a/src/shared/bootspec.c +++ b/src/shared/bootspec.c @@ -533,6 +533,7 @@ static int boot_loader_read_conf_path(BootConfig *config, const char *root, cons assert(path); r = chase_and_fopen_unlocked(path, root, CHASE_PREFIX_ROOT|CHASE_PROHIBIT_SYMLINKS, "re", &full, &f); + config->loader_conf_status = r < 0 ? r : true; if (r == -ENOENT) return 0; if (r < 0) diff --git a/src/shared/bootspec.h b/src/shared/bootspec.h index 1ccdf20606..0edf6e084e 100644 --- a/src/shared/bootspec.h +++ b/src/shared/bootspec.h @@ -67,6 +67,8 @@ typedef struct BootEntry { } typedef struct BootConfig { + int loader_conf_status; /* 0 → before loading, 1 → loaded, negative → error. */ + char *default_pattern; char *entry_oneshot; From a83de23353aa9e41d59cf198f1c8fd5d56c1e97b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 28 Jul 2025 14:38:39 +0200 Subject: [PATCH 2/6] man: fix confusion in loader.conf For some reason, the man page for loader.conf also mentioned type#1 entries in passing. Except for using the same file extension, those files are in a completely different format and with a different purpose. This mixup was first introduced in f37d3835828c45b3a92ed12d9a6a30796c0a4a27, was then reported in #10923, which was closed by cbae79b8d07327051c1e1f438f7086ab634b93f8, but that didn't fix the actual issue. Really fixes #10923. While at it, simplify and improve the wording a bit. --- man/loader.conf.xml | 47 +++++++++++++++++++++------------------------ 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/man/loader.conf.xml b/man/loader.conf.xml index f14b77b537..293f59adfd 100644 --- a/man/loader.conf.xml +++ b/man/loader.conf.xml @@ -21,47 +21,44 @@ - ESP/loader/loader.conf, - ESP/loader/entries/*.conf - XBOOTLDR/loader/entries/*.conf - + ESP/loader/loader.conf Description - systemd-boot7 will - read ESP/loader/loader.conf, and any files with the - .conf extension under - ESP/loader/entries/ on the EFI system partition (ESP), - and XBOOTLDR/loader/entries/ on the extended boot loader - partition (XBOOTLDR) as defined by Boot Loader - Specification. - + systemd-boot7 reads + ESP/loader/loader.conf. This file configures whether the + menu is shown and for how long, the font, audible beep, types of menu entries to show, the default + choice, and some aspects of Secure Boot enrollment and firmware handling. See the list of available + options below. - 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. # may be used to start a comment line. Empty and comment lines are ignored. The - files use UTF-8 encoding. + The file uses UTF-8 encoding and consists of series of lines separated by "line feed" (i.e. ASCII + code 10). Lines that are empty or start with the comment sign (#) are ignored. Other + lines consist of an option name, followed by whitespace, and the option value. + Boolean arguments may be written as - yes/y/true/t/on/1 or + yes/y/true/t/on/1 + or no/n/false/f/off/0. + + Note: systemd-boot will also read boot loader entry files, + type #1 (ESP/loader/entries/*.conf and + XBOOTLDR/loader/entries/*.conf) + and type #2 (ESP/EFI/Linux/*.uki + and XBOOTLDR/EFI/Linux/*.uki). + Those files are described by the + Boot Loader + Specification. Options - The configuration options supported by - ESP/loader/entries/*.conf and - XBOOTLDR/loader/entries/*.conf files are defined as part - of the Boot Loader - Specification. - - The following configuration are supported by the loader.conf configuration - file: + The following configuration are supported in loader.conf: From ec7e81ae3dfc4f8dedfefea6f6eccef30981c8b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 28 Jul 2025 14:38:56 +0200 Subject: [PATCH 3/6] man/loader.conf: wrap some very wrong lines --- man/loader.conf.xml | 16 ++++++++++------ man/systemd-boot.xml | 6 +++--- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/man/loader.conf.xml b/man/loader.conf.xml index 293f59adfd..3bd8597164 100644 --- a/man/loader.conf.xml +++ b/man/loader.conf.xml @@ -251,8 +251,9 @@ beep - 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. + 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. @@ -399,8 +400,8 @@ sbvarsign --attr "${attr}" --key KEK.key --cert KEK.pem --output db.auth db db.e Caveat: This feature is experimental, and is likely to be changed (or removed in its current form) in a future version of systemd. - Work around BitLocker requiring a recovery key when the boot loader was - updated (disabled by default). + Work around BitLocker requiring a recovery key when the boot loader was updated (disabled by + default). 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 BootNext EFI variable @@ -439,8 +440,11 @@ sbvarsign --attr "${attr}" --key KEK.key --cert KEK.pem --output db.auth db db.e - Perform the reboot if and only if boot counting is enabled for this entry and the tries left counter wasn't already at 0. - This is the default, as it is typically a safe option, that ensures a clean measurement log on each boot attempt, but also does not risk an unbounded reboot loop. + Perform the reboot if and only if boot counting is enabled for this entry and the tries + left counter wasn't already at 0. + + This is the default, as it is typically a safe option, that ensures a clean measurement log + on each boot attempt, but also does not risk an unbounded reboot loop. diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 52aa582c30..3482968812 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -396,9 +396,9 @@ LoaderBootCountPath - If boot counting is enabled, contains the path to the file in whose name the boot counters are - encoded. Set by the boot - loader. systemd-bless-boot.service8 + If boot counting is enabled, contains the path to the file in whose name the boot + counters are encoded. Set by the boot loader. + systemd-bless-boot.service8 uses this information to mark a boot as successful as determined by the successful activation of the boot-complete.target target unit. From 7a800a66561490d12483053e28c57deae6bedcd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 28 Jul 2025 14:57:09 +0200 Subject: [PATCH 4/6] 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. --- man/loader.conf.xml | 6 ++++++ man/systemd-boot.xml | 28 +++++++++++++++++++--------- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/man/loader.conf.xml b/man/loader.conf.xml index 3bd8597164..1d441654f8 100644 --- a/man/loader.conf.xml +++ b/man/loader.conf.xml @@ -53,6 +53,12 @@ Those files are described by the Boot Loader Specification. + + Note: the behaviour of systemd-boot 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 + systemd-boot7 for + details. diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 3482968812..14e5cd6f96 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -149,6 +149,8 @@ d Make selected entry the default + An EFI variable is set to allow this setting to persist. + @@ -164,6 +166,8 @@ t Increase the timeout before default entry is booted + An EFI variable is set to allow this setting to persist. + @@ -172,6 +176,8 @@ T Decrease the timeout + An EFI variable is set to allow this setting to persist. + @@ -179,6 +185,8 @@ r Change screen resolution, skipping any unsupported modes. + An EFI variable is set to allow this setting to persist. + @@ -186,6 +194,8 @@ R Reset screen resolution to firmware or configuration file default. + An EFI variable is set to allow this setting to persist. + @@ -389,9 +399,9 @@ EFI Variables - The following EFI variables are defined, set and read by systemd-boot, under the - vendor UUID 4a67b082-0a4c-41cf-b6c7-440b29bb8c4f, for communication between the boot - loader and the OS: + The following EFI variables are defined, and may be set or read by systemd-boot + for communication between the boot loader and the OS. The vendor UUID + 4a67b082-0a4c-41cf-b6c7-440b29bb8c4f is used in all cases. @@ -465,13 +475,13 @@ LoaderEntrySysFail LoaderEntryOneShot - The identifier of the default boot loader entry. Set primarily by the OS and read by the boot + The identifier of the default boot loader entry. Can be set in the OS and the boot loader. LoaderEntryOneShot sets the default entry for the next boot only, while - LoaderEntryDefault sets it persistently for all future - boots. bootctl1's - and commands make use of these variables. The boot - loader modifies LoaderEntryDefault on request, when the d key is used, see - above. + LoaderEntryDefault sets it persistently for all future boots. + bootctl1's + and commands make use of these variables. + The boot loader modifies LoaderEntryDefault on request, when the + d key is used, see above. From 509f701ab3b1294e6935561a2d212db48fccd7c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 28 Jul 2025 15:14:57 +0200 Subject: [PATCH 5/6] man/systemd-boot: recommend holding space by default https://github.com/systemd/systemd/pull/15509/files#r2234113960 complains that the advice is still not clear enough. systemd-boot itself says "Menu hidden. Hold down key at bootup to show menu." so let's do the same and tell users to hold down space as the first option. This should work fine for 99% of people. Then invert the following advice to try repeated pressing as the alternative option. Also, fix the advice about --boot-loader-menu=. The whole para is about getting the menu to show, so 0 is not a good value. Follow-up for https://github.com/systemd/systemd/pull/15509. --- man/systemd-boot.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 14e5cd6f96..b01299143c 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -290,15 +290,15 @@ The boot menu is shown when a non-zero menu timeout has been configured. If the menu timeout has - been set to zero, it is sufficient to press any key — before the boot loader initializes — to bring up - the boot menu, except for the keys listed immediately above as they directly boot into the selected boot - menu item. Note that depending on the firmware implementation the time window where key presses are - accepted before the boot loader initializes might be short. If the window is missed, reboot and try - again, possibly pressing a suitable key (e.g. the space bar) continuously; on most systems it should be - possible to hit the time window after a few attempts. To avoid this problem, consider setting a non-zero - timeout, thus showing the boot menu unconditionally. Some desktop environments might offer an option to - directly boot into the boot menu, to avoid the problem altogether. Alternatively, use the command line - systemctl reboot --boot-loader-menu=0 from the shell. + been set to zero, hold down a key (space is recommended) before the boot loader + initializes to bring up the boot menu. Note that depending on the firmware implementation the time window + where key presses are accepted before the boot loader initializes might be short. If the window is + missed, reboot and try again, possibly repeatedly pressing a suitable key; on most systems it should be + possible to hit the time window after a few attempts. Keys other than the space bar may be used, except + for the keys listed above. If showing the menu on demand doesn't work well, consider setting a non-zero + timeout to show the boot menu unconditionally. Some desktop environments might offer an option to boot + directly into the boot menu, which also avoids the problem altogether. Alternatively, use the command + line systemctl reboot --boot-loader-menu= with a non-zero value from the shell. In the editor, most keys simply insert themselves, but the following keys may be used to perform additional actions: From b68b9f8f7f5b7590f4369d24371af7a18a8702a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 29 Jul 2025 11:33:29 +0200 Subject: [PATCH 6/6] docs/ENVIRONMENT: fix typo and adjust grammar --- docs/ENVIRONMENT.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index ab3ac4895b..d423d9cd9c 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -353,12 +353,13 @@ All tools: default is not appropriate for a given system. Defaults to `5`, accepts positive integers. -* `$SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_INTERVAL_SEC` — can be set to override the mount - units interval rate limit for parsing `/proc/self/mountinfo`. Similar to - `$SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST`, the interval limit maybe adjusted when - the default is not appropriate for a given system. The default value is 1 and the - default application time unit is second, and the time unit can beoverriden as usual - by specifying it explicitly, see the systemd.time(7) man page. +* `$SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_INTERVAL_SEC` — can be set to override the + mount units interval rate limit for parsing `/proc/self/mountinfo`. Similar + to `$SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST`, the interval limit maybe + adjusted when the default is not appropriate for a given system. The default + value is 1, the default application time unit is second, and the time unit + can be overridden as usual by specifying it explicitly, see the + systemd.time(7) man page. `systemd-remount-fs`: