docs/BOOT_LOADER_INTERFACE.md

   1 ---
   2 title: Boot Loader Interface
   3 category: Booting
   4 layout: default
   5 ---
   6
   7 # The Boot Loader Interface
   8
   9 systemd can interface with the boot loader to receive performance data and
  10 other information, and pass control information. This is only supported on EFI
  11 systems. Data is transferred between the boot loader and systemd in EFI
  12 variables. All EFI variables use the vendor UUID
  13 `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`.
  14
  15 * The EFI Variable `LoaderTimeInitUSec` contains the timestamp in microseconds
  16   when the loader was initialized. This value is the time spent in the firmware
  17   for initialization, it is formatted as numeric, NUL-terminated, decimal
  18   string, in UTF-16.
  19
  20 * The EFI Variable `LoaderTimeExecUSec` contains the timestamp in microseconds
  21   when the loader finished its work and is about to execute the kernel. The
  22   time spent in the loader is the difference between `LoaderTimeExecUSec` and
  23   `LoaderTimeInitUSec`. This value is formatted the same way as
  24   `LoaderTimeInitUSec`.
  25
  26 * The EFI variable `LoaderDevicePartUUID` contains the partition GUID of the
  27   ESP the boot loader was run from formatted as NUL-terminated UTF16 string, in
  28   normal GUID syntax.
  29
  30 * The EFI variable `LoaderConfigTimeout` contains the boot menu timeout
  31   currently in use. It may be modified both by the boot loader and by the
  32   host. The value should be formatted as numeric, NUL-terminated, decimal
  33   string, in UTF-16. The time is specified in µs.
  34
  35 * Similarly, the EFI variable `LoaderConfigTimeoutOneShot` contains a boot menu
  36   timeout for a single following boot. It is set by the OS in order to request
  37   display of the boot menu on the following boot. When set overrides
  38   `LoaderConfigTimeout`. It is removed automatically after being read by the
  39   boot loader, to ensure it only takes effect a single time. This value is
  40   formatted the same way as `LoaderConfigTimeout`. If set to `0` the boot menu
  41   timeout is turned off, and the menu is shown indefinitely.
  42
  43 * The EFI variable `LoaderEntries` may contain a series of boot loader entry
  44   identifiers, one after the other, each individually NUL terminated. This may
  45   be used to let the OS know which boot menu entries were discovered by the
  46   boot loader. A boot loader entry identifier should be a short, non-empty
  47   alphanumeric string (possibly containing `-`, too). The list should be in the
  48   order the entries are shown on screen during boot. See below regarding a
  49   recommended vocabulary for boot loader entry identifiers.
  50
  51 * The EFI variable `LoaderEntryDefault` contains the default boot loader entry
  52   to use. It contains a NUL-terminated boot loader entry identifier.
  53
  54 * Similarly, the EFI variable `LoaderEntryOneShot` contains the default boot
  55   loader entry to use for a single following boot. It is set by the OS in order
  56   to request booting into a specific menu entry on the following boot. When set
  57   overrides `LoaderEntryDefault`. It is removed automatically after being read
  58   by the boot loader, to ensure it only takes effect a single time. This value
  59   is formatted the same way as `LoaderEntryDefault`.
  60
  61 * The EFI variable `LoaderEntrySelected` contains the boot loader entry
  62   identifier that was booted. It is set by the boot loader and read by
  63   the OS in order to identify which entry has been used for the current boot.
  64
  65 * The EFI variable `LoaderFeatures` contains a 64bit unsigned integer with a
  66   number of flags bits that are set by the boot loader and passed to the OS and
  67   indicate the features the boot loader supports. Specifically, the following
  68   bits are defined:
  69
  70   * `1 << 0` → The boot loader honours `LoaderConfigTimeout` when set.
  71   * `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set.
  72   * `1 << 2` → The boot loader honours `LoaderEntryDefault` when set.
  73   * `1 << 3` → The boot loader honours `LoaderEntryOneShot` when set.
  74   * `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT).
  75   * `1 << 5` → The boot loader supports looking for boot menu entries in the Extended Boot Loader Partition.
  76   * `1 << 6` → The boot loader supports passing a random seed to the OS.
  77
  78 * The EFI variable `LoaderRandomSeed` contains a binary random seed if set. It
  79   is set by the boot loader to pass an entropy seed read from the ESP partition
  80   to the OS. The system manager then credits this seed to the kernel's entropy
  81   pool. It is the responsibility of the boot loader to ensure the quality and
  82   integrity of the random seed.
  83
  84 * The EFI variable `LoaderSystemToken` contains binary random data,
  85   persistently set by the OS installer. Boot loaders that support passing
  86   random seeds to the OS should use this data and combine it with the random
  87   seed file read from the ESP. By combining this random data with the random
  88   seed read off the disk before generating a seed to pass to the OS and a new
  89   seed to store in the ESP the boot loader can protect itself from situations
  90   where "golden" OS images that include a random seed are replicated and used
  91   on multiple systems. Since the EFI variable storage is usually independent
  92   (i.e. in physical NVRAM) of the ESP file system storage, and only the latter
  93   is part of "golden" OS images, this ensures that different systems still come
  94   up with different random seeds. Note that the `LoaderSystemToken` is
  95   generally only written once, by the OS installer, and is usually not touched
  96   after that.
  97
  98 If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze`
  99 will include them in its boot-time analysis.  If `LoaderDevicePartUUID` is set,
 100 systemd will mount the ESP that was used for the boot to `/boot`, but only if
 101 that directory is empty, and only if no other file systems are mounted
 102 there. The `systemctl reboot --boot-loader-entry=…` and `systemctl reboot
 103 --boot-loader-menu=…` commands rely on the `LoaderFeatures` ,
 104 `LoaderConfigTimeoutOneShot`, `LoaderEntries`, `LoaderEntryOneShot`
 105 variables. `LoaderRandomSeed` is read by PID during early boot and credited to
 106 the kernel's random pool.
 107
 108 ## Boot Loader Entry Identifiers
 109
 110 While boot loader entries may be named relatively freely, it's highly
 111 recommended to follow the following rules when picking identifiers for the
 112 entries, so that programs (and users) can derive basic context and meaning from
 113 the identifiers as passed in `LoaderEntries`, `LoaderEntryDefault`,
 114 `LoaderEntryOneShot`, `LoaderEntrySelected`, and possibly show nicely localized
 115 names for them in UIs.
 116
 117 1. When boot loader entries are defined through [Boot Loader
 118    Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) drop-in files
 119    the identifier should be derived directly from the drop-in snippet name, but
 120    with the `.conf` (or `.efi` in case of Type #2 entries) suffix removed.
 121
 122 2. Entries automatically discovered by the boot loader (as opposed to being
 123    configured in configuration files) should generally have an identifier
 124    prefixed with `auto-`.
 125
 126 3. Boot menu entries referring to Microsoft Windows installations should either
 127    use the identifier `windows` or use the `windows-` prefix for the
 128    identifier. If a menu entry is automatically discovered, it should be
 129    prefixed with `auto-`, see above (Example: this means an automatically
 130    discovered Windows installation might have the identifier `auto-windows` or
 131    `auto-windows-10` or so.).
 132
 133 4. Similar, boot menu entries referring to Apple MacOS X installations should
 134    use the identifier `osx` or one that is prefixed with `osx-`. If such an
 135    entry is automatically discovered by the boot loader use `auto-osx` as
 136    identifier, or `auto-osx-` as prefix for the identifier, see above.
 137
 138 5. If a boot menu entry encapsulates the EFI shell program, it should use the
 139    identifier `efi-shell` (or when automatically discovered: `auto-efi-shell`,
 140    see above).
 141
 142 6. If a boot menu entry encapsulates a reboot into EFI firmware setup feature,
 143    it should use the identifier `reboot-to-firmware-setup` (or
 144    `auto-reboot-to-firmware-setup` in case it is automatically discovered).
 145
 146 ## Links
 147
 148 [Boot Loader Specification](https://systemd.io/BOOT_LOADER_INTERFACE)<br>
 149 [Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)<br>
 150 [systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
 151 [bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
 152 [systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)