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