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 /boot, /efi, or /boot/efi during OS runtime.
16 Configuration file fragments, kernels, initrds and other EFI images to
17 boot generally need to reside on the ESP. Linux kernels must be built
18 with CONFIG_EFI_STUB to be able to be directly executed as an EFI
19 image. During boot systemd-boot automatically assembles a list of boot
20 entries from the following sources:
21 · Boot entries defined with Boot Loader Specification[1] description
23 files located in /loader/entries/ on the ESP. These usually
24 describe Linux kernel images with associated initrd images, but
25 alternatively may also describe arbitrary other EFI executables.
26 · Unified kernel images following the Boot Loader Specification[1],
28 as executable EFI binaries in /EFI/Linux/ on the ESP.
29 · The Microsoft Windows EFI boot manager, if installed
31 · The Apple MacOS X boot manager, if installed
33 · The EFI Shell binary, if installed
35 · A reboot into the UEFI firmware setup option, if supported by the
37 firmware
38 kernel-install(8) may be used to copy kernel images onto the ESP and to
40 generate description files compliant with the Boot Loader
41 Specification. bootctl(1) may be used from a running system to locate
42 the ESP, list available entries, and install systemd-boot itself.
43 systemd-boot will provide information about the time spent in UEFI
45 firmware using the Boot Loader Interface[2]. This information can be
46 displayed using systemd-analyze(1).
47
49 The following keys may be used in the boot menu:
50 ↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End
52 Navigate up/down in the entry list
53 ↵ (Enter)
55 Boot selected entry
56 d
58 Make selected entry the default
59 e
61 Edit the kernel command line for selected entry
62 +, t
64 Increase the timeout before default entry is booted
65 -, T
67 Decrease the timeout
68 v
70 Show systemd-boot, UEFI, and firmware versions
71 P
73 Print status
74 Q
76 Quit
77 h, ?
79 Show a help screen
80 Ctrl+l
82 Reprint the screen
83 The following keys may be used during bootup or in the boot menu to
85 directly boot a specific entry:
86 l
88 Linux
89 w
91 Windows
92 a
94 OS X
95 s
97 EFI shell
98 1, 2, 3, 4, 5, 6, 7, 8, 9
100 Boot entry number 1 ... 9
101 In the editor, most keys simply insert themselves, but the following
103 keys may be used to perform additional actions:
104 ← (Left), → (Right), Home, End
106 Navigate left/right
107 Esc
109 Abort the edit and quit the editor
110 Ctrl+k
112 Clear the command line
113 Ctrl+w, Alt+Backspace
115 Delete word backwards
116 Alt+d
118 Delete word forwards
119 ↵ (Enter)
121 Boot entry with the edited command line
122 Note that unless configured otherwise in the UEFI firmware,
124 systemd-boot will use the US keyboard layout, so key labels might not
125 match for keys like +/-.
126
128 The files systemd-boot reads generally reside on the UEFI ESP which is
129 usually mounted to /boot/, /efi/ or /boot/efi during OS runtime.
130 systemd-boot reads runtime configuration such as the boot timeout and
131 default entry from /loader/loader.conf on the ESP (in combination with
132 data read from EFI variables). See loader.conf(5). Boot entry
133 description files following the Boot Loader Specification[1] are read
134 from /loader/entries/ on the ESP. Unified kernel boot entries following
135 the Boot Loader Specification[1] are read from /EFI/Linux/ on the ESP.
136
138 The following EFI variables are defined, set and read by systemd-boot,
139 under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4", for
140 communication between the OS and the boot loader:
141 LoaderBootCountPath
143 If boot counting is enabled, contains the path to the file in whose
144 name the boot counters are encoded. Set by the boot loader.
145 systemd-bless-boot.service(8) uses this information to mark a boot
146 as successful as determined by the successful activation of the
147 boot-complete.target target unit.
148 LoaderConfigTimeout, LoaderConfigTimeoutOneShot
150 The menu timeout in seconds. Read by the boot loader.
151 LoaderConfigTimeout is maintained persistently, while
152 LoaderConfigTimeoutOneShot is a one-time override which is read
153 once (in which case it takes precedence over LoaderConfigTimeout)
154 and then removed. LoaderConfigTimeout may be manipulated with the
155 t/T keys, see above.)
156 LoaderDevicePartUUID
158 Contains the partition UUID of the EFI System Partition the boot
159 loader was run from. Set by the boot loader. systemd-gpt-auto-
160 generator(8) uses this information to automatically find the disk
161 booted from, in order to discover various other partitions on the
162 same disk automatically.
163 LoaderEntries
165 A list of the identifiers of all discovered boot loader entries.
166 Set by the boot loader.
167 LoaderEntryDefault, LoaderEntryOneShot
169 The identifier of the default boot loader entry. Set primarily by
170 the OS and read by the boot loader. LoaderEntryOneShot sets the
171 default entry for the next boot only, while LoaderEntryDefault sets
172 it persistently for all future boots. bootctl(1)'s set-default and
173 set-oneshot commands make use of these variables. The boot loader
174 modifies LoaderEntryDefault on request, when the d key is used, see
175 above.)
176 LoaderEntrySelected
178 The identifier of the boot loader entry currently being booted. Set
179 by the boot loader.
180 LoaderFeatures
182 A set of flags indicating the features the boot loader supports.
183 Set by the boot loader. Use bootctl(1) to view this data.
184 LoaderFirmwareInfo, LoaderFirmwareType
186 Brief firmware information. Set by the boot loader. Use bootctl(1)
187 to view this data.
188 LoaderImageIdentifier
190 The path of executable of the boot loader used for the current
191 boot, relative to the EFI System Partition's root directory. Set by
192 the boot loader. Use bootctl(1) to view this data.
193 LoaderInfo
195 Brief information about the boot loader. Set by the boot loader.
196 Use bootctl(1) to view this data.
197 LoaderTimeExecUSec, LoaderTimeInitUSec, LoaderTimeMenuUsec
199 Information about the time spent in various parts of the boot
200 loader. Set by the boot loader. Use systemd-analyze(1) to view this
201 data. These variables are defined by the Boot Loader Interface[2].
202
204 systemd-boot implements a simple boot counting mechanism on top of the
205 Boot Loader Specification[1], for automatic and unattended fallback to
206 older kernel versions/boot loader entries when a specific entry
207 continously fails. Any boot loader entry file and unified kernel image
208 file that contains a "+" followed by one or two numbers (if two they
209 need to be separated by a "-"), before the .conf or .efi suffix is
210 subject to boot counting: the first of the two numbers ('tries left')
211 is decreased by one on every boot attempt, the second of the two
212 numbers ('tries done') is increased by one (if 'tries done' is absent
213 it is considered equivalent to 0). Depending on the current value of
214 these two counters the boot entry is considered to be in one of three
215 states:
216 1. If the 'tries left' counter of an entry is greater than zero the
218 entry is considered to be in 'indeterminate' state. This means the
219 entry has not completed booting successfully yet, but also hasn't
220 been determined not to work.
221 2. If the 'tries left' counter of an entry is zero it is considered to
223 be in 'bad' state. This means no further attempts to boot this item
224 will be made (that is, unless all other boot entries are also in
225 'bad' state), as all attempts to boot this entry have not completed
226 successfully.
227 3. If the 'tries left' and 'tries done' counters of an entry are
229 absent it is considered to be in 'good' state. This means further
230 boot counting for the entry is turned off, as it successfully
231 booted at least once. The systemd-bless-boot.service(8) service
232 moves the currently booted entry from 'indeterminate' into 'good'
233 state when a boot attempt completed successfully.
234 Generally, when new entries are added to the boot loader, they first
236 start out in 'indeterminate' state, i.e. with a 'tries left' counter
237 greater than zero. The boot entry remains in this state until either it
238 managed to complete a full boot successfully at least once (in which
239 case it will be in 'good' state) — or the 'tries left' counter reaches
240 zero (in which case it will be in 'bad' state).
241 Example: let's say a boot loader entry file foo.conf is set up for 3
243 boot tries. The installer will hence create it under the name
244 foo+3.conf. On first boot, the boot loader will rename it to
245 foo+2-1.conf. If that boot does not complete successfully, the boot
246 loader will rename it to foo+1-2.conf on the following boot. If that
247 fails too, it will finally be renamed foo+0-3.conf by the boot loader
248 on next boot, after which it will be considered 'bad'. If the boot
249 succeeds however the entry file will be renamed to foo.conf by the OS,
250 so that it is considered 'good' from then on.
251 The boot menu takes the 'tries left' counter into account when sorting
253 the menu entries: entries in 'bad' state are ordered at the end of the
254 list, and entries in 'good' or 'indeterminate' at the beginning. The
255 user can freely choose to boot any entry of the menu, including those
256 already marked 'bad'. If the menu entry to boot is automatically
257 determined, this means that 'good' or 'indeterminate' entries are
258 generally preferred (as the top item of the menu is the one booted by
259 default), and 'bad' entries will only be considered if there are no
260 'good' or 'indeterminate' entries left.
261 The kernel-install(8) kernel install framework optionally sets the
263 initial 'tries left' counter to the value specified in
264 /etc/kernel/tries when a boot loader entry is first created.
265
267 bootctl(1), loader.conf(5), systemd-bless-boot.service(8), kernel-
268 install(8), Boot Loader Specification[1], Boot Loader Interface[2]
269
271 1. Boot Loader Specification
272 https://systemd.io/BOOT_LOADER_SPECIFICATION
273 2. Boot Loader Interface
275 https://systemd.io/BOOT_LOADER_INTERFACE
276systemd 241 SYSTEMD-BOOT(7)