1SYSTEMD-BOOT(7) systemd-boot SYSTEMD-BOOT(7)
2
6 systemd-boot, sd-boot - A simple UEFI boot manager
7
9 systemd-boot (short: sd-boot) is a simple UEFI boot manager. It
10 provides a graphical menu to select the entry to boot and an editor for
11 the kernel command line. systemd-boot supports systems with UEFI
12 firmware only.
13 systemd-boot loads boot entry information from the EFI system partition
15 (ESP), usually mounted at /efi/, /boot/, or /boot/efi/ during OS
16 runtime, as well as from the Extended Boot Loader partition if it
17 exists (usually mounted to /boot/). Configuration file fragments,
18 kernels, initrds and other EFI images to boot generally need to reside
19 on the ESP or the Extended Boot Loader partition. Linux kernels must be
20 built with CONFIG_EFI_STUB to be able to be directly executed as an EFI
21 image. During boot systemd-boot automatically assembles a list of boot
22 entries from the following sources:
23 • Boot entries defined with Boot Loader Specification[1] description
25 files located in /loader/entries/ on the ESP and the Extended Boot
26 Loader Partition. These usually describe Linux kernel images with
27 associated initrd images, but alternatively may also describe
28 arbitrary other EFI executables.
29 • Unified kernel images following the Boot Loader Specification[1],
31 as executable EFI binaries in /EFI/Linux/ on the ESP and the
32 Extended Boot Loader Partition.
33 • The Microsoft Windows EFI boot manager, if installed
35 • The Apple macOS boot manager, if installed
37 • The EFI Shell binary, if installed
39 • A reboot into the UEFI firmware setup option, if supported by the
41 firmware
42 systemd-boot supports the following features:
44 • Basic boot manager configuration changes (such as timeout
46 configuration, default boot entry selection, ...) may be made
47 directly from the boot loader UI at boot-time, as well as during
48 system runtime with EFI variables.
49 • The boot manager integrates with the systemctl command to implement
51 features such as systemctl reboot --boot-loader-entry=... (for
52 rebooting into a specific boot menu entry, i.e. "reboot into
53 Windows") and systemctl reboot --boot-loader-menu=... (for
54 rebooting into the boot loader menu), by implementing the Boot
55 Loader Interface[2]. See systemctl(1) for details.
56 • An EFI variable set by the boot loader informs the OS about the ESP
58 partition used during boot. This is then used to automatically
59 mount the correct ESP partition to /efi/ or /boot/ during OS
60 runtime. See systemd-gpt-auto-generator(8) for details.
61 • The boot manager provides information about the boot time spent in
63 UEFI firmware using the Boot Loader Interface[2]. This information
64 can be displayed using systemd-analyze(1).
65 • The boot manager implements boot counting and automatic fallback to
67 older, working boot entries on failure. See Automatic Boot
68 Assessment[3].
69 • The boot manager optionally reads a random seed from the ESP
71 partition, combines it with a 'system token' stored in a persistent
72 EFI variable and derives a random seed to use by the OS as entropy
73 pool initialization, providing a full entropy pool during early
74 boot.
75 bootctl(1) may be used from a running system to locate the ESP and the
77 Extended Boot Loader Partition, list available entries, and install
78 systemd-boot itself.
79 kernel-install(8) may be used to copy kernel images onto the ESP or the
81 Extended Boot Loader Partition and to generate description files
82 compliant with the Boot Loader Specification.
83
85 The following keys may be used in the boot menu:
86 ↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End
88 Navigate up/down in the entry list
89 ↵ (Enter), → (Right)
91 Boot selected entry
92 d
94 Make selected entry the default
95 e
97 Edit the kernel command line for selected entry
98 +, t
100 Increase the timeout before default entry is booted
101 -, T
103 Decrease the timeout
104 v
106 Show systemd-boot, UEFI, and firmware versions
107 P
109 Print status
110 Q
112 Quit
113 h, ?, F1
115 Show a help screen
116 Ctrl+l
118 Reprint the screen
119 The following keys may be pressed during bootup or in the boot menu to
121 directly boot a specific entry:
122 l
124 Linux
125 w
127 Windows
128 a
130 macOS
131 s
133 EFI shell
134 1, 2, 3, 4, 5, 6, 7, 8, 9
136 Boot entry number 1 ... 9
137 The boot menu is shown when a non-zero menu timeout has been
139 configured. If the menu timeout has been set to zero, it is sufficient
140 to press any key — before the boot loader initializes — to bring up the
141 boot menu, except for the keys listed immediately above as they
142 directly boot into the selected boot menu item. Note that depending on
143 the firmware implementation the time window where key presses are
144 accepted before the boot loader initializes might be short. If the
145 window is missed, reboot and try again, possibly pressing a suitable
146 key (e.g. the space bar) continuously; on most systems it should be
147 possible to hit the time window after a few attempts. To avoid this
148 problem, consider setting a non-zero timeout, thus showing the boot
149 menu unconditionally. Some desktop environments might offer an option
150 to directly boot into the boot menu, to avoid the problem altogether.
151 Alternatively, use the command line systemctl reboot
152 --boot-loader-menu=0 from the shell.
153 In the editor, most keys simply insert themselves, but the following
155 keys may be used to perform additional actions:
156 ← (Left), → (Right), Home, End
158 Navigate left/right
159 Esc
161 Abort the edit and quit the editor
162 Ctrl+k
164 Clear the command line
165 Ctrl+w, Alt+Backspace
167 Delete word backwards
168 Alt+d
170 Delete word forwards
171 ↵ (Enter)
173 Boot entry with the edited command line
174 Note that unless configured otherwise in the UEFI firmware,
176 systemd-boot will use the US keyboard layout, so key labels might not
177 match for keys like +/-.
178
180 The files systemd-boot processes generally reside on the UEFI ESP which
181 is usually mounted to /efi/, /boot/ or /boot/efi/ during OS runtime. It
182 also processes files on the Extended Boot Loader partition which is
183 typically mounted to /boot/, if it exists. systemd-boot reads runtime
184 configuration such as the boot timeout and default entry from
185 /loader/loader.conf on the ESP (in combination with data read from EFI
186 variables). See loader.conf(5). Boot entry description files following
187 the Boot Loader Specification[1] are read from /loader/entries/ on the
188 ESP and the Extended Boot Loader partition. Unified kernel boot entries
189 following the Boot Loader Specification[1] are read from /EFI/Linux/ on
190 the ESP and the Extended Boot Loader partition. Optionally, a random
191 seed for early boot entropy pool provisioning is stored in
192 /loader/random-seed in the ESP.
193
195 The following EFI variables are defined, set and read by systemd-boot,
196 under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4", for
197 communication between the OS and the boot loader:
198 LoaderBootCountPath
200 If boot counting is enabled, contains the path to the file in whose
201 name the boot counters are encoded. Set by the boot loader.
202 systemd-bless-boot.service(8) uses this information to mark a boot
203 as successful as determined by the successful activation of the
204 boot-complete.target target unit.
205 LoaderConfigTimeout, LoaderConfigTimeoutOneShot
207 The menu timeout in seconds. Read by the boot loader.
208 LoaderConfigTimeout is maintained persistently, while
209 LoaderConfigTimeoutOneShot is a one-time override which is read
210 once (in which case it takes precedence over LoaderConfigTimeout)
211 and then removed. LoaderConfigTimeout may be manipulated with the
212 t/T keys, see above.
213 LoaderDevicePartUUID
215 Contains the partition UUID of the EFI System Partition the boot
216 loader was run from. Set by the boot loader. systemd-gpt-auto-
217 generator(8) uses this information to automatically find the disk
218 booted from, in order to discover various other partitions on the
219 same disk automatically.
220 LoaderEntries
222 A list of the identifiers of all discovered boot loader entries.
223 Set by the boot loader.
224 LoaderEntryDefault, LoaderEntryOneShot
226 The identifier of the default boot loader entry. Set primarily by
227 the OS and read by the boot loader. LoaderEntryOneShot sets the
228 default entry for the next boot only, while LoaderEntryDefault sets
229 it persistently for all future boots. bootctl(1)'s set-default and
230 set-oneshot commands make use of these variables. The boot loader
231 modifies LoaderEntryDefault on request, when the d key is used, see
232 above.
233 LoaderEntrySelected
235 The identifier of the boot loader entry currently being booted. Set
236 by the boot loader.
237 LoaderFeatures
239 A set of flags indicating the features the boot loader supports.
240 Set by the boot loader. Use bootctl(1) to view this data.
241 LoaderFirmwareInfo, LoaderFirmwareType
243 Brief firmware information. Set by the boot loader. Use bootctl(1)
244 to view this data.
245 LoaderImageIdentifier
247 The path of executable of the boot loader used for the current
248 boot, relative to the EFI System Partition's root directory. Set by
249 the boot loader. Use bootctl(1) to view this data.
250 LoaderInfo
252 Brief information about the boot loader. Set by the boot loader.
253 Use bootctl(1) to view this data.
254 LoaderTimeExecUSec, LoaderTimeInitUSec, LoaderTimeMenuUsec
256 Information about the time spent in various parts of the boot
257 loader. Set by the boot loader. Use systemd-analyze(1) to view this
258 data.
259 LoaderRandomSeed
261 A binary random seed systemd-boot may optionally pass to the OS.
262 This is a volatile EFI variable that is hashed at boot from the
263 combination of a random seed stored in the ESP (in
264 /loader/random-seed) and a "system token" persistently stored in
265 the EFI variable LoaderSystemToken (see below). During early OS
266 boot the system manager reads this variable and passes it to the OS
267 kernel's random pool, crediting the full entropy it contains. This
268 is an efficient way to ensure the system starts up with a fully
269 initialized kernel random pool — as early as the initial RAM disk
270 phase. systemd-boot reads the random seed from the ESP, combines
271 it with the "system token", and both derives a new random seed to
272 update in-place the seed stored in the ESP, and the random seed to
273 pass to the OS from it via SHA256 hashing in counter mode. This
274 ensures that different physical systems that boot the same "golden"
275 OS image — i.e. containing the same random seed file in the ESP —
276 will still pass a different random seed to the OS. It is made sure
277 the random seed stored in the ESP is fully overwritten before the
278 OS is booted, to ensure different random seed data is used between
279 subsequent boots.
280 See Random Seeds[4] for further information.
282 LoaderSystemToken
284 A binary random data field, that is used for generating the random
285 seed to pass to the OS (see above). Note that this random data is
286 generally only generated once, during OS installation, and is then
287 never updated again.
288 Many of these variables are defined by the Boot Loader Interface[2].
290
292 systemd-boot implements a simple boot counting mechanism on top of the
293 Boot Loader Specification[1], for automatic and unattended fallback to
294 older kernel versions/boot loader entries when a specific entry
295 continuously fails. Any boot loader entry file and unified kernel image
296 file that contains a "+" followed by one or two numbers (if two they
297 need to be separated by a "-"), before the .conf or .efi suffix is
298 subject to boot counting: the first of the two numbers ('tries left')
299 is decreased by one on every boot attempt, the second of the two
300 numbers ('tries done') is increased by one (if 'tries done' is absent
301 it is considered equivalent to 0). Depending on the current value of
302 these two counters the boot entry is considered to be in one of three
303 states:
304 1. If the 'tries left' counter of an entry is greater than zero the
306 entry is considered to be in 'indeterminate' state. This means the
307 entry has not completed booting successfully yet, but also hasn't
308 been determined not to work.
309 2. If the 'tries left' counter of an entry is zero it is considered to
311 be in 'bad' state. This means no further attempts to boot this item
312 will be made (that is, unless all other boot entries are also in
313 'bad' state), as all attempts to boot this entry have not completed
314 successfully.
315 3. If the 'tries left' and 'tries done' counters of an entry are
317 absent it is considered to be in 'good' state. This means further
318 boot counting for the entry is turned off, as it successfully
319 booted at least once. The systemd-bless-boot.service(8) service
320 moves the currently booted entry from 'indeterminate' into 'good'
321 state when a boot attempt completed successfully.
322 Generally, when new entries are added to the boot loader, they first
324 start out in 'indeterminate' state, i.e. with a 'tries left' counter
325 greater than zero. The boot entry remains in this state until either it
326 managed to complete a full boot successfully at least once (in which
327 case it will be in 'good' state) — or the 'tries left' counter reaches
328 zero (in which case it will be in 'bad' state).
329 Example: let's say a boot loader entry file foo.conf is set up for 3
331 boot tries. The installer will hence create it under the name
332 foo+3.conf. On first boot, the boot loader will rename it to
333 foo+2-1.conf. If that boot does not complete successfully, the boot
334 loader will rename it to foo+1-2.conf on the following boot. If that
335 fails too, it will finally be renamed foo+0-3.conf by the boot loader
336 on next boot, after which it will be considered 'bad'. If the boot
337 succeeds however the entry file will be renamed to foo.conf by the OS,
338 so that it is considered 'good' from then on.
339 The boot menu takes the 'tries left' counter into account when sorting
341 the menu entries: entries in 'bad' state are ordered at the beginning
342 of the list, and entries in 'good' or 'indeterminate' at the end. The
343 user can freely choose to boot any entry of the menu, including those
344 already marked 'bad'. If the menu entry to boot is automatically
345 determined, this means that 'good' or 'indeterminate' entries are
346 generally preferred (as the bottom item of the menu is the one booted
347 by default), and 'bad' entries will only be considered if there are no
348 'good' or 'indeterminate' entries left.
349 The kernel-install(8) kernel install framework optionally sets the
351 initial 'tries left' counter to the value specified in
352 /etc/kernel/tries when a boot loader entry is first created.
353
355 bootctl(1), loader.conf(5), systemd-bless-boot.service(8), systemd-
356 boot-system-token.service(8), kernel-install(8), Boot Loader
357 Specification[1], Boot Loader Interface[2]
358
360 1. Boot Loader Specification
361 https://systemd.io/BOOT_LOADER_SPECIFICATION
362 2. Boot Loader Interface
364 https://systemd.io/BOOT_LOADER_INTERFACE
365 3. Automatic Boot Assessment
367 https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
368 4. Random Seeds
370 https://systemd.io/RANDOM_SEEDS
371systemd 248 SYSTEMD-BOOT(7)