# 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`.
-
-* 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 `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 `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 `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.
-
-* 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.
-
-* 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 `LoaderEntryDefault` 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 `LoaderSysFailReason` contains the system failure reason.
+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 `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-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` 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 `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:
+* 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-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 << 6` → The boot loader supports passing a random seed to the OS.
* `1 << 13` → The boot loader honours `menu-disabled` option when set.
-* 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 `LoaderDeviceURL` 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 `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`.
If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze`
will include them in its boot-time analysis. If `LoaderDevicePartUUID` is set,
## 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 Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/)
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
projects / thirdparty / systemd.git / commitdiff
