docs/BOOT_LOADER_INTERFACE.md

   1 # The Boot Loader Interface
   2
   3 systemd can interface with the boot loader to receive performance data and
   4 other information, and pass control information. This is only supported on EFI
   5 systems. Data is transferred between the boot loader and systemd in EFI
   6 variables. All EFI variables use the vendor UUID
   7 `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`.
   8
   9 * The EFI Variable `LoaderTimeInitUSec` contains the timestamp in microseconds
  10   when the loader was initialized. This value is the time spent in the firmware
  11   for initialization, it is formatted as numeric, NUL-terminated, decimal
  12   string, in UTF-16.
  13
  14 * The EFI Variable `LoaderTimeExecUSec` contains the timestamp in microseconds
  15   when the loader finished its work and is about to execute the kernel. The
  16   time spent in the loader is the difference between `LoaderTimeExecUSec` and
  17   `LoaderTimeInitUSec`. This value is formatted the same way as
  18   `LoaderTimeInitUSec`.
  19
  20 * The EFI variable `LoaderDevicePartUUID` contains the partition GUID of the
  21   ESP the boot loader was run from formatted as NUL-terminated UTF16 string, in
  22   normal GUID syntax.
  23
  24 * The EFI variable `LoaderConfigTimeout` contains the boot menu time-out
  25   currently in use. It may be modified both by the boot loader and by the
  26   host. The value should be formatted as numeric, NUL-terminated, decimal
  27   string, in UTF-16. The time is specified in µs.
  28
  29 * Similarly, the EFI variable `LoaderConfigTimeoutOneShot` contains a boot menu
  30   time-out for a single following boot. It is set by the OS in order to request
  31   display of the boot menu on the following boot. When set overrides
  32   `LoaderConfigTimeout`. It is removed automatically after being read by the
  33   boot loader, to ensure it only takes effect a single time. This value is
  34   formatted the same way as `LoaderConfigTimeout`. If set to `0` the boot menu
  35   time-out is turned off, and the menu is shown indefinitely.
  36
  37 * The EFI variable `LoaderEntries` may contain a series of boot loader entry
  38   identifiers, one after the other, each individually NUL terminated. This may
  39   be used to let the OS know which boot menu entries were discovered by the
  40   boot loader. A boot loader entry identifier should be a short, non-empty
  41   alphanumeric string (possibly containing `-`, too). The list should be in the
  42   order the entries are shown on screen during boot. See below regarding a
  43   recommended vocabulary for boot loader entry identifiers.
  44
  45 * The EFI variable `LoaderEntryDefault` contains the default boot loader entry
  46   to use. It contains a NUL-terminated boot loader entry identifier.
  47
  48 * Similarly, the EFI variable `LoaderEntryOneShot` contains the default boot
  49   loader entry to use for a single following boot. It is set by the OS in order
  50   to request booting into a specific menu entry on the following boot. When set
  51   overrides `LoaderEntryDefault`. It is removed automatically after being read
  52   by the boot loader, to ensure it only takes effect a single time. This value
  53   is formatted the same way as `LoaderEntryDefault`.
  54
  55 * The EFI variable `LoaderEntrySelected` contains the boot loader entry
  56   identifier that was booted. It is set by the boot loader and read by
  57   the OS in order to identify which entry has been used for the current boot.
  58
  59 * The EFI variable `LoaderFeatures` contains a 64bit unsigned integer with a
  60   number of flags bits that are set by the boot loader and passed to the OS and
  61   indicate the features the boot loader supports. Specifically, the following
  62   bits are defined:
  63
  64   * `1 << 0` → The boot loader honours `LoaderConfigTimeout` when set.
  65   * `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set.
  66   * `1 << 2` → The boot loader honours `LoaderEntryDefault` when set.
  67   * `1 << 3` → The boot loader honours `LoaderEntryOneShot` when set.
  68   * `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT).
  69
  70 If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze`
  71 will include them in its boot-time analysis.  If `LoaderDevicePartUUID` is set,
  72 systemd will mount the ESP that was used for the boot to `/boot`, but only if
  73 that directory is empty, and only if no other file systems are mounted
  74 there. The `systemctl reboot --boot-loader-entry=…` and `systemctl reboot
  75 --boot-loader-menu=…` commands rely on the `LoaderFeatures` ,
  76 `LoaderConfigTimeoutOneShot`, `LoaderEntries`, `LoaderEntryOneShot` variables.
  77
  78 ## Boot Loader Entry Identifiers
  79
  80 While boot loader entries may be named relatively freely, it's highly
  81 recommended to follow the following rules when picking identifiers for the
  82 entries, so that programs (and users) can derive basic context and meaning from
  83 the identifiers as passed in `LoaderEntries`, `LoaderEntryDefault`,
  84 `LoaderEntryOneShot`, `LoaderEntrySelected`, and possibly show nicely localized
  85 names for them in UIs.
  86
  87 1. When boot loader entries are defined through [Boot Loader
  88    Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) drop-in files
  89    the identifier should be derived directly from the drop-in snippet name, but
  90    with the `.conf` (or `.efi` in case of Type #2 entries) suffix removed.
  91
  92 2. Entries automatically discovered by the boot loader (as opposed to being
  93    configured in configuration files) should generally have an identifier
  94    prefixed with `auto-`.
  95
  96 3. Boot menu entries referring to Microsoft Windows installations should either
  97    use the identifier `windows` or use the `windows-` prefix for the
  98    identifier. If a menu entry is automatically discovered, it should be
  99    prefixed with `auto-`, see above (Example: this means an automatically
 100    discovered Windows installation might have the identifier `auto-windows` or
 101    `auto-windows-10` or so.).
 102
 103 4. Similar, boot menu entries referring to Apple MacOS X installations should
 104    use the identifier `osx` or one that is prefixed with `osx-`. If such an
 105    entry is automatically discovered by the boot loader use `auto-osx` as
 106    identifier, or `auto-osx-` as prefix for the identifier, see above.
 107
 108 5. If a boot menu entry encapsulates the EFI shell program, it should use the
 109    identifier `efi-shell` (or when automatically discovered: `auto-efi-shell`,
 110    see above).
 111
 112 6. If a boot menu entry encapsulates a reboot into EFI firmware setup feature,
 113    it should use the identifier `reboot-to-firmware-setup` (or
 114    `auto-reboot-to-firmware-setup` in case it is automatically discovered).