diff --git a/TODO b/TODO index d4dbe7baa7..b1bc038ef5 100644 --- a/TODO +++ b/TODO @@ -1392,9 +1392,6 @@ Features: * chase(): take inspiration from path_extract_filename() and return O_DIRECTORY if input path contains trailing slash. -* document in boot loader spec that symlinks in XBOOTLDR/ESP are not OK even if - non-VFAT fs is used. - * measure credentials picked up from SMBIOS to some suitable PCR * measure GPT and LUKS headers somewhere when we use them (i.e. in @@ -2319,9 +2316,11 @@ Features: ConditionConfigSearchPathNotEmpty= or different syntax? See the discussion starting at https://github.com/systemd/systemd/pull/15109#issuecomment-607740136. -* BootLoaderSpec: Define a way how an installer can figure out whether a BLS +* BootLoaderSpec: define a way how an installer can figure out whether a BLS compliant boot loader is installed. +* BootLoaderSpec: document @saved pseudo-entry, update mention in BLI + * think about requeuing jobs when daemon-reload is issued? use case: the initrd issues a reload after fstab from the host is accessible and we might want to requeue the mounts local-fs acquired through diff --git a/docs/BOOT_LOADER_INTERFACE.md b/docs/BOOT_LOADER_INTERFACE.md index 82dd534a65..37ec443d9d 100644 --- a/docs/BOOT_LOADER_INTERFACE.md +++ b/docs/BOOT_LOADER_INTERFACE.md @@ -7,84 +7,97 @@ SPDX-License-Identifier: LGPL-2.1-or-later # The Boot Loader Interface -systemd can interface with the boot loader to receive performance data and -other information, and pass control information. This is only supported on EFI -systems. Data is transferred between the boot loader and systemd in EFI -variables. All EFI variables use the vendor UUID -`4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`. +systemd can interface with the boot loader +to receive performance data and other information, +and pass control information. +This is only supported on EFI systems. +Data is transferred between the boot loader and systemd in EFI variables. +All EFI variables use the vendor UUID `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`. +Variables will be listed below using the Linux efivarfs naming, +`-`. -* The EFI Variable `LoaderTimeInitUSec` contains the timestamp in microseconds - when the loader was initialized. This value is the time spent in the firmware - for initialization, it is formatted as numeric, NUL-terminated, decimal - string, in UTF-16. +* The EFI Variable `LoaderTimeInitUSec-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the timestamp in microseconds when the loader was initialized. + This value is the time spent in the firmware for initialization. + It is formatted as numeric, NUL-terminated, decimal string, in UTF-16. -* The EFI Variable `LoaderTimeExecUSec` contains the timestamp in microseconds - when the loader finished its work and is about to execute the kernel. The - time spent in the loader is the difference between `LoaderTimeExecUSec` and - `LoaderTimeInitUSec`. This value is formatted the same way as - `LoaderTimeInitUSec`. +* The EFI Variable `LoaderTimeExecUSec-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the timestamp in microseconds when the loader finished its work and is about to execute the kernel. + The time spent in the loader is the difference between `LoaderTimeExecUSec` and `LoaderTimeInitUSec`. + This value is formatted the same way as `LoaderTimeInitUSec`. -* The EFI variable `LoaderDevicePartUUID` contains the partition GUID of the - ESP the boot loader was run from formatted as NUL-terminated UTF16 string, in - normal GUID syntax. +* The EFI variable `LoaderDevicePartUUID-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the partition GUID of the ESP the boot loader was run from + formatted as NUL-terminated UTF16 string, in normal GUID syntax. -* The EFI variable `LoaderConfigTimeout` contains the boot menu timeout - currently in use. It may be modified both by the boot loader and by the - host. The value should be formatted as numeric, NUL-terminated, decimal - string, in UTF-16. The time is specified in seconds. In addition some - non-numeric string values are also accepted. A value of `menu-force` - will disable the timeout and show the menu indefinitely. If set to `0` or - `menu-hidden` the default entry is booted immediately without showing a menu. - Unless a value of `menu-disabled` is set, the boot loader should provide a - way to interrupt this by for example listening for key presses for a brief - moment before booting. +* The EFI variable `LoaderConfigTimeout-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the boot menu timeout currently in use. + It may be modified both by the boot loader and by the host. + The value should be formatted as numeric, NUL-terminated, decimal string, in UTF-16. + The time is specified in seconds. + In addition some non-numeric string values are also accepted. + A value of `menu-force` will disable the timeout and show the menu indefinitely. + If set to `0` or `menu-hidden` the default entry is booted immediately without showing a menu. + Unless a value of `menu-disabled` is set, + the boot loader should provide a way to interrupt this + by for example listening for key presses for a brief moment before booting. -* Similarly, the EFI variable `LoaderConfigTimeoutOneShot` contains a boot menu - timeout for a single following boot. It is set by the OS in order to request - display of the boot menu on the following boot. When set overrides - `LoaderConfigTimeout`. It is removed automatically after being read by the - boot loader, to ensure it only takes effect a single time. This value is - formatted the same way as `LoaderConfigTimeout`. If set to `0` the boot menu - timeout is turned off, and the menu is shown indefinitely. +* Similarly, the EFI variable `LoaderConfigTimeoutOneShot-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains a boot menu timeout for a single following boot. + It is set by the OS in order to request display of the boot menu on the following boot. + When set overrides `LoaderConfigTimeout`. + It is removed automatically after being read by the boot loader, + to ensure it only takes effect a single time. + This value is formatted the same way as `LoaderConfigTimeout`. + If set to `0` the boot menu timeout is turned off, + and the menu is shown indefinitely. -* The EFI variable `LoaderEntries` may contain a series of boot loader entry - identifiers, one after the other, each individually NUL terminated. This may - be used to let the OS know which boot menu entries were discovered by the - boot loader. A boot loader entry identifier should be a short, non-empty - alphanumeric string (possibly containing `-`, too). The list should be in the - order the entries are shown on screen during boot. See below regarding the - recommended vocabulary for boot loader entry identifiers. +* The EFI variable `LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + may contain a series of boot loader entry identifiers, + one after the other, each individually NUL terminated. + This may be used to let the OS know which boot menu entries were discovered by the boot loader. + A boot loader entry identifier should be a short, non-empty alphanumeric string + (possibly containing `-`, too). + The list should be in the order the entries are shown on screen during boot. + See below regarding the recommended vocabulary for boot loader entry identifiers. -* The EFI variable `LoaderEntryDefault` contains the default boot loader entry - to use. It contains a NUL-terminated boot loader entry identifier. +* The EFI variable `LoaderEntryDefault-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the default boot loader entry to use. + It contains a NUL-terminated boot loader entry identifier. -* The EFI variable `LoaderEntrySysFail` specifies the boot loader entry to be - used in case of a system failure. System failure (SysFail) boot entries can - optionally modify the automatic selection order in the event of a failure, - such as a boot firmware update failure with the failure status recorded in - the EFI system table. If a system failure occurs and `LoaderEntrySysFail` is - set, systemd-boot will use this boot entry, and store the actual SysFail - reason in the `LoaderSysFailReason` EFI variable. +* The EFI variable `LoaderEntrySysFail-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + specifies the boot loader entry to be used in case of a system failure. + System failure (SysFail) boot entries + can optionally modify the automatic selection order in the event of a failure, + such as a boot firmware update failure with the failure status recorded in the EFI system table. + If a system failure occurs and `LoaderEntrySysFail` is set, + systemd-boot will use this boot entry, + and store the actual SysFail reason in the `LoaderSysFailReason` EFI variable. -* The EFI variable `LoaderSysFailReason` contains the system failure reason. +* The EFI variable `LoaderSysFailReason-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the system failure reason. This variable is used in cooperation with `LoaderEntrySysFail` boot entry. If system failure doesn't occur, `LoaderSysFailReason` is not set. -* Similarly, the EFI variable `LoaderEntryOneShot` contains the default boot - loader entry to use for a single following boot. It is set by the OS in order - to request booting into a specific menu entry on the following boot. When set - overrides `LoaderEntryDefault`. It is removed automatically after being read - by the boot loader, to ensure it only takes effect a single time. This value - is formatted the same way as `LoaderEntryDefault`. +* Similarly, the EFI variable `LoaderEntryOneShot-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the default boot loader entry to use for a single following boot. + It is set by the OS + in order to request booting into a specific menu entry on the following boot. + When set overrides `LoaderEntryDefault`. + It is removed automatically after being read by the boot loader, + to ensure it only takes effect a single time. + This value is formatted the same way as `LoaderEntryDefault`. -* The EFI variable `LoaderEntrySelected` contains the boot loader entry - identifier that was booted. It is set by the boot loader and read by - the OS in order to identify which entry has been used for the current boot. +* The EFI variable `LoaderEntrySelected-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the boot loader entry identifier that was booted. + It is set by the boot loader and read by the OS + in order to identify which entry has been used for the current boot. -* The EFI variable `LoaderFeatures` contains a 64-bit unsigned integer with a - number of flags bits that are set by the boot loader and passed to the OS and - indicate the features the boot loader supports. Specifically, the following - bits are defined: +* The EFI variable `LoaderFeatures-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains a 64-bit unsigned integer with a number of flags bits + that are set by the boot loader and passed to the OS + and indicate the features the boot loader supports. + Specifically, the following bits are defined: * `1 << 0` → The boot loader honours `LoaderConfigTimeout` when set. * `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set. @@ -93,29 +106,53 @@ variables. All EFI variables use the vendor UUID * `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](/AUTOMATIC_BOOT_ASSESSMENT). * `1 << 5` → The boot loader supports looking for boot menu entries in the Extended Boot Loader Partition. * `1 << 6` → The boot loader supports passing a random seed to the OS. + * `1 << 7` → The boot loader supports loading of drop-in drivers from the `/EFI/systemd/drivers/` directory on the ESP, + see [`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html). + * `1 << 8` → The boot loader supports the `sort-key` field defined by the + [Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). + * `1 << 9` → The boot loader supports the `@saved` pseudo-entry + * `1 << 10` → The boot loader supports the `devicetree` field defined by the + [Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). + * `1 << 11` → The boot loader support automatic enrollment of SecureBoot keys, + see [`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html). + * `1 << 12` → The boot loader will set EFI variable `ShimRetainProtocol-605dab50-e046-4300-abb6-3dd810dd8b23` + for `shim` to make its protocol available to the booted binary. * `1 << 13` → The boot loader honours `menu-disabled` option when set. + * `1 << 14` → The boot loader supports multi-profile Unified Kernel Images (UKIs) + * `1 << 15` → The boot loader sets the `LoaderDeviceURL` variable when appropriate. + * `1 << 16` → The boot loader supports the `uki` field defined by the + [Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). + * `1 << 17` → The boot loader supports the `uki-url` field defined by the + [Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). + * `1 << 18` → The boot loader reports active TPM2 PCR banks in the + EFI variable `LoaderTpm2ActivePcrBanks-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`. -* The EFI variable `LoaderSystemToken` contains binary random data, - persistently set by the OS installer. Boot loaders that support passing - random seeds to the OS should use this data and combine it with the random - seed file read from the ESP. By combining this random data with the random - seed read off the disk before generating a seed to pass to the OS and a new - seed to store in the ESP the boot loader can protect itself from situations - where "golden" OS images that include a random seed are replicated and used - on multiple systems. Since the EFI variable storage is usually independent - (i.e. in physical NVRAM) of the ESP file system storage, and only the latter - is part of "golden" OS images, this ensures that different systems still come - up with different random seeds. Note that the `LoaderSystemToken` is - generally only written once, by the OS installer, and is usually not touched - after that. +* The EFI variable `LoaderSystemToken-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains binary random data, + persistently set by the OS installer. + Boot loaders that support passing random seeds to the OS + should use this data and combine it with the random seed file read from the ESP. + By combining this random data with the random seed read off the disk + before generating a seed to pass to the OS and a new seed to store in the ESP + the boot loader can protect itself from situations where + "golden" OS images that include a random seed are replicated and used on multiple systems. + Since the EFI variable storage is usually independent + (i.e. in physical NVRAM) of the ESP file system storage, + and only the latter is part of "golden" OS images, + this ensures that different systems still come up with different random seeds. + Note that the `LoaderSystemToken` is generally only written once, + by the OS installer, + and is usually not touched after that. -* The EFI variable `LoaderDeviceURL` contains the URL the boot loader was - downloaded from, in UTF-16 format. Only set in case of network boots. +* The EFI variable `LoaderDeviceURL-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains the URL the boot loader was downloaded from, + in UTF-16 format. + Only set in case of network boots. -* The EFI variable `LoaderTpm2ActivePcrBanks` contains a hexadecimal string - representation of a bitmask with values defined by the TCG EFI Protocol - Specification for TPM 2.0 as EFI_TCG2_BOOT_HASH_ALG_*. If no TPM2 support or - no active banks were detected, will be set to `0`. +* The EFI variable `LoaderTpm2ActivePcrBanks-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` + contains a hexadecimal string representation of a bitmask with values defined by + the TCG EFI ProtocolSpecification for TPM 2.0 as `EFI_TCG2_BOOT_HASH_ALG_*`. + If no TPM2 support or no active banks were detected, will be set to `0`. If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze` will include them in its boot-time analysis. If `LoaderDevicePartUUID` is set, @@ -128,12 +165,11 @@ variables. ## Boot Loader Entry Identifiers -While boot loader entries may be named relatively freely, it's highly -recommended to follow the following rules when picking identifiers for the -entries, so that programs (and users) can derive basic context and meaning from -the identifiers as passed in `LoaderEntries`, `LoaderEntryDefault`, -`LoaderEntryOneShot`, `LoaderEntrySelected`, and possibly show nicely localized -names for them in UIs. +While boot loader entries may be named relatively freely, +it's highly recommended to follow the following rules when picking identifiers for the entries, +so that programs (and users) can derive basic context and meaning from the identifiers +as passed in `LoaderEntries`, `LoaderEntryDefault`, `LoaderEntryOneShot`, `LoaderEntrySelected`, +and possibly show nicely localized names for them in UIs. 1. When boot loader entries are defined through the [BOOT.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/) @@ -141,29 +177,30 @@ names for them in UIs. but with the `.conf` (Type #1 snippets) or `.efi` (Type #2 images) suffix removed. -2. Entries automatically discovered by the boot loader (as opposed to being - configured in configuration files) should generally have an identifier - prefixed with `auto-`. +2. Entries automatically discovered by the boot loader + (as opposed to being configured in configuration files) + should generally have an identifier prefixed with `auto-`. -3. Boot menu entries referring to Microsoft Windows installations should either - use the identifier `windows` or use the `windows-` prefix for the - identifier. If a menu entry is automatically discovered, it should be - prefixed with `auto-`, see above (Example: this means an automatically - discovered Windows installation might have the identifier `auto-windows` or - `auto-windows-10` or so.). +3. Boot menu entries referring to Microsoft Windows installations + should either use the identifier `windows` + or use the `windows-` prefix for the identifier. + If a menu entry is automatically discovered, + it should be prefixed with `auto-`, see above. + (Example: this means an automatically discovered Windows installation + might have the identifier `auto-windows` or `auto-windows-10` or so.). -4. Similarly, boot menu entries referring to Apple macOS installations should - use the identifier `osx` or one that is prefixed with `osx-`. If such an - entry is automatically discovered by the boot loader use `auto-osx` as - identifier, or `auto-osx-` as prefix for the identifier, see above. +4. Similarly, boot menu entries referring to Apple macOS installations + should use the identifier `osx` or one that is prefixed with `osx-`. + If such an entry is automatically discovered by the boot loader use `auto-osx` as identifier, + or `auto-osx-` as prefix for the identifier, see above. -5. If a boot menu entry encapsulates the EFI shell program, it should use the - identifier `efi-shell` (or when automatically discovered: `auto-efi-shell`, - see above). +5. If a boot menu entry encapsulates the EFI shell program, + it should use the identifier `efi-shell` + (or when automatically discovered: `auto-efi-shell`, see above). 6. If a boot menu entry encapsulates a reboot into EFI firmware setup feature, - it should use the identifier `reboot-to-firmware-setup` (or - `auto-reboot-to-firmware-setup` in case it is automatically discovered). + it should use the identifier `reboot-to-firmware-setup` + (or `auto-reboot-to-firmware-setup` in case it is automatically discovered). ## Links diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 65be783df7..78ef02768f 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -57,7 +57,7 @@ A Reboot Into Firmware Interface option, if supported by the UEFI firmware. - Secure Boot variables enrollment if the UEFI firmware is in setup-mode and files are provided + Secure Boot variable enrollment if the UEFI firmware is in setup mode and files are provided on the ESP. @@ -97,7 +97,7 @@ entropy pool initialization, providing a full entropy pool during early boot. The boot manager allows for Secure Boot variables to be enrolled if the UEFI firmware is - in setup-mode. Additionally, variables can be automatically enrolled if configured. + in setup mode. Additionally, variables can be automatically enrolled if configured. bootctl1 @@ -386,8 +386,8 @@ During initialization, systemd-boot automatically loads all driver files placed in the /EFI/systemd/drivers/ directory of the ESP. The files placed there must have an extension of the EFI architecture ID followed by .efi (e.g. for x86-64 this means - a suffix of x64.efi). This may be used to automatically load file system drivers and - similar, to extend the native firmware support. + a suffix of x64.efi). This may be used e.g. to add support for hardware not + supported natively by the firmware. Enrollment of Secure Boot variables can be performed manually or automatically if files are available under /loader/keys/NAME/{db,dbx,KEK,PK}.auth, NAME diff --git a/src/bootctl/bootctl-status.c b/src/bootctl/bootctl-status.c index d691bce862..460c332ac7 100644 --- a/src/bootctl/bootctl-status.c +++ b/src/bootctl/bootctl-status.c @@ -424,7 +424,7 @@ int verb_status(int argc, char *argv[], void *userdata) { { EFI_LOADER_FEATURE_REPORT_URL, "Loader reports network boot URL" }, { EFI_LOADER_FEATURE_TYPE1_UKI, "Support Type #1 uki field" }, { EFI_LOADER_FEATURE_TYPE1_UKI_URL, "Support Type #1 uki-url field" }, - { EFI_LOADER_FEATURE_TPM2_ACTIVE_PCR_BANKS, "Loader reports TPM2 active PCR banks" }, + { EFI_LOADER_FEATURE_TPM2_ACTIVE_PCR_BANKS, "Loader reports active TPM2 PCR banks" }, }; static const struct { uint64_t flag;