]>
Commit | Line | Data |
---|---|---|
f37d3835 | 1 | <?xml version='1.0'?> <!--*-nxml-*--> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
f37d3835 | 5 | |
dfca5587 | 6 | <refentry id="systemd-boot" conditional='ENABLE_BOOTLOADER' |
f37d3835 ZJS |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
8 | <refentryinfo> | |
70c8db75 | 9 | <title>systemd-boot</title> |
f37d3835 | 10 | <productname>systemd</productname> |
f37d3835 ZJS |
11 | </refentryinfo> |
12 | ||
13 | <refmeta> | |
70c8db75 | 14 | <refentrytitle>systemd-boot</refentrytitle> |
f37d3835 ZJS |
15 | <manvolnum>7</manvolnum> |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
70c8db75 | 19 | <refname>systemd-boot</refname> |
f37d3835 ZJS |
20 | <refname>sd-boot</refname> |
21 | <refpurpose>A simple UEFI boot manager</refpurpose> | |
22 | </refnamediv> | |
23 | ||
24 | <refsect1> | |
25 | <title>Description</title> | |
26 | ||
c5fcaed8 | 27 | <para><command>systemd-boot</command> (short: <command>sd-boot</command>) is a simple UEFI boot |
b8cdb662 | 28 | manager. It provides a textual menu to select the entry to boot and an editor for the kernel command |
c5fcaed8 | 29 | line. <command>systemd-boot</command> supports systems with UEFI firmware only.</para> |
53ddb667 | 30 | |
39867bb9 LP |
31 | <para><command>systemd-boot</command> loads boot entry information from the EFI system partition (ESP), |
32 | usually mounted at <filename>/efi/</filename>, <filename>/boot/</filename>, or | |
cafa9d87 LP |
33 | <filename>/boot/efi/</filename> during OS runtime, as well as from the Extended Boot Loader partition |
34 | (XBOOTLDR) if it exists (usually mounted to <filename>/boot/</filename>). Configuration file fragments, | |
35 | kernels, initrds and other EFI images to boot generally need to reside on the ESP or the Extended Boot | |
36 | Loader partition. Linux kernels must be built with <option>CONFIG_EFI_STUB</option> to be able to be | |
37 | directly executed as an EFI image. During boot <command>systemd-boot</command> automatically assembles a | |
38 | list of boot entries from the following sources:</para> | |
53ddb667 LP |
39 | |
40 | <itemizedlist> | |
41 | <listitem><para>Boot entries defined with <ulink | |
db811444 | 42 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> Type #1 |
a0aa3838 ZJS |
43 | description files located in <filename>/loader/entries/</filename> on the ESP and the Extended Boot |
44 | Loader Partition. These usually describe Linux kernel images with associated initrd images, but | |
45 | alternatively may also describe other arbitrary EFI executables.</para></listitem> | |
53ddb667 | 46 | |
db811444 | 47 | <listitem><para>Unified kernel images, <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot |
a0aa3838 ZJS |
48 | Loader Specification</ulink> Type #2, which are executable EFI binaries in |
49 | <filename>/EFI/Linux/</filename> on the ESP and the Extended Boot Loader Partition.</para></listitem> | |
53ddb667 | 50 | |
a0aa3838 | 51 | <listitem><para>The Microsoft Windows EFI boot manager, if installed.</para></listitem> |
53ddb667 | 52 | |
a0aa3838 | 53 | <listitem><para>The Apple macOS boot manager, if installed.</para></listitem> |
53ddb667 | 54 | |
a0aa3838 | 55 | <listitem><para>The EFI Shell binary, if installed.</para></listitem> |
53ddb667 | 56 | |
6ad3dc40 ZJS |
57 | <listitem><para>A <literal>Reboot Into Firmware Interface option</literal>, if supported by the UEFI |
58 | firmware.</para></listitem> | |
e6b0cfad | 59 | |
8b9f0921 | 60 | <listitem><para>Secure Boot variables enrollment if the UEFI firmware is in setup-mode and files are provided |
e6b0cfad | 61 | on the ESP.</para></listitem> |
53ddb667 LP |
62 | </itemizedlist> |
63 | ||
39867bb9 LP |
64 | <para><command>systemd-boot</command> supports the following features:</para> |
65 | ||
66 | <itemizedlist> | |
67 | <listitem><para>Basic boot manager configuration changes (such as timeout | |
68 | configuration, default boot entry selection, …) may be made directly from the boot loader UI at | |
69 | boot-time, as well as during system runtime with EFI variables.</para></listitem> | |
70 | ||
71 | <listitem><para>The boot manager integrates with the <command>systemctl</command> command to implement | |
72 | features such as <command>systemctl reboot --boot-loader-entry=…</command> (for rebooting into a | |
73 | specific boot menu entry, i.e. "reboot into Windows") and <command>systemctl reboot | |
74 | --boot-loader-menu=…</command> (for rebooting into the boot loader menu), by implementing the <ulink | |
75 | url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. See | |
76 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for | |
77 | details.</para></listitem> | |
78 | ||
250db1bf | 79 | <listitem><para>An EFI variable set by the boot loader informs the OS about the EFI System Partition used |
80 | during boot. This is then used to automatically mount the correct EFI System Partition to | |
39867bb9 LP |
81 | <filename>/efi/</filename> or <filename>/boot/</filename> during OS runtime. See |
82 | <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
83 | for details.</para></listitem> | |
84 | ||
85 | <listitem><para>The boot manager provides information about the boot time spent in UEFI firmware using | |
86 | the <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. This | |
87 | information can be displayed using | |
88 | <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>. | |
89 | </para></listitem> | |
90 | ||
91 | <listitem><para>The boot manager implements boot counting and automatic fallback to older, working boot | |
92 | entries on failure. See <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot | |
93 | Assessment</ulink>.</para></listitem> | |
94 | ||
95 | <listitem><para>The boot manager optionally reads a random seed from the ESP partition, combines it | |
11fcfc53 | 96 | with a 'system token' stored in a persistent EFI variable and derives a random seed to use by the OS as |
e9dd6984 | 97 | entropy pool initialization, providing a full entropy pool during early boot.</para></listitem> |
e6b0cfad | 98 | |
8b9f0921 | 99 | <listitem><para>The boot manager allows for Secure Boot variables to be enrolled if the UEFI firmware is |
e6b0cfad | 100 | in setup-mode. Additionally, variables can be automatically enrolled if configured.</para></listitem> |
39867bb9 LP |
101 | </itemizedlist> |
102 | ||
103 | <para><citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
c5fcaed8 LP |
104 | may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list |
105 | available entries, and install <command>systemd-boot</command> itself.</para> | |
53ddb667 | 106 | |
39867bb9 LP |
107 | <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
108 | may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate | |
109 | description files compliant with the Boot Loader | |
110 | Specification.</para> | |
3f9a615d LP |
111 | |
112 | <para><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
113 | may be used as UEFI boot stub for executed kernels, which is useful to show graphical boot splashes | |
114 | before transitioning into the Linux world. It is also capable of automatically picking up auxiliary | |
115 | credential files (for boot parameterization) and system extension images, as companion files to the | |
116 | booted kernel images.</para> | |
f37d3835 ZJS |
117 | </refsect1> |
118 | ||
f37d3835 ZJS |
119 | <refsect1> |
120 | <title>Key bindings</title> | |
121 | <para>The following keys may be used in the boot menu:</para> | |
122 | ||
8a8e5666 JJ |
123 | <!-- Developer commands Q/v/Ctrl+l deliberately not advertised. --> |
124 | ||
f37d3835 ZJS |
125 | <variablelist> |
126 | <varlistentry> | |
8c073dde LP |
127 | <term><keycap>↑</keycap> (Up)</term> |
128 | <term><keycap>↓</keycap> (Down)</term> | |
129 | <term><keycap>j</keycap></term> | |
130 | <term><keycap>k</keycap></term> | |
131 | <term><keycap>PageUp</keycap></term> | |
132 | <term><keycap>PageDown</keycap></term> | |
133 | <term><keycap>Home</keycap></term> | |
134 | <term><keycap>End</keycap></term> | |
ec07c3c8 AK |
135 | <listitem><para>Navigate up/down in the entry list</para> |
136 | ||
137 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
138 | </varlistentry> |
139 | ||
140 | <varlistentry> | |
8c073dde | 141 | <term><keycap>↵</keycap> (Enter)</term> |
904ebcb2 | 142 | <term><keycap>→</keycap> (Right)</term> |
ec07c3c8 AK |
143 | <listitem><para>Boot selected entry</para> |
144 | ||
aefdc112 | 145 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> |
f37d3835 ZJS |
146 | </varlistentry> |
147 | ||
148 | <varlistentry> | |
8c073dde | 149 | <term><keycap>d</keycap></term> |
ec07c3c8 AK |
150 | <listitem><para>Make selected entry the default</para> |
151 | ||
152 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
153 | </varlistentry> |
154 | ||
155 | <varlistentry> | |
8c073dde | 156 | <term><keycap>e</keycap></term> |
ec07c3c8 AK |
157 | <listitem><para>Edit the kernel command line for selected entry</para> |
158 | ||
159 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
160 | </varlistentry> |
161 | ||
162 | <varlistentry> | |
8c073dde LP |
163 | <term><keycap>+</keycap></term> |
164 | <term><keycap>t</keycap></term> | |
ec07c3c8 AK |
165 | <listitem><para>Increase the timeout before default entry is booted</para> |
166 | ||
167 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
168 | </varlistentry> |
169 | ||
170 | <varlistentry> | |
8c073dde LP |
171 | <term><keycap>-</keycap></term> |
172 | <term><keycap>T</keycap></term> | |
ec07c3c8 AK |
173 | <listitem><para>Decrease the timeout</para> |
174 | ||
175 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
176 | </varlistentry> |
177 | ||
1b965abc JJ |
178 | <varlistentry> |
179 | <term><keycap>r</keycap></term> | |
ec07c3c8 AK |
180 | <listitem><para>Change screen resolution, skipping any unsupported modes.</para> |
181 | ||
182 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
1b965abc JJ |
183 | </varlistentry> |
184 | ||
185 | <varlistentry> | |
186 | <term><keycap>R</keycap></term> | |
ec07c3c8 AK |
187 | <listitem><para>Reset screen resolution to firmware or configuration file default.</para> |
188 | ||
189 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
1b965abc JJ |
190 | </varlistentry> |
191 | ||
f37d3835 | 192 | <varlistentry> |
8a8e5666 | 193 | <term><keycap>p</keycap></term> |
ec07c3c8 AK |
194 | <listitem><para>Print status</para> |
195 | ||
196 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
f37d3835 ZJS |
197 | </varlistentry> |
198 | ||
f37d3835 | 199 | <varlistentry> |
8c073dde LP |
200 | <term><keycap>h</keycap></term> |
201 | <term><keycap>?</keycap></term> | |
a318a565 | 202 | <term><keycap>F1</keycap></term> |
aefdc112 AK |
203 | <listitem><para>Show a help screen</para> |
204 | ||
205 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 | 206 | </varlistentry> |
e6cab77e JJ |
207 | |
208 | <varlistentry> | |
209 | <term><keycap>f</keycap></term> | |
210 | <listitem><para>Reboot into firmware interface.</para> | |
211 | ||
212 | <para>For compatibility with the keybindings of several firmware implementations this operation | |
213 | may also be reached with <keycap>F2</keycap>, <keycap>F10</keycap>, <keycap>Del</keycap> and | |
ec07c3c8 AK |
214 | <keycap>Esc</keycap>.</para> |
215 | ||
216 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
e6cab77e | 217 | </varlistentry> |
f6531b11 LP |
218 | |
219 | <varlistentry> | |
220 | <term><keycombo><keycap>Shift</keycap><keycap>o</keycap></keycombo></term> | |
ec07c3c8 AK |
221 | <listitem><para>Power off the system.</para> |
222 | ||
223 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
f6531b11 LP |
224 | </varlistentry> |
225 | ||
226 | <varlistentry> | |
227 | <term><keycombo><keycap>Shift</keycap><keycap>b</keycap></keycombo></term> | |
ec07c3c8 AK |
228 | <listitem><para>Reboot the system.</para> |
229 | ||
230 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
f6531b11 | 231 | </varlistentry> |
f37d3835 ZJS |
232 | </variablelist> |
233 | ||
e14a0c21 LP |
234 | <para>The following keys may be pressed during bootup or in the boot menu to directly boot a specific |
235 | entry:</para> | |
f37d3835 ZJS |
236 | |
237 | <variablelist> | |
238 | <varlistentry> | |
8c073dde | 239 | <term><keycap>l</keycap></term> |
ec07c3c8 AK |
240 | <listitem><para>Linux</para> |
241 | ||
242 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
243 | </varlistentry> |
244 | ||
245 | <varlistentry> | |
8c073dde | 246 | <term><keycap>w</keycap></term> |
ec07c3c8 AK |
247 | <listitem><para>Windows</para> |
248 | ||
249 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
250 | </varlistentry> |
251 | ||
252 | <varlistentry> | |
8c073dde | 253 | <term><keycap>a</keycap></term> |
ec07c3c8 AK |
254 | <listitem><para>macOS</para> |
255 | ||
256 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
257 | </varlistentry> |
258 | ||
259 | <varlistentry> | |
8c073dde | 260 | <term><keycap>s</keycap></term> |
ec07c3c8 AK |
261 | <listitem><para>EFI shell</para> |
262 | ||
263 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
264 | </varlistentry> |
265 | ||
266 | <varlistentry> | |
8c073dde LP |
267 | <term><keycap>1</keycap></term> |
268 | <term><keycap>2</keycap></term> | |
269 | <term><keycap>3</keycap></term> | |
270 | <term><keycap>4</keycap></term> | |
271 | <term><keycap>5</keycap></term> | |
272 | <term><keycap>6</keycap></term> | |
273 | <term><keycap>7</keycap></term> | |
274 | <term><keycap>8</keycap></term> | |
275 | <term><keycap>9</keycap></term> | |
ec07c3c8 AK |
276 | <listitem><para>Boot entry number 1 … 9</para> |
277 | ||
278 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
279 | </varlistentry> |
280 | </variablelist> | |
281 | ||
e14a0c21 LP |
282 | <para>The boot menu is shown when a non-zero menu timeout has been configured. If the menu timeout has |
283 | been set to zero, it is sufficient to press any key — before the boot loader initializes — to bring up | |
284 | the boot menu, except for the keys listed immediately above as they directly boot into the selected boot | |
285 | menu item. Note that depending on the firmware implementation the time window where key presses are | |
286 | accepted before the boot loader initializes might be short. If the window is missed, reboot and try | |
287 | again, possibly pressing a suitable key (e.g. the space bar) continuously; on most systems it should be | |
288 | possible to hit the time window after a few attempts. To avoid this problem, consider setting a non-zero | |
289 | timeout, thus showing the boot menu unconditionally. Some desktop environments might offer an option to | |
290 | directly boot into the boot menu, to avoid the problem altogether. Alternatively, use the command line | |
291 | <command>systemctl reboot --boot-loader-menu=0</command> from the shell.</para> | |
292 | ||
f37d3835 ZJS |
293 | <para>In the editor, most keys simply insert themselves, but the following keys |
294 | may be used to perform additional actions:</para> | |
295 | ||
296 | <variablelist> | |
297 | <varlistentry> | |
8c073dde LP |
298 | <term><keycap>←</keycap> (Left)</term> |
299 | <term><keycap>→</keycap> (Right)</term> | |
300 | <term><keycap>Home</keycap></term> | |
301 | <term><keycap>End</keycap></term> | |
ec07c3c8 AK |
302 | <listitem><para>Navigate left/right</para> |
303 | ||
304 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
305 | </varlistentry> |
306 | ||
307 | <varlistentry> | |
8c073dde | 308 | <term><keycap>Esc</keycap></term> |
230f7820 | 309 | <term><keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo></term> |
aefdc112 AK |
310 | <listitem><para>Abort the edit and quit the editor</para> |
311 | ||
312 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
313 | </varlistentry> |
314 | ||
315 | <varlistentry> | |
8c073dde | 316 | <term><keycombo><keycap>Ctrl</keycap><keycap>k</keycap></keycombo></term> |
ec07c3c8 AK |
317 | <listitem><para>Clear the command line forwards</para> |
318 | ||
aefdc112 | 319 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> |
f37d3835 ZJS |
320 | </varlistentry> |
321 | ||
322 | <varlistentry> | |
8c073dde LP |
323 | <term><keycombo><keycap>Ctrl</keycap><keycap>w</keycap></keycombo></term> |
324 | <term><keycombo><keycap>Alt</keycap><keycap>Backspace</keycap></keycombo></term> | |
ec07c3c8 AK |
325 | <listitem><para>Delete word backwards</para> |
326 | ||
aefdc112 | 327 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> |
f37d3835 ZJS |
328 | </varlistentry> |
329 | ||
330 | <varlistentry> | |
230f7820 | 331 | <term><keycombo><keycap>Ctrl</keycap><keycap>Del</keycap></keycombo></term> |
8c073dde | 332 | <term><keycombo><keycap>Alt</keycap><keycap>d</keycap></keycombo></term> |
aefdc112 AK |
333 | <listitem><para>Delete word forwards</para> |
334 | ||
335 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
336 | </varlistentry> |
337 | ||
338 | <varlistentry> | |
8c073dde | 339 | <term><keycap>↵</keycap> (Enter)</term> |
ec07c3c8 AK |
340 | <listitem><para>Boot entry with the edited command line</para> |
341 | ||
342 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
f37d3835 ZJS |
343 | </varlistentry> |
344 | </variablelist> | |
345 | ||
70c8db75 | 346 | <para>Note that unless configured otherwise in the UEFI firmware, systemd-boot will |
f37d3835 ZJS |
347 | use the US keyboard layout, so key labels might not match for keys like +/-. |
348 | </para> | |
349 | </refsect1> | |
350 | ||
53ddb667 LP |
351 | <refsect1> |
352 | <title>Files</title> | |
353 | ||
c5fcaed8 LP |
354 | <para>The files <command>systemd-boot</command> processes generally reside on the UEFI ESP which is |
355 | usually mounted to <filename>/efi/</filename>, <filename>/boot/</filename> or | |
356 | <filename>/boot/efi/</filename> during OS runtime. It also processes files on the Extended Boot Loader | |
357 | partition which is typically mounted to <filename>/boot/</filename>, if it | |
99d51ed9 LP |
358 | exists.</para> |
359 | ||
360 | <para><command>systemd-boot</command> reads runtime configuration such as the boot timeout and default | |
c5fcaed8 LP |
361 | entry from <filename>/loader/loader.conf</filename> on the ESP (in combination with data read from EFI |
362 | variables). See | |
99d51ed9 LP |
363 | <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> |
364 | ||
365 | <para>Boot entry description files following the <ulink | |
db811444 | 366 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> are read from |
99d51ed9 LP |
367 | <filename>/loader/entries/</filename> on the ESP and the Extended Boot Loader partition.</para> |
368 | ||
369 | <para>Unified kernel boot entries following the <ulink | |
db811444 | 370 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> are read from |
99d51ed9 LP |
371 | <filename>/EFI/Linux/</filename> on the ESP and the Extended Boot Loader partition.</para> |
372 | ||
373 | <para>Optionally, a random seed for early boot entropy pool provisioning is stored in | |
374 | <filename>/loader/random-seed</filename> in the ESP.</para> | |
375 | ||
376 | <para>During initialization, <command>sd-boot</command> automatically loads all driver files placed in | |
377 | the <filename>/EFI/systemd/drivers/</filename> directory of the ESP. The files placed there must have an | |
378 | extension of the EFI architecture ID followed by <filename>.efi</filename> (e.g. for x86-64 this means a | |
379 | suffix of <filename>x64.efi</filename>). This may be used to automatically load file system drivers and | |
380 | similar, to extend the native firmware support.</para> | |
e6b0cfad VD |
381 | |
382 | <para>Enrollment of Secure Boot variables can be performed manually or automatically if files are available | |
57ea8012 | 383 | under <filename>/loader/keys/<replaceable>NAME</replaceable>/{db,dbx,KEK,PK}.auth</filename>, <replaceable>NAME</replaceable> |
e6b0cfad VD |
384 | being the display name for the set of variables in the menu. If one of the sets is named <filename>auto</filename> |
385 | then it might be enrolled automatically depending on whether <literal>secure-boot-enroll</literal> is set | |
386 | to force or not.</para> | |
53ddb667 LP |
387 | </refsect1> |
388 | ||
8eebff9e LP |
389 | <refsect1> |
390 | <title>EFI Variables</title> | |
391 | ||
b8cdb662 LP |
392 | <para>The following EFI variables are defined, set and read by <command>systemd-boot</command>, under the |
393 | vendor UUID <literal>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</literal>, for communication between the boot | |
394 | loader and the OS:</para> | |
8eebff9e | 395 | |
bc61c2b1 | 396 | <variablelist class='efi-variables'> |
8eebff9e LP |
397 | <varlistentry> |
398 | <term><varname>LoaderBootCountPath</varname></term> | |
399 | <listitem><para>If boot counting is enabled, contains the path to the file in whose name the boot counters are | |
400 | encoded. Set by the boot | |
401 | loader. <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
402 | uses this information to mark a boot as successful as determined by the successful activation of the | |
ec07c3c8 AK |
403 | <filename>boot-complete.target</filename> target unit.</para> |
404 | ||
405 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
406 | </varlistentry> |
407 | ||
408 | <varlistentry> | |
409 | <term><varname>LoaderConfigTimeout</varname></term> | |
fe2579dd | 410 | <term><varname>LoaderConfigTimeoutOneShot</varname></term> |
3f9a0a52 | 411 | <listitem><para>The menu timeout in seconds. Read by the boot loader. <varname>LoaderConfigTimeout</varname> |
fe2579dd LP |
412 | is maintained persistently, while <varname>LoaderConfigTimeoutOneShot</varname> is a one-time override which is |
413 | read once (in which case it takes precedence over <varname>LoaderConfigTimeout</varname>) and then | |
414 | removed. <varname>LoaderConfigTimeout</varname> may be manipulated with the | |
ec07c3c8 AK |
415 | <keycap>t</keycap>/<keycap>T</keycap> keys, see above.</para> |
416 | ||
417 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
418 | </varlistentry> |
419 | ||
b207ad63 EV |
420 | <varlistentry> |
421 | <term><varname>LoaderConfigConsoleMode</varname></term> | |
422 | <listitem><para>The numerical menu console mode. Read by the boot loader. <varname>LoaderConfigConsoleMode</varname> | |
423 | is maintained persistently. <varname>LoaderConfigConsoleMode</varname> may be manipulated with the | |
424 | <keycap>r</keycap>/<keycap>R</keycap> keys, see above.</para> | |
425 | ||
426 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
427 | </varlistentry> | |
428 | ||
8eebff9e LP |
429 | <varlistentry> |
430 | <term><varname>LoaderDevicePartUUID</varname></term> | |
431 | ||
432 | <listitem><para>Contains the partition UUID of the EFI System Partition the boot loader was run from. Set by | |
433 | the boot | |
434 | loader. <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
435 | uses this information to automatically find the disk booted from, in order to discover various other partitions | |
ec07c3c8 AK |
436 | on the same disk automatically.</para> |
437 | ||
438 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
439 | </varlistentry> |
440 | ||
441 | <varlistentry> | |
442 | <term><varname>LoaderEntries</varname></term> | |
443 | ||
444 | <listitem><para>A list of the identifiers of all discovered boot loader entries. Set by the boot | |
ec07c3c8 AK |
445 | loader.</para> |
446 | ||
447 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
448 | </varlistentry> |
449 | ||
450 | <varlistentry> | |
451 | <term><varname>LoaderEntryDefault</varname></term> | |
452 | <term><varname>LoaderEntryOneShot</varname></term> | |
453 | ||
454 | <listitem><para>The identifier of the default boot loader entry. Set primarily by the OS and read by the boot | |
455 | loader. <varname>LoaderEntryOneShot</varname> sets the default entry for the next boot only, while | |
456 | <varname>LoaderEntryDefault</varname> sets it persistently for all future | |
457 | boots. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s | |
458 | <option>set-default</option> and <option>set-oneshot</option> commands make use of these variables. The boot | |
459 | loader modifies <varname>LoaderEntryDefault</varname> on request, when the <keycap>d</keycap> key is used, see | |
ec07c3c8 AK |
460 | above.</para> |
461 | ||
462 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
463 | </varlistentry> |
464 | ||
ef4976dc EV |
465 | <varlistentry> |
466 | <term><varname>LoaderEntryLastBooted</varname></term> | |
467 | ||
468 | <listitem><para>The identifier of the boot loader entry last attempted. Set and read by the boot loader, | |
469 | only when <filename>/loader/loader.conf</filename> has default set to <literal>@saved</literal>. See | |
470 | <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> | |
471 | ||
472 | <para> The boot loader will ensure <varname>LoaderEntryLastBooted</varname> is up-to date for every boot, | |
473 | updating it as needed and will omit changing it all together when <varname>LoaderEntryOneShot</varname> | |
474 | is set.</para> | |
475 | ||
476 | <para>The boot loader reads the variable, which takes higher priority than | |
477 | <varname>LoaderEntryDefault</varname>. The variable is ignored when <varname>LoaderEntryOneShot</varname> | |
478 | is set.</para> | |
479 | ||
480 | <para><varname>LoaderEntryLastBooted</varname> cannot be used as indication that the last boot was | |
481 | successful or not.</para> | |
482 | ||
483 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
484 | </varlistentry> | |
485 | ||
8eebff9e LP |
486 | <varlistentry> |
487 | <term><varname>LoaderEntrySelected</varname></term> | |
488 | ||
489 | <listitem><para>The identifier of the boot loader entry currently being booted. Set by the boot | |
ec07c3c8 AK |
490 | loader.</para> |
491 | ||
492 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
493 | </varlistentry> |
494 | ||
5dd5f7cf LP |
495 | <varlistentry> |
496 | <term><varname>LoaderFeatures</varname></term> | |
497 | ||
498 | <listitem><para>A set of flags indicating the features the boot loader supports. Set by the boot loader. Use | |
499 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this | |
ec07c3c8 AK |
500 | data.</para> |
501 | ||
502 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
5dd5f7cf LP |
503 | </varlistentry> |
504 | ||
8eebff9e LP |
505 | <varlistentry> |
506 | <term><varname>LoaderFirmwareInfo</varname></term> | |
507 | <term><varname>LoaderFirmwareType</varname></term> | |
508 | ||
509 | <listitem><para>Brief firmware information. Set by the boot loader. Use | |
510 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this | |
ec07c3c8 AK |
511 | data.</para> |
512 | ||
513 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
514 | </varlistentry> |
515 | ||
516 | <varlistentry> | |
517 | <term><varname>LoaderImageIdentifier</varname></term> | |
518 | ||
519 | <listitem><para>The path of executable of the boot loader used for the current boot, relative to the EFI System | |
520 | Partition's root directory. Set by the boot loader. Use | |
521 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this | |
ec07c3c8 AK |
522 | data.</para> |
523 | ||
524 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
525 | </varlistentry> |
526 | ||
527 | <varlistentry> | |
528 | <term><varname>LoaderInfo</varname></term> | |
529 | ||
530 | <listitem><para>Brief information about the boot loader. Set by the boot loader. Use | |
531 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this | |
ec07c3c8 AK |
532 | data.</para> |
533 | ||
534 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
8eebff9e LP |
535 | </varlistentry> |
536 | ||
537 | <varlistentry> | |
538 | <term><varname>LoaderTimeExecUSec</varname></term> | |
539 | <term><varname>LoaderTimeInitUSec</varname></term> | |
540 | <term><varname>LoaderTimeMenuUsec</varname></term> | |
541 | ||
542 | <listitem><para>Information about the time spent in various parts of the boot loader. Set by the boot | |
543 | loader. Use <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
ec07c3c8 AK |
544 | to view this data. </para> |
545 | ||
546 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
39867bb9 LP |
547 | </varlistentry> |
548 | ||
39867bb9 LP |
549 | <varlistentry> |
550 | <term><varname>LoaderSystemToken</varname></term> | |
551 | ||
e9dd6984 ZJS |
552 | <listitem><para>A binary random data field, that is used for generating the random seed to pass to |
553 | the OS (see above). Note that this random data is generally only generated once, during OS | |
ec07c3c8 AK |
554 | installation, and is then never updated again.</para> |
555 | ||
556 | <xi:include href="version-info.xml" xpointer="v243"/></listitem> | |
8eebff9e LP |
557 | </varlistentry> |
558 | </variablelist> | |
39867bb9 LP |
559 | |
560 | <para>Many of these variables are defined by the <ulink | |
561 | url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para> | |
8eebff9e LP |
562 | </refsect1> |
563 | ||
365e90b9 DDM |
564 | <refsect1> |
565 | <title>SMBIOS Type 11 Strings</title> | |
566 | ||
567 | <para><command>systemd-boot</command> can be configured using SMBIOS Type 11 strings. Applicable strings | |
f7100379 DDM |
568 | consist of a name, followed by <literal>=</literal>, followed by the value. Unless |
569 | <command>systemd-boot</command> detects it is running inside a confidential computing environment, | |
365e90b9 DDM |
570 | <command>systemd-boot</command> will search the table for a string with a specific name, and if found, |
571 | use its value. The following strings are read:</para> | |
572 | ||
573 | <variablelist> | |
574 | <varlistentry> | |
575 | <term><varname>io.systemd.boot.kernel-cmdline-extra</varname></term> | |
576 | <listitem><para>If set, the value of this string is added to the list of kernel command line | |
577 | arguments for Boot Loader Specification Type 1 entries that are measured in PCR12 and passed to the | |
578 | kernel.</para> | |
579 | ||
580 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
581 | </varlistentry> | |
582 | </variablelist> | |
583 | </refsect1> | |
584 | ||
2b6cc3ca LP |
585 | <refsect1> |
586 | <title>Boot Counting</title> | |
587 | ||
588 | <para><command>systemd-boot</command> implements a simple boot counting mechanism on top of the <ulink | |
db811444 | 589 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>, for automatic and unattended |
5238e957 | 590 | fallback to older kernel versions/boot loader entries when a specific entry continuously fails. Any boot loader |
2b6cc3ca LP |
591 | entry file and unified kernel image file that contains a <literal>+</literal> followed by one or two numbers (if |
592 | two they need to be separated by a <literal>-</literal>), before the <filename>.conf</filename> or | |
593 | <filename>.efi</filename> suffix is subject to boot counting: the first of the two numbers ('tries left') is | |
594 | decreased by one on every boot attempt, the second of the two numbers ('tries done') is increased by one (if 'tries | |
595 | done' is absent it is considered equivalent to 0). Depending on the current value of these two counters the boot | |
596 | entry is considered to be in one of three states:</para> | |
597 | ||
598 | <orderedlist> | |
599 | <listitem><para>If the 'tries left' counter of an entry is greater than zero the entry is considered to be in | |
600 | 'indeterminate' state. This means the entry has not completed booting successfully yet, but also hasn't been | |
601 | determined not to work.</para></listitem> | |
602 | ||
603 | <listitem><para>If the 'tries left' counter of an entry is zero it is considered to be in 'bad' state. This means | |
604 | no further attempts to boot this item will be made (that is, unless all other boot entries are also in 'bad' | |
605 | state), as all attempts to boot this entry have not completed successfully.</para></listitem> | |
606 | ||
607 | <listitem><para>If the 'tries left' and 'tries done' counters of an entry are absent it is considered to be in | |
608 | 'good' state. This means further boot counting for the entry is turned off, as it successfully booted at least | |
609 | once. The | |
610 | <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
611 | service moves the currently booted entry from 'indeterminate' into 'good' state when a boot attempt completed | |
612 | successfully.</para></listitem> | |
613 | </orderedlist> | |
614 | ||
615 | <para>Generally, when new entries are added to the boot loader, they first start out in 'indeterminate' state, | |
616 | i.e. with a 'tries left' counter greater than zero. The boot entry remains in this state until either it managed to | |
617 | complete a full boot successfully at least once (in which case it will be in 'good' state) — or the 'tries left' | |
618 | counter reaches zero (in which case it will be in 'bad' state).</para> | |
619 | ||
620 | <para>Example: let's say a boot loader entry file <filename>foo.conf</filename> is set up for 3 boot tries. The | |
621 | installer will hence create it under the name <filename>foo+3.conf</filename>. On first boot, the boot loader will | |
622 | rename it to <filename>foo+2-1.conf</filename>. If that boot does not complete successfully, the boot loader will | |
623 | rename it to <filename>foo+1-2.conf</filename> on the following boot. If that fails too, it will finally be renamed | |
624 | <filename>foo+0-3.conf</filename> by the boot loader on next boot, after which it will be considered 'bad'. If the | |
625 | boot succeeds however the entry file will be renamed to <filename>foo.conf</filename> by the OS, so that it is | |
626 | considered 'good' from then on.</para> | |
627 | ||
628 | <para>The boot menu takes the 'tries left' counter into account when sorting the menu entries: entries in 'bad' | |
f65a3326 LP |
629 | state are ordered at the beginning of the list, and entries in 'good' or 'indeterminate' at the end. The user can |
630 | freely choose to boot any entry of the menu, including those already marked 'bad'. If the menu entry to boot is | |
631 | automatically determined, this means that 'good' or 'indeterminate' entries are generally preferred (as the bottom | |
632 | item of the menu is the one booted by default), and 'bad' entries will only be considered if there are no 'good' or | |
2b6cc3ca LP |
633 | 'indeterminate' entries left.</para> |
634 | ||
635 | <para>The <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> kernel | |
636 | install framework optionally sets the initial 'tries left' counter to the value specified in | |
637 | <filename>/etc/kernel/tries</filename> when a boot loader entry is first created.</para> | |
638 | </refsect1> | |
639 | ||
941d418d | 640 | <refsect1> |
8fb35004 | 641 | <title>Using <command>systemd-boot</command> in virtual machines</title> |
941d418d GH |
642 | |
643 | <para>When using qemu with OVMF (UEFI Firmware for virtual machines) the <option>-kernel</option> switch | |
644 | works not only for linux kernels, but for any EFI binary, including sd-boot and unified linux | |
8fb35004 | 645 | kernels. Example command line for loading <command>systemd-boot</command> on x64:</para> |
941d418d GH |
646 | |
647 | <para> | |
648 | <command>qemu-system-x86_64 <replaceable>[ ... ]</replaceable> | |
649 | -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi</command> | |
650 | </para> | |
651 | ||
652 | <para>systemd-boot will detect that it was started directly instead of being loaded from ESP and will | |
653 | search for the ESP in that case, taking into account boot order information from the hypervisor (if | |
654 | available).</para> | |
655 | </refsect1> | |
656 | ||
f37d3835 ZJS |
657 | <refsect1> |
658 | <title>See Also</title> | |
13a69c12 DT |
659 | <para><simplelist type="inline"> |
660 | <member><citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
661 | <member><citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
662 | <member><citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
663 | <member><citerefentry><refentrytitle>systemd-boot-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
664 | <member><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
665 | <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
666 | <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member> | |
667 | <member><ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink></member> | |
668 | <member><ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink></member> | |
669 | </simplelist></para> | |
f37d3835 ZJS |
670 | </refsect1> |
671 | </refentry> |