]>
Commit | Line | Data |
---|---|---|
c3e270f4 | 1 | --- |
a0fadf66 | 2 | title: Boot Loader Interface |
4cdca0af | 3 | category: Booting |
b41a3f66 | 4 | layout: default |
0aff7b75 | 5 | SPDX-License-Identifier: LGPL-2.1-or-later |
c3e270f4 FB |
6 | --- |
7 | ||
2fe82132 LP |
8 | # The Boot Loader Interface |
9 | ||
10 | systemd can interface with the boot loader to receive performance data and | |
11 | other information, and pass control information. This is only supported on EFI | |
12 | systems. Data is transferred between the boot loader and systemd in EFI | |
13 | variables. 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 | ||
3f9a0a52 | 31 | * The EFI variable `LoaderConfigTimeout` contains the boot menu timeout |
2fe82132 LP |
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 | |
3f9a0a52 | 37 | timeout for a single following boot. It is set by the OS in order to request |
2fe82132 LP |
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 | |
3f9a0a52 | 42 | timeout is turned off, and the menu is shown indefinitely. |
2fe82132 LP |
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. | |
5c90c67a | 75 | * `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](AUTOMATIC_BOOT_ASSESSMENT.md). |
c7bb4dfc | 76 | * `1 << 5` → The boot loader supports looking for boot menu entries in the Extended Boot Loader Partition. |
22aba2b9 | 77 | * `1 << 6` → The boot loader supports passing a random seed to the OS. |
c7bb4dfc LP |
78 | |
79 | * The EFI variable `LoaderRandomSeed` contains a binary random seed if set. It | |
250db1bf | 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. | |
c7bb4dfc LP |
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. | |
2fe82132 LP |
98 | |
99 | If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze` | |
100 | will include them in its boot-time analysis. If `LoaderDevicePartUUID` is set, | |
101 | systemd will mount the ESP that was used for the boot to `/boot`, but only if | |
102 | that directory is empty, and only if no other file systems are mounted | |
103 | there. The `systemctl reboot --boot-loader-entry=…` and `systemctl reboot | |
104 | --boot-loader-menu=…` commands rely on the `LoaderFeatures` , | |
c7bb4dfc LP |
105 | `LoaderConfigTimeoutOneShot`, `LoaderEntries`, `LoaderEntryOneShot` |
106 | variables. `LoaderRandomSeed` is read by PID during early boot and credited to | |
107 | the kernel's random pool. | |
f7f00fb1 LP |
108 | |
109 | ## Boot Loader Entry Identifiers | |
110 | ||
111 | While boot loader entries may be named relatively freely, it's highly | |
112 | recommended to follow the following rules when picking identifiers for the | |
113 | entries, so that programs (and users) can derive basic context and meaning from | |
114 | the identifiers as passed in `LoaderEntries`, `LoaderEntryDefault`, | |
115 | `LoaderEntryOneShot`, `LoaderEntrySelected`, and possibly show nicely localized | |
116 | names for them in UIs. | |
117 | ||
5c90c67a BF |
118 | 1. When boot loader entries are defined through |
119 | [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md) drop-in files | |
f7f00fb1 LP |
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 | ||
123 | 2. 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 | ||
127 | 3. 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 | ||
6d3831ce | 134 | 4. Similar, boot menu entries referring to Apple macOS installations should |
f7f00fb1 LP |
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 | ||
139 | 5. 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 | ||
143 | 6. 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). | |
b0cda241 ZJS |
146 | |
147 | ## Links | |
148 | ||
5c90c67a BF |
149 | [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md)<br> |
150 | [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md)<br> | |
a43d2229 LP |
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) |