Merge pull request #16096 from poettering/journal-hash-fix

[thirdparty/systemd.git] / docs / BOOT_LOADER_INTERFACE.md

diff --git a/docs/BOOT_LOADER_INTERFACE.md b/docs/BOOT_LOADER_INTERFACE.md
index e1b99be960af167712b4429ef2ec9f2b581f244a..6084fe2a2a444b080f5c025c69999cc432c53c7b 100644 (file)
--- a/docs/BOOT_LOADER_INTERFACE.md
+++ b/docs/BOOT_LOADER_INTERFACE.md
@@ -1,3 +1,9 @@
+---
+title: Boot Loader Interface
+category: Booting
+layout: default
+---
+
 # The Boot Loader Interface
 
 systemd can interface with the boot loader to receive performance data and
@@ -21,18 +27,18 @@ variables. All EFI variables use the vendor UUID
   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 time-out
+* 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
-  time-out for a single following boot. It is set by the OS in order to request
+  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
-  time-out is turned off, and the menu is shown indefinitely.
+  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
@@ -66,6 +72,28 @@ variables. All EFI variables use the vendor UUID
   * `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,
@@ -73,7 +101,9 @@ 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.
+`LoaderConfigTimeoutOneShot`, `LoaderEntries`, `LoaderEntryOneShot`
+variables. `LoaderRandomSeed` is read by PID during early boot and credited to
+the kernel's random pool.
 
 ## Boot Loader Entry Identifiers
 
@@ -112,3 +142,11 @@ names for them in UIs.
 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_INTERFACE)<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)