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 textual 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 (XBOOTLDR)
17 if it 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] Type #1
25 description files located in /loader/entries/ on the ESP and the
26 Extended Boot Loader Partition. These usually describe Linux kernel
27 images with associated initrd images, but alternatively may also
28 describe other arbitrary EFI executables.
29 • Unified kernel images, Boot Loader Specification[1] Type #2, which
31 are 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 EFI
58 System Partition used during boot. This is then used to
59 automatically mount the correct EFI System Partition to /efi/ or
60 /boot/ during OS runtime. See systemd-gpt-auto-generator(8) for
61 details.
62 • The boot manager provides information about the boot time spent in
64 UEFI firmware using the Boot Loader Interface[2]. This information
65 can be displayed using systemd-analyze(1).
66 • The boot manager implements boot counting and automatic fallback to
68 older, working boot entries on failure. See Automatic Boot
69 Assessment[3].
70 • The boot manager optionally reads a random seed from the ESP
72 partition, combines it with a 'system token' stored in a persistent
73 EFI variable and derives a random seed to use by the OS as entropy
74 pool initialization, providing a full entropy pool during early
75 boot.
76 bootctl(1) may be used from a running system to locate the ESP and the
78 Extended Boot Loader Partition, list available entries, and install
79 systemd-boot itself.
80 kernel-install(8) may be used to copy kernel images onto the ESP or the
82 Extended Boot Loader Partition and to generate description files
83 compliant with the Boot Loader Specification.
84 systemd-stub(7) may be used as UEFI boot stub for executed kernels,
86 which is useful to show graphical boot splashes before transitioning
87 into the Linux world. It is also capable of automatically picking up
88 auxiliary credential files (for boot parameterization) and system
89 extension images, as companion files to the booted kernel images.
90
92 The following keys may be used in the boot menu:
93 ↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End
95 Navigate up/down in the entry list
96 ↵ (Enter), → (Right)
98 Boot selected entry
99 d
101 Make selected entry the default
102 e
104 Edit the kernel command line for selected entry
105 +, t
107 Increase the timeout before default entry is booted
108 -, T
110 Decrease the timeout
111 r
113 Change screen resolution, skipping any unsupported modes.
114 R
116 Reset screen resolution to firmware or configuration file default.
117 p
119 Print status
120 h, ?, F1
122 Show a help screen
123 f
125 Reboot into firmware interface.
126 For compatibility with the keybindings of several firmware
128 implementations this operation may also be reached with F2, F10,
129 Del and Esc.
130 The following keys may be pressed during bootup or in the boot menu to
132 directly boot a specific entry:
133 l
135 Linux
136 w
138 Windows
139 a
141 macOS
142 s
144 EFI shell
145 1, 2, 3, 4, 5, 6, 7, 8, 9
147 Boot entry number 1 ... 9
148 The boot menu is shown when a non-zero menu timeout has been
150 configured. If the menu timeout has been set to zero, it is sufficient
151 to press any key — before the boot loader initializes — to bring up the
152 boot menu, except for the keys listed immediately above as they
153 directly boot into the selected boot menu item. Note that depending on
154 the firmware implementation the time window where key presses are
155 accepted before the boot loader initializes might be short. If the
156 window is missed, reboot and try again, possibly pressing a suitable
157 key (e.g. the space bar) continuously; on most systems it should be
158 possible to hit the time window after a few attempts. To avoid this
159 problem, consider setting a non-zero timeout, thus showing the boot
160 menu unconditionally. Some desktop environments might offer an option
161 to directly boot into the boot menu, to avoid the problem altogether.
162 Alternatively, use the command line systemctl reboot
163 --boot-loader-menu=0 from the shell.
164 In the editor, most keys simply insert themselves, but the following
166 keys may be used to perform additional actions:
167 ← (Left), → (Right), Home, End
169 Navigate left/right
170 Esc
172 Abort the edit and quit the editor
173 Ctrl+k
175 Clear the command line
176 Ctrl+w, Alt+Backspace
178 Delete word backwards
179 Alt+d
181 Delete word forwards
182 ↵ (Enter)
184 Boot entry with the edited command line
185 Note that unless configured otherwise in the UEFI firmware,
187 systemd-boot will use the US keyboard layout, so key labels might not
188 match for keys like +/-.
189
191 The files systemd-boot processes generally reside on the UEFI ESP which
192 is usually mounted to /efi/, /boot/ or /boot/efi/ during OS runtime. It
193 also processes files on the Extended Boot Loader partition which is
194 typically mounted to /boot/, if it exists.
195 systemd-boot reads runtime configuration such as the boot timeout and
197 default entry from /loader/loader.conf on the ESP (in combination with
198 data read from EFI variables). See loader.conf(5).
199 Boot entry description files following the Boot Loader Specification[1]
201 are read from /loader/entries/ on the ESP and the Extended Boot Loader
202 partition.
203 Unified kernel boot entries following the Boot Loader Specification[1]
205 are read from /EFI/Linux/ on the ESP and the Extended Boot Loader
206 partition.
207 Optionally, a random seed for early boot entropy pool provisioning is
209 stored in /loader/random-seed in the ESP.
210 During initialization, sd-boot automatically loads all driver files
212 placed in the /EFI/systemd/drivers/ directory of the ESP. The files
213 placed there must have an extension of the EFI architecture ID followed
214 by .efi (e.g. for x86-64 this means a suffix of x64.efi). This may be
215 used to automatically load file system drivers and similar, to extend
216 the native firmware support.
217
219 The following EFI variables are defined, set and read by systemd-boot,
220 under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f", for
221 communication between the boot loader and the OS:
222 LoaderBootCountPath
224 If boot counting is enabled, contains the path to the file in whose
225 name the boot counters are encoded. Set by the boot loader.
226 systemd-bless-boot.service(8) uses this information to mark a boot
227 as successful as determined by the successful activation of the
228 boot-complete.target target unit.
229 LoaderConfigTimeout, LoaderConfigTimeoutOneShot
231 The menu timeout in seconds. Read by the boot loader.
232 LoaderConfigTimeout is maintained persistently, while
233 LoaderConfigTimeoutOneShot is a one-time override which is read
234 once (in which case it takes precedence over LoaderConfigTimeout)
235 and then removed. LoaderConfigTimeout may be manipulated with the
236 t/T keys, see above.
237 LoaderDevicePartUUID
239 Contains the partition UUID of the EFI System Partition the boot
240 loader was run from. Set by the boot loader. systemd-gpt-auto-
241 generator(8) uses this information to automatically find the disk
242 booted from, in order to discover various other partitions on the
243 same disk automatically.
244 LoaderEntries
246 A list of the identifiers of all discovered boot loader entries.
247 Set by the boot loader.
248 LoaderEntryDefault, LoaderEntryOneShot
250 The identifier of the default boot loader entry. Set primarily by
251 the OS and read by the boot loader. LoaderEntryOneShot sets the
252 default entry for the next boot only, while LoaderEntryDefault sets
253 it persistently for all future boots. bootctl(1)'s set-default and
254 set-oneshot commands make use of these variables. The boot loader
255 modifies LoaderEntryDefault on request, when the d key is used, see
256 above.
257 LoaderEntrySelected
259 The identifier of the boot loader entry currently being booted. Set
260 by the boot loader.
261 LoaderFeatures
263 A set of flags indicating the features the boot loader supports.
264 Set by the boot loader. Use bootctl(1) to view this data.
265 LoaderFirmwareInfo, LoaderFirmwareType
267 Brief firmware information. Set by the boot loader. Use bootctl(1)
268 to view this data.
269 LoaderImageIdentifier
271 The path of executable of the boot loader used for the current
272 boot, relative to the EFI System Partition's root directory. Set by
273 the boot loader. Use bootctl(1) to view this data.
274 LoaderInfo
276 Brief information about the boot loader. Set by the boot loader.
277 Use bootctl(1) to view this data.
278 LoaderTimeExecUSec, LoaderTimeInitUSec, LoaderTimeMenuUsec
280 Information about the time spent in various parts of the boot
281 loader. Set by the boot loader. Use systemd-analyze(1) to view this
282 data.
283 LoaderRandomSeed
285 A binary random seed systemd-boot may optionally pass to the OS.
286 This is a volatile EFI variable that is hashed at boot from the
287 combination of a random seed stored in the ESP (in
288 /loader/random-seed) and a "system token" persistently stored in
289 the EFI variable LoaderSystemToken (see below). During early OS
290 boot the system manager reads this variable and passes it to the OS
291 kernel's random pool, crediting the full entropy it contains. This
292 is an efficient way to ensure the system starts up with a fully
293 initialized kernel random pool — as early as the initial RAM disk
294 phase. systemd-boot reads the random seed from the ESP, combines
295 it with the "system token", and both derives a new random seed to
296 update in-place the seed stored in the ESP, and the random seed to
297 pass to the OS from it via SHA256 hashing in counter mode. This
298 ensures that different physical systems that boot the same "golden"
299 OS image — i.e. containing the same random seed file in the ESP —
300 will still pass a different random seed to the OS. It is made sure
301 the random seed stored in the ESP is fully overwritten before the
302 OS is booted, to ensure different random seed data is used between
303 subsequent boots.
304 See Random Seeds[4] for further information.
306 LoaderSystemToken
308 A binary random data field, that is used for generating the random
309 seed to pass to the OS (see above). Note that this random data is
310 generally only generated once, during OS installation, and is then
311 never updated again.
312 Many of these variables are defined by the Boot Loader Interface[2].
314
316 systemd-boot implements a simple boot counting mechanism on top of the
317 Boot Loader Specification[1], for automatic and unattended fallback to
318 older kernel versions/boot loader entries when a specific entry
319 continuously fails. Any boot loader entry file and unified kernel image
320 file that contains a "+" followed by one or two numbers (if two they
321 need to be separated by a "-"), before the .conf or .efi suffix is
322 subject to boot counting: the first of the two numbers ('tries left')
323 is decreased by one on every boot attempt, the second of the two
324 numbers ('tries done') is increased by one (if 'tries done' is absent
325 it is considered equivalent to 0). Depending on the current value of
326 these two counters the boot entry is considered to be in one of three
327 states:
328 1. If the 'tries left' counter of an entry is greater than zero the
330 entry is considered to be in 'indeterminate' state. This means the
331 entry has not completed booting successfully yet, but also hasn't
332 been determined not to work.
333 2. If the 'tries left' counter of an entry is zero it is considered to
335 be in 'bad' state. This means no further attempts to boot this item
336 will be made (that is, unless all other boot entries are also in
337 'bad' state), as all attempts to boot this entry have not completed
338 successfully.
339 3. If the 'tries left' and 'tries done' counters of an entry are
341 absent it is considered to be in 'good' state. This means further
342 boot counting for the entry is turned off, as it successfully
343 booted at least once. The systemd-bless-boot.service(8) service
344 moves the currently booted entry from 'indeterminate' into 'good'
345 state when a boot attempt completed successfully.
346 Generally, when new entries are added to the boot loader, they first
348 start out in 'indeterminate' state, i.e. with a 'tries left' counter
349 greater than zero. The boot entry remains in this state until either it
350 managed to complete a full boot successfully at least once (in which
351 case it will be in 'good' state) — or the 'tries left' counter reaches
352 zero (in which case it will be in 'bad' state).
353 Example: let's say a boot loader entry file foo.conf is set up for 3
355 boot tries. The installer will hence create it under the name
356 foo+3.conf. On first boot, the boot loader will rename it to
357 foo+2-1.conf. If that boot does not complete successfully, the boot
358 loader will rename it to foo+1-2.conf on the following boot. If that
359 fails too, it will finally be renamed foo+0-3.conf by the boot loader
360 on next boot, after which it will be considered 'bad'. If the boot
361 succeeds however the entry file will be renamed to foo.conf by the OS,
362 so that it is considered 'good' from then on.
363 The boot menu takes the 'tries left' counter into account when sorting
365 the menu entries: entries in 'bad' state are ordered at the beginning
366 of the list, and entries in 'good' or 'indeterminate' at the end. The
367 user can freely choose to boot any entry of the menu, including those
368 already marked 'bad'. If the menu entry to boot is automatically
369 determined, this means that 'good' or 'indeterminate' entries are
370 generally preferred (as the bottom item of the menu is the one booted
371 by default), and 'bad' entries will only be considered if there are no
372 'good' or 'indeterminate' entries left.
373 The kernel-install(8) kernel install framework optionally sets the
375 initial 'tries left' counter to the value specified in
376 /etc/kernel/tries when a boot loader entry is first created.
377
379 bootctl(1), loader.conf(5), systemd-bless-boot.service(8), systemd-
380 boot-system-token.service(8), kernel-install(8), systemd-stub(7), Boot
381 Loader Specification[1], Boot Loader Interface[2]
382
384 1. Boot Loader Specification
385 https://systemd.io/BOOT_LOADER_SPECIFICATION
386 2. Boot Loader Interface
388 https://systemd.io/BOOT_LOADER_INTERFACE
389 3. Automatic Boot Assessment
391 https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
392 4. Random Seeds
394 https://systemd.io/RANDOM_SEEDS
395systemd 251 SYSTEMD-BOOT(7)