1SYSTEMD-BOOT(7)                  systemd-boot                  SYSTEMD-BOOT(7)
2
3
4

NAME

6       systemd-boot, sd-boot - A simple UEFI boot manager
7

DESCRIPTION

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
14       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
24       •   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
30       •   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
34       •   The Microsoft Windows EFI boot manager, if installed
35
36       •   The Apple macOS boot manager, if installed
37
38       •   The EFI Shell binary, if installed
39
40       •   A reboot into the UEFI firmware setup option, if supported by the
41           firmware
42
43       systemd-boot supports the following features:
44
45       •   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
50       •   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
57       •   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
63       •   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
67       •   The boot manager implements boot counting and automatic fallback to
68           older, working boot entries on failure. See Automatic Boot
69           Assessment[3].
70
71       •   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
77       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
81       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
85       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

KEY BINDINGS

92       The following keys may be used in the boot menu:
93
94       ↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End
95           Navigate up/down in the entry list
96
97       ↵ (Enter), → (Right)
98           Boot selected entry
99
100       d
101           Make selected entry the default
102
103       e
104           Edit the kernel command line for selected entry
105
106       +, t
107           Increase the timeout before default entry is booted
108
109       -, T
110           Decrease the timeout
111
112       r
113           Change screen resolution, skipping any unsupported modes.
114
115       R
116           Reset screen resolution to firmware or configuration file default.
117
118       p
119           Print status
120
121       h, ?, F1
122           Show a help screen
123
124       f
125           Reboot into firmware interface.
126
127           For compatibility with the keybindings of several firmware
128           implementations this operation may also be reached with F2, F10,
129           Del and Esc.
130
131       The following keys may be pressed during bootup or in the boot menu to
132       directly boot a specific entry:
133
134       l
135           Linux
136
137       w
138           Windows
139
140       a
141           macOS
142
143       s
144           EFI shell
145
146       1, 2, 3, 4, 5, 6, 7, 8, 9
147           Boot entry number 1 ... 9
148
149       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
165       In the editor, most keys simply insert themselves, but the following
166       keys may be used to perform additional actions:
167
168       ← (Left), → (Right), Home, End
169           Navigate left/right
170
171       Esc
172           Abort the edit and quit the editor
173
174       Ctrl+k
175           Clear the command line
176
177       Ctrl+w, Alt+Backspace
178           Delete word backwards
179
180       Alt+d
181           Delete word forwards
182
183       ↵ (Enter)
184           Boot entry with the edited command line
185
186       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

FILES

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
196       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
200       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
204       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
208       Optionally, a random seed for early boot entropy pool provisioning is
209       stored in /loader/random-seed in the ESP.
210
211       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

EFI VARIABLES

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
223       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
230       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
238       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
245       LoaderEntries
246           A list of the identifiers of all discovered boot loader entries.
247           Set by the boot loader.
248
249       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
258       LoaderEntrySelected
259           The identifier of the boot loader entry currently being booted. Set
260           by the boot loader.
261
262       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
266       LoaderFirmwareInfo, LoaderFirmwareType
267           Brief firmware information. Set by the boot loader. Use bootctl(1)
268           to view this data.
269
270       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
275       LoaderInfo
276           Brief information about the boot loader. Set by the boot loader.
277           Use bootctl(1) to view this data.
278
279       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
284       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
305           See Random Seeds[4] for further information.
306
307       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
313       Many of these variables are defined by the Boot Loader Interface[2].
314

BOOT COUNTING

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
329        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
334        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
340        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
347       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
354       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
364       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
374       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

SEE ALSO

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

NOTES

384        1. Boot Loader Specification
385           https://systemd.io/BOOT_LOADER_SPECIFICATION
386
387        2. Boot Loader Interface
388           https://systemd.io/BOOT_LOADER_INTERFACE
389
390        3. Automatic Boot Assessment
391           https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
392
393        4. Random Seeds
394           https://systemd.io/RANDOM_SEEDS
395
396
397
398systemd 250                                                    SYSTEMD-BOOT(7)
Impressum