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 X 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 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 · 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 · The boot manager implements boot counting and automatic fallback to
67 older, working boot entries on failure. See Automatic Boot
68 Assessment[3].
69 · 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 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 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
85 The following keys may be used in the boot menu:
86 ↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End
88 Navigate up/down in the entry list
89 ↵ (Enter)
91 Boot selected entry
92 d
94 Make selected entry the default
95 e
97 Edit the kernel command line for selected entry
98 +, t
100 Increase the timeout before default entry is booted
101 -, T
103 Decrease the timeout
104 v
106 Show systemd-boot, UEFI, and firmware versions
107 P
109 Print status
110 Q
112 Quit
113 h, ?
115 Show a help screen
116 Ctrl+l
118 Reprint the screen
119 The following keys may be used during bootup or in the boot menu to
121 directly boot a specific entry:
122 l
124 Linux
125 w
127 Windows
128 a
130 OS X
131 s
133 EFI shell
134 1, 2, 3, 4, 5, 6, 7, 8, 9
136 Boot entry number 1 ... 9
137 In the editor, most keys simply insert themselves, but the following
139 keys may be used to perform additional actions:
140 ← (Left), → (Right), Home, End
142 Navigate left/right
143 Esc
145 Abort the edit and quit the editor
146 Ctrl+k
148 Clear the command line
149 Ctrl+w, Alt+Backspace
151 Delete word backwards
152 Alt+d
154 Delete word forwards
155 ↵ (Enter)
157 Boot entry with the edited command line
158 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
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
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 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 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 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 LoaderEntries
206 A list of the identifiers of all discovered boot loader entries.
207 Set by the boot loader.
208 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 LoaderEntrySelected
219 The identifier of the boot loader entry currently being booted. Set
220 by the boot loader.
221 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 LoaderFirmwareInfo, LoaderFirmwareType
227 Brief firmware information. Set by the boot loader. Use bootctl(1)
228 to view this data.
229 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 LoaderInfo
236 Brief information about the boot loader. Set by the boot loader.
237 Use bootctl(1) to view this data.
238 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 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 See Random Seeds[4] for further information.
266 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 Many of these variables are defined by the Boot Loader Interface[2].
274
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 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 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 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 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 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 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 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
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
344 1. Boot Loader Specification
345 https://systemd.io/BOOT_LOADER_SPECIFICATION
346 2. Boot Loader Interface
348 https://systemd.io/BOOT_LOADER_INTERFACE
349 3. Automatic Boot Assessment
351 https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT
352 4. Random Seeds
354 https://systemd.io/RANDOM_SEEDS
355systemd 243 SYSTEMD-BOOT(7)