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 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
86 The following keys may be used in the boot menu:
87 ↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End
89 Navigate up/down in the entry list
90 ↵ (Enter), → (Right)
92 Boot selected entry
93 d
95 Make selected entry the default
96 e
98 Edit the kernel command line for selected entry
99 +, t
101 Increase the timeout before default entry is booted
102 -, T
104 Decrease the timeout
105 v
107 Show systemd-boot, UEFI, and firmware versions
108 P
110 Print status
111 Q
113 Quit
114 h, ?, F1
116 Show a help screen
117 Ctrl+l
119 Reprint the screen
120 The following keys may be pressed during bootup or in the boot menu to
122 directly boot a specific entry:
123 l
125 Linux
126 w
128 Windows
129 a
131 macOS
132 s
134 EFI shell
135 1, 2, 3, 4, 5, 6, 7, 8, 9
137 Boot entry number 1 ... 9
138 The boot menu is shown when a non-zero menu timeout has been
140 configured. If the menu timeout has been set to zero, it is sufficient
141 to press any key — before the boot loader initializes — to bring up the
142 boot menu, except for the keys listed immediately above as they
143 directly boot into the selected boot menu item. Note that depending on
144 the firmware implementation the time window where key presses are
145 accepted before the boot loader initializes might be short. If the
146 window is missed, reboot and try again, possibly pressing a suitable
147 key (e.g. the space bar) continuously; on most systems it should be
148 possible to hit the time window after a few attempts. To avoid this
149 problem, consider setting a non-zero timeout, thus showing the boot
150 menu unconditionally. Some desktop environments might offer an option
151 to directly boot into the boot menu, to avoid the problem altogether.
152 Alternatively, use the command line systemctl reboot
153 --boot-loader-menu=0 from the shell.
154 In the editor, most keys simply insert themselves, but the following
156 keys may be used to perform additional actions:
157 ← (Left), → (Right), Home, End
159 Navigate left/right
160 Esc
162 Abort the edit and quit the editor
163 Ctrl+k
165 Clear the command line
166 Ctrl+w, Alt+Backspace
168 Delete word backwards
169 Alt+d
171 Delete word forwards
172 ↵ (Enter)
174 Boot entry with the edited command line
175 Note that unless configured otherwise in the UEFI firmware,
177 systemd-boot will use the US keyboard layout, so key labels might not
178 match for keys like +/-.
179
181 The files systemd-boot processes generally reside on the UEFI ESP which
182 is usually mounted to /efi/, /boot/ or /boot/efi/ during OS runtime. It
183 also processes files on the Extended Boot Loader partition which is
184 typically mounted to /boot/, if it exists. systemd-boot reads runtime
185 configuration such as the boot timeout and default entry from
186 /loader/loader.conf on the ESP (in combination with data read from EFI
187 variables). See loader.conf(5). Boot entry description files following
188 the Boot Loader Specification[1] are read from /loader/entries/ on the
189 ESP and the Extended Boot Loader partition. Unified kernel boot entries
190 following the Boot Loader Specification[1] are read from /EFI/Linux/ on
191 the ESP and the Extended Boot Loader partition. Optionally, a random
192 seed for early boot entropy pool provisioning is stored in
193 /loader/random-seed in the ESP.
194
196 The following EFI variables are defined, set and read by systemd-boot,
197 under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f", for
198 communication between the OS and the boot loader:
199 LoaderBootCountPath
201 If boot counting is enabled, contains the path to the file in whose
202 name the boot counters are encoded. Set by the boot loader.
203 systemd-bless-boot.service(8) uses this information to mark a boot
204 as successful as determined by the successful activation of the
205 boot-complete.target target unit.
206 LoaderConfigTimeout, LoaderConfigTimeoutOneShot
208 The menu timeout in seconds. Read by the boot loader.
209 LoaderConfigTimeout is maintained persistently, while
210 LoaderConfigTimeoutOneShot is a one-time override which is read
211 once (in which case it takes precedence over LoaderConfigTimeout)
212 and then removed. LoaderConfigTimeout may be manipulated with the
213 t/T keys, see above.
214 LoaderDevicePartUUID
216 Contains the partition UUID of the EFI System Partition the boot
217 loader was run from. Set by the boot loader. systemd-gpt-auto-
218 generator(8) uses this information to automatically find the disk
219 booted from, in order to discover various other partitions on the
220 same disk automatically.
221 LoaderEntries
223 A list of the identifiers of all discovered boot loader entries.
224 Set by the boot loader.
225 LoaderEntryDefault, LoaderEntryOneShot
227 The identifier of the default boot loader entry. Set primarily by
228 the OS and read by the boot loader. LoaderEntryOneShot sets the
229 default entry for the next boot only, while LoaderEntryDefault sets
230 it persistently for all future boots. bootctl(1)'s set-default and
231 set-oneshot commands make use of these variables. The boot loader
232 modifies LoaderEntryDefault on request, when the d key is used, see
233 above.
234 LoaderEntrySelected
236 The identifier of the boot loader entry currently being booted. Set
237 by the boot loader.
238 LoaderFeatures
240 A set of flags indicating the features the boot loader supports.
241 Set by the boot loader. Use bootctl(1) to view this data.
242 LoaderFirmwareInfo, LoaderFirmwareType
244 Brief firmware information. Set by the boot loader. Use bootctl(1)
245 to view this data.
246 LoaderImageIdentifier
248 The path of executable of the boot loader used for the current
249 boot, relative to the EFI System Partition's root directory. Set by
250 the boot loader. Use bootctl(1) to view this data.
251 LoaderInfo
253 Brief information about the boot loader. Set by the boot loader.
254 Use bootctl(1) to view this data.
255 LoaderTimeExecUSec, LoaderTimeInitUSec, LoaderTimeMenuUsec
257 Information about the time spent in various parts of the boot
258 loader. Set by the boot loader. Use systemd-analyze(1) to view this
259 data.
260 LoaderRandomSeed
262 A binary random seed systemd-boot may optionally pass to the OS.
263 This is a volatile EFI variable that is hashed at boot from the
264 combination of a random seed stored in the ESP (in
265 /loader/random-seed) and a "system token" persistently stored in
266 the EFI variable LoaderSystemToken (see below). During early OS
267 boot the system manager reads this variable and passes it to the OS
268 kernel's random pool, crediting the full entropy it contains. This
269 is an efficient way to ensure the system starts up with a fully
270 initialized kernel random pool — as early as the initial RAM disk
271 phase. systemd-boot reads the random seed from the ESP, combines
272 it with the "system token", and both derives a new random seed to
273 update in-place the seed stored in the ESP, and the random seed to
274 pass to the OS from it via SHA256 hashing in counter mode. This
275 ensures that different physical systems that boot the same "golden"
276 OS image — i.e. containing the same random seed file in the ESP —
277 will still pass a different random seed to the OS. It is made sure
278 the random seed stored in the ESP is fully overwritten before the
279 OS is booted, to ensure different random seed data is used between
280 subsequent boots.
281 See Random Seeds[4] for further information.
283 LoaderSystemToken
285 A binary random data field, that is used for generating the random
286 seed to pass to the OS (see above). Note that this random data is
287 generally only generated once, during OS installation, and is then
288 never updated again.
289 Many of these variables are defined by the Boot Loader Interface[2].
291
293 systemd-boot implements a simple boot counting mechanism on top of the
294 Boot Loader Specification[1], for automatic and unattended fallback to
295 older kernel versions/boot loader entries when a specific entry
296 continuously fails. Any boot loader entry file and unified kernel image
297 file that contains a "+" followed by one or two numbers (if two they
298 need to be separated by a "-"), before the .conf or .efi suffix is
299 subject to boot counting: the first of the two numbers ('tries left')
300 is decreased by one on every boot attempt, the second of the two
301 numbers ('tries done') is increased by one (if 'tries done' is absent
302 it is considered equivalent to 0). Depending on the current value of
303 these two counters the boot entry is considered to be in one of three
304 states:
305 1. If the 'tries left' counter of an entry is greater than zero the
307 entry is considered to be in 'indeterminate' state. This means the
308 entry has not completed booting successfully yet, but also hasn't
309 been determined not to work.
310 2. If the 'tries left' counter of an entry is zero it is considered to
312 be in 'bad' state. This means no further attempts to boot this item
313 will be made (that is, unless all other boot entries are also in
314 'bad' state), as all attempts to boot this entry have not completed
315 successfully.
316 3. If the 'tries left' and 'tries done' counters of an entry are
318 absent it is considered to be in 'good' state. This means further
319 boot counting for the entry is turned off, as it successfully
320 booted at least once. The systemd-bless-boot.service(8) service
321 moves the currently booted entry from 'indeterminate' into 'good'
322 state when a boot attempt completed successfully.
323 Generally, when new entries are added to the boot loader, they first
325 start out in 'indeterminate' state, i.e. with a 'tries left' counter
326 greater than zero. The boot entry remains in this state until either it
327 managed to complete a full boot successfully at least once (in which
328 case it will be in 'good' state) — or the 'tries left' counter reaches
329 zero (in which case it will be in 'bad' state).
330 Example: let's say a boot loader entry file foo.conf is set up for 3
332 boot tries. The installer will hence create it under the name
333 foo+3.conf. On first boot, the boot loader will rename it to
334 foo+2-1.conf. If that boot does not complete successfully, the boot
335 loader will rename it to foo+1-2.conf on the following boot. If that
336 fails too, it will finally be renamed foo+0-3.conf by the boot loader
337 on next boot, after which it will be considered 'bad'. If the boot
338 succeeds however the entry file will be renamed to foo.conf by the OS,
339 so that it is considered 'good' from then on.
340 The boot menu takes the 'tries left' counter into account when sorting
342 the menu entries: entries in 'bad' state are ordered at the beginning
343 of the list, and entries in 'good' or 'indeterminate' at the end. The
344 user can freely choose to boot any entry of the menu, including those
345 already marked 'bad'. If the menu entry to boot is automatically
346 determined, this means that 'good' or 'indeterminate' entries are
347 generally preferred (as the bottom item of the menu is the one booted
348 by default), and 'bad' entries will only be considered if there are no
349 'good' or 'indeterminate' entries left.
350 The kernel-install(8) kernel install framework optionally sets the
352 initial 'tries left' counter to the value specified in
353 /etc/kernel/tries when a boot loader entry is first created.
354
356 bootctl(1), loader.conf(5), systemd-bless-boot.service(8), systemd-
357 boot-system-token.service(8), kernel-install(8), Boot Loader
358 Specification[1], Boot Loader Interface[2]
359
361 1. Boot Loader Specification
362 https://systemd.io/BOOT_LOADER_SPECIFICATION
363 2. Boot Loader Interface
365 https://systemd.io/BOOT_LOADER_INTERFACE
366 3. Automatic Boot Assessment
368 https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
369 4. Random Seeds
371 https://systemd.io/RANDOM_SEEDS
372systemd 249 SYSTEMD-BOOT(7)