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 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
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 X 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 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
62       ·   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
66       ·   The boot manager implements boot counting and automatic fallback to
67           older, working boot entries on failure. See Automatic Boot
68           Assessment[3].
69
70       ·   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
76       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
80       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

KEY BINDINGS

85       The following keys may be used in the boot menu:
86
87       ↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End
88           Navigate up/down in the entry list
89
90       ↵ (Enter), → (Right)
91           Boot selected entry
92
93       d
94           Make selected entry the default
95
96       e
97           Edit the kernel command line for selected entry
98
99       +, t
100           Increase the timeout before default entry is booted
101
102       -, T
103           Decrease the timeout
104
105       v
106           Show systemd-boot, UEFI, and firmware versions
107
108       P
109           Print status
110
111       Q
112           Quit
113
114       h, ?, F1
115           Show a help screen
116
117       Ctrl+l
118           Reprint the screen
119
120       The following keys may be pressed during bootup or in the boot menu to
121       directly boot a specific entry:
122
123       l
124           Linux
125
126       w
127           Windows
128
129       a
130           OS X
131
132       s
133           EFI shell
134
135       1, 2, 3, 4, 5, 6, 7, 8, 9
136           Boot entry number 1 ... 9
137
138       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
154       In the editor, most keys simply insert themselves, but the following
155       keys may be used to perform additional actions:
156
157       ← (Left), → (Right), Home, End
158           Navigate left/right
159
160       Esc
161           Abort the edit and quit the editor
162
163       Ctrl+k
164           Clear the command line
165
166       Ctrl+w, Alt+Backspace
167           Delete word backwards
168
169       Alt+d
170           Delete word forwards
171
172       ↵ (Enter)
173           Boot entry with the edited command line
174
175       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

FILES

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

EFI VARIABLES

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
199       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
206       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
214       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
221       LoaderEntries
222           A list of the identifiers of all discovered boot loader entries.
223           Set by the boot loader.
224
225       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
234       LoaderEntrySelected
235           The identifier of the boot loader entry currently being booted. Set
236           by the boot loader.
237
238       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
242       LoaderFirmwareInfo, LoaderFirmwareType
243           Brief firmware information. Set by the boot loader. Use bootctl(1)
244           to view this data.
245
246       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
251       LoaderInfo
252           Brief information about the boot loader. Set by the boot loader.
253           Use bootctl(1) to view this data.
254
255       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
260       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
281           See Random Seeds[4] for further information.
282
283       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
289       Many of these variables are defined by the Boot Loader Interface[2].
290

BOOT COUNTING

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
305        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
310        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
316        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
323       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
330       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
340       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
350       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

SEE ALSO

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

NOTES

360        1. Boot Loader Specification
361           https://systemd.io/BOOT_LOADER_SPECIFICATION
362
363        2. Boot Loader Interface
364           https://systemd.io/BOOT_LOADER_INTERFACE
365
366        3. Automatic Boot Assessment
367           https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
368
369        4. Random Seeds
370           https://systemd.io/RANDOM_SEEDS
371
372
373
374systemd 246                                                    SYSTEMD-BOOT(7)
Impressum