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 persistant
72           EFI variable and derives a random seed to use by the OS as entropy
73           pool initializaton, 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)
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, ?
115           Show a help screen
116
117       Ctrl+l
118           Reprint the screen
119
120       The following keys may be used 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       In the editor, most keys simply insert themselves, but the following
139       keys may be used to perform additional actions:
140
141       ← (Left), → (Right), Home, End
142           Navigate left/right
143
144       Esc
145           Abort the edit and quit the editor
146
147       Ctrl+k
148           Clear the command line
149
150       Ctrl+w, Alt+Backspace
151           Delete word backwards
152
153       Alt+d
154           Delete word forwards
155
156       ↵ (Enter)
157           Boot entry with the edited command line
158
159       Note that unless configured otherwise in the UEFI firmware,
160       systemd-boot will use the US keyboard layout, so key labels might not
161       match for keys like +/-.
162

FILES

164       The files systemd-boot processes generally reside on the UEFI ESP which
165       is usually mounted to /efi/, /boot/ or /boot/efi/ during OS runtime. It
166       also processes files on the Extended Boot Loader partition which is
167       typically mounted to /boot/, if it exists.  systemd-boot reads runtime
168       configuration such as the boot timeout and default entry from
169       /loader/loader.conf on the ESP (in combination with data read from EFI
170       variables). See loader.conf(5). Boot entry description files following
171       the Boot Loader Specification[1] are read from /loader/entries/ on the
172       ESP and the Extended Boot Loader partition. Unified kernel boot entries
173       following the Boot Loader Specification[1] are read from /EFI/Linux/ on
174       the ESP and the Extended Boot Loader partition. Optionally, a random
175       seed for early boot entropy pool provisioning is stored in
176       /loader/random-seed in the ESP.
177

EFI VARIABLES

179       The following EFI variables are defined, set and read by systemd-boot,
180       under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4", for
181       communication between the OS and the boot loader:
182
183       LoaderBootCountPath
184           If boot counting is enabled, contains the path to the file in whose
185           name the boot counters are encoded. Set by the boot loader.
186           systemd-bless-boot.service(8) uses this information to mark a boot
187           as successful as determined by the successful activation of the
188           boot-complete.target target unit.
189
190       LoaderConfigTimeout, LoaderConfigTimeoutOneShot
191           The menu timeout in seconds. Read by the boot loader.
192           LoaderConfigTimeout is maintained persistently, while
193           LoaderConfigTimeoutOneShot is a one-time override which is read
194           once (in which case it takes precedence over LoaderConfigTimeout)
195           and then removed.  LoaderConfigTimeout may be manipulated with the
196           t/T keys, see above.)
197
198       LoaderDevicePartUUID
199           Contains the partition UUID of the EFI System Partition the boot
200           loader was run from. Set by the boot loader.  systemd-gpt-auto-
201           generator(8) uses this information to automatically find the disk
202           booted from, in order to discover various other partitions on the
203           same disk automatically.
204
205       LoaderEntries
206           A list of the identifiers of all discovered boot loader entries.
207           Set by the boot loader.
208
209       LoaderEntryDefault, LoaderEntryOneShot
210           The identifier of the default boot loader entry. Set primarily by
211           the OS and read by the boot loader.  LoaderEntryOneShot sets the
212           default entry for the next boot only, while LoaderEntryDefault sets
213           it persistently for all future boots.  bootctl(1)'s set-default and
214           set-oneshot commands make use of these variables. The boot loader
215           modifies LoaderEntryDefault on request, when the d key is used, see
216           above.)
217
218       LoaderEntrySelected
219           The identifier of the boot loader entry currently being booted. Set
220           by the boot loader.
221
222       LoaderFeatures
223           A set of flags indicating the features the boot loader supports.
224           Set by the boot loader. Use bootctl(1) to view this data.
225
226       LoaderFirmwareInfo, LoaderFirmwareType
227           Brief firmware information. Set by the boot loader. Use bootctl(1)
228           to view this data.
229
230       LoaderImageIdentifier
231           The path of executable of the boot loader used for the current
232           boot, relative to the EFI System Partition's root directory. Set by
233           the boot loader. Use bootctl(1) to view this data.
234
235       LoaderInfo
236           Brief information about the boot loader. Set by the boot loader.
237           Use bootctl(1) to view this data.
238
239       LoaderTimeExecUSec, LoaderTimeInitUSec, LoaderTimeMenuUsec
240           Information about the time spent in various parts of the boot
241           loader. Set by the boot loader. Use systemd-analyze(1) to view this
242           data.
243
244       LoaderRandomSeed
245           A binary random seed systemd-boot may optionally pass to the OS.
246           This is a volatile EFI variable that is hashed at boot from the
247           combination of a random seed stored in the ESP (in
248           /loader/random-seed) and a "system token" persistently stored in
249           the EFI variable LoaderSystemToken (see below). During early OS
250           boot the system manager reads this variable and passes it to the OS
251           kernel's random pool, crediting the full entropy it contains. This
252           is an efficient way to ensure the system starts up with a fully
253           initialized kernel random pool — as early as the initial RAM disk
254           phase.  systemd-boot reads the random seed from the ESP, combines
255           it with the "system token", and both derives a new random seed to
256           update in-place the seed stored in the ESP, and the random seed to
257           pass to the OS from it via SHA256 hashing in counter mode. This
258           ensures that different physical systems that boot the same "golden"
259           OS image — i.e. containing the same random seed file in the ESP —
260           will still pass a different random seed to the OS. It is made sure
261           the random seed stored in the ESP is fully overwritten before the
262           OS is booted, to ensure different random seed data is used between
263           subsequent boots.
264
265           See Random Seeds[4] for further information.
266
267       LoaderSystemToken
268           A binary random data field, that is used for generating the random
269           see to pass to the OS (see above). Note that this random data is
270           generally only generated once, during OS installation, and is then
271           never updated again.
272
273       Many of these variables are defined by the Boot Loader Interface[2].
274

BOOT COUNTING

276       systemd-boot implements a simple boot counting mechanism on top of the
277       Boot Loader Specification[1], for automatic and unattended fallback to
278       older kernel versions/boot loader entries when a specific entry
279       continuously fails. Any boot loader entry file and unified kernel image
280       file that contains a "+" followed by one or two numbers (if two they
281       need to be separated by a "-"), before the .conf or .efi suffix is
282       subject to boot counting: the first of the two numbers ('tries left')
283       is decreased by one on every boot attempt, the second of the two
284       numbers ('tries done') is increased by one (if 'tries done' is absent
285       it is considered equivalent to 0). Depending on the current value of
286       these two counters the boot entry is considered to be in one of three
287       states:
288
289        1. If the 'tries left' counter of an entry is greater than zero the
290           entry is considered to be in 'indeterminate' state. This means the
291           entry has not completed booting successfully yet, but also hasn't
292           been determined not to work.
293
294        2. If the 'tries left' counter of an entry is zero it is considered to
295           be in 'bad' state. This means no further attempts to boot this item
296           will be made (that is, unless all other boot entries are also in
297           'bad' state), as all attempts to boot this entry have not completed
298           successfully.
299
300        3. If the 'tries left' and 'tries done' counters of an entry are
301           absent it is considered to be in 'good' state. This means further
302           boot counting for the entry is turned off, as it successfully
303           booted at least once. The systemd-bless-boot.service(8) service
304           moves the currently booted entry from 'indeterminate' into 'good'
305           state when a boot attempt completed successfully.
306
307       Generally, when new entries are added to the boot loader, they first
308       start out in 'indeterminate' state, i.e. with a 'tries left' counter
309       greater than zero. The boot entry remains in this state until either it
310       managed to complete a full boot successfully at least once (in which
311       case it will be in 'good' state) — or the 'tries left' counter reaches
312       zero (in which case it will be in 'bad' state).
313
314       Example: let's say a boot loader entry file foo.conf is set up for 3
315       boot tries. The installer will hence create it under the name
316       foo+3.conf. On first boot, the boot loader will rename it to
317       foo+2-1.conf. If that boot does not complete successfully, the boot
318       loader will rename it to foo+1-2.conf on the following boot. If that
319       fails too, it will finally be renamed foo+0-3.conf by the boot loader
320       on next boot, after which it will be considered 'bad'. If the boot
321       succeeds however the entry file will be renamed to foo.conf by the OS,
322       so that it is considered 'good' from then on.
323
324       The boot menu takes the 'tries left' counter into account when sorting
325       the menu entries: entries in 'bad' state are ordered at the end of the
326       list, and entries in 'good' or 'indeterminate' at the beginning. The
327       user can freely choose to boot any entry of the menu, including those
328       already marked 'bad'. If the menu entry to boot is automatically
329       determined, this means that 'good' or 'indeterminate' entries are
330       generally preferred (as the top item of the menu is the one booted by
331       default), and 'bad' entries will only be considered if there are no
332       'good' or 'indeterminate' entries left.
333
334       The kernel-install(8) kernel install framework optionally sets the
335       initial 'tries left' counter to the value specified in
336       /etc/kernel/tries when a boot loader entry is first created.
337

SEE ALSO

339       bootctl(1), loader.conf(5), systemd-bless-boot.service(8), systemd-
340       boot-system-token.service(8), kernel-install(8), Boot Loader
341       Specification[1], Boot Loader Interface[2]
342

NOTES

344        1. Boot Loader Specification
345           https://systemd.io/BOOT_LOADER_SPECIFICATION
346
347        2. Boot Loader Interface
348           https://systemd.io/BOOT_LOADER_INTERFACE
349
350        3. Automatic Boot Assessment
351           https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
352
353        4. Random Seeds
354           https://systemd.io/RANDOM_SEEDS
355
356
357
358systemd 243                                                    SYSTEMD-BOOT(7)
Impressum