systemd/docs/BOOT_LOADER_INTERFACE.md

title, category, layout, SPDX-License-Identifier

title	category	layout	SPDX-License-Identifier
Boot Loader Interface	Booting	default	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. Variables will be listed below using the Linux efivarfs naming, <name>-<vendoruuid>.

• 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-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-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-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-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-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 LoaderEntryPreferred-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f contains the preferred boot loader entry to use. This takes boot assessment into account by not selecting boot entries that have been marked as bad, see Automatic Boot Assessment for more details on boot assessment. If no entry was selected by the preferred setting (from either the EFI var or the config file), then the boot loader will look at the default setting, which does not skip entries that were marked as bad. 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. This ignores boot assessment and can select boot entries that have been marked as bad by boot assessment, see Automatic Boot Assessment for more details on boot assessment as well as the documentation on the LoaderEntryPreferred EFI var. It contains a NUL-terminated boot loader entry identifier.

• 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-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-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 LoaderEntryPreferred and 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 and LoaderEntryPreferred.

• 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-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.
  • 1 << 2 → The boot loader honours LoaderEntryDefault when set.
  • 1 << 3 → The boot loader honours LoaderEntryOneShot when set.
  • 1 << 4 → The boot loader supports boot counting as described in 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).
  • 1 << 8 → The boot loader supports the sort-key field defined by the 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.
  • 1 << 11 → The boot loader support automatic enrollment of SecureBoot keys, see systemd-boot(7).
  • 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.
  • 1 << 17 → The boot loader supports the uki-url field defined by the Boot Loader Specification.
  • 1 << 18 → The boot loader reports active TPM2 PCR banks in the EFI variable LoaderTpm2ActivePcrBanks-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f.
  • 1 << 19 → The boot loader supports the LoaderEntryPreferred variable when set.
  • 1 << 20 → The boot loader reports the firmware-configured keyboard layout in the EFI variable LoaderKeyboardLayout-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f.
  • 1 << 21 → The boot loader measures SMBIOS information into a TPM2 PCR and reports the PCR index in the EFI variable LoaderPcrSMBIOS-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f.

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

• The EFI variable LoaderKeyboardLayout-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f contains the RFC 4646 (BCP 47) language tag of the currently-active keyboard layout as reported by the UEFI HII database (e.g. en-US, de-DE). It is formatted as a NUL-terminated UTF-16 string. The boot loader sets this variable from the layout returned by EFI_HII_DATABASE_PROTOCOL.GetKeyboardLayout(), if that protocol is implemented by the firmware. Userspace (notably systemd-vconsole-setup) uses this as a lowest-priority fallback keyboard layout when no explicit configuration is provided.

• The EFI variable LoaderPcrSMBIOS-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f contains the index of the TPM2 PCR (as a decimal ASCII string formatted as a NUL-terminated UTF-16 string, e.g. 1) into which the boot loader measured select SMBIOS structures: type 1 (system information, with the volatile "Wake-up Type" field zeroed out), type 2 (baseboard information) and type 11 (OEM strings). This is a volatile (non-persistent) variable, set only if a measurement was successfully completed, and remains unset otherwise. Both systemd-boot and systemd-stub perform this measurement; whichever runs first sets the variable, and its presence suppresses a second measurement of the same data into the same PCR during the same boot.

If LoaderTimeInitUSec and LoaderTimeExecUSec are set, systemd-analyze will include them in its boot-time analysis. If LoaderDevicePartUUID is set, systemd will mount the ESP that was used for the boot to /boot, but only if that directory is empty, and only if no other file systems are mounted there. The systemctl reboot --boot-loader-entry=… and systemctl reboot --boot-loader-menu=… commands rely on the LoaderFeatures , LoaderConfigTimeoutOneShot, LoaderEntries, LoaderEntryOneShot variables.

Boot Loader Entry Identifiers

While boot loader entries may be named relatively freely, it's highly recommended to follow these 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, LoaderEntryPreferred, 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 files, the identifier should be derived directly from the file name, 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-.

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.

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

Links

UAPI.1 Boot Loader Specification
UAPI.2 Discoverable Partitions Specification
systemd-boot(7)
bootctl(1)
systemd-gpt-auto-generator(8)