summaryrefslogtreecommitdiffstats
path: root/docs/BOOT_LOADER_INTERFACE.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/BOOT_LOADER_INTERFACE.md')
-rw-r--r--docs/BOOT_LOADER_INTERFACE.md152
1 files changed, 152 insertions, 0 deletions
diff --git a/docs/BOOT_LOADER_INTERFACE.md b/docs/BOOT_LOADER_INTERFACE.md
new file mode 100644
index 0000000..15a575d
--- /dev/null
+++ b/docs/BOOT_LOADER_INTERFACE.md
@@ -0,0 +1,152 @@
+---
+title: Boot Loader Interface
+category: Booting
+layout: default
+---
+
+# 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 µs.
+
+* 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 a
+ 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.
+
+* 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 64bit 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](https://systemd.io/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.
+
+* The EFI variable `LoaderRandomSeed` contains a binary random seed if set. It
+ is set by the boot loader to pass an entropy seed read from the ESP partition
+ to the OS. The system manager then credits this seed to the kernel's entropy
+ pool. It is the responsibility of the boot loader to ensure the quality and
+ integrity of the random seed.
+
+* 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.
+
+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. `LoaderRandomSeed` is read by PID during early boot and credited to
+the kernel's random pool.
+
+## 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.
+
+1. When boot loader entries are defined through [Boot Loader
+ Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) drop-in files
+ the identifier should be derived directly from the drop-in snippet name, but
+ with the `.conf` (or `.efi` in case of Type #2 entries) 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. Similar, boot menu entries referring to Apple MacOS X 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
+
+[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)<br>
+[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)<br>
+[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
+[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
+[systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)