]>
Commit | Line | Data |
---|---|---|
f37d3835 ZJS |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
4 | ||
5 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> | |
6 | ||
70c8db75 | 7 | <refentry id="systemd-boot" conditional='ENABLE_EFI' |
f37d3835 ZJS |
8 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
9 | <refentryinfo> | |
70c8db75 | 10 | <title>systemd-boot</title> |
f37d3835 | 11 | <productname>systemd</productname> |
f37d3835 ZJS |
12 | </refentryinfo> |
13 | ||
14 | <refmeta> | |
70c8db75 | 15 | <refentrytitle>systemd-boot</refentrytitle> |
f37d3835 ZJS |
16 | <manvolnum>7</manvolnum> |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
70c8db75 | 20 | <refname>systemd-boot</refname> |
f37d3835 ZJS |
21 | <refname>sd-boot</refname> |
22 | <refpurpose>A simple UEFI boot manager</refpurpose> | |
23 | </refnamediv> | |
24 | ||
25 | <refsect1> | |
26 | <title>Description</title> | |
27 | ||
53ddb667 LP |
28 | <para><command>systemd-boot</command> (short: <command>sd-boot</command>) is a simple UEFI boot manager. It |
29 | provides a graphical menu to select the entry to boot and an editor for the kernel command line. systemd-boot | |
48691dca | 30 | supports systems with UEFI firmware only.</para> |
53ddb667 LP |
31 | |
32 | <para>systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at | |
33 | <filename>/boot</filename>, <filename>/efi</filename>, or <filename>/boot/efi</filename> during OS | |
34 | runtime. Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on | |
35 | the ESP. Linux kernels must be built with <option>CONFIG_EFI_STUB</option> to be able to be directly executed as an | |
36 | EFI image. During boot systemd-boot automatically assembles a list of boot entries from the following | |
37 | sources:</para> | |
38 | ||
39 | <itemizedlist> | |
40 | <listitem><para>Boot entries defined with <ulink | |
a0848495 | 41 | url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader |
53ddb667 LP |
42 | Specification</ulink> description files located in <filename>/loader/entries/</filename> on the ESP. These |
43 | usually describe Linux kernel images with associated initrd images, but alternatively may also describe | |
44 | arbitrary other EFI executables.</para></listitem> | |
45 | ||
46 | <listitem><para>Unified kernel images following the <ulink | |
a0848495 | 47 | url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader |
48691dca ZJS |
48 | Specification</ulink>, as executable EFI binaries in <filename>/EFI/Linux/</filename> on the ESP. |
49 | </para></listitem> | |
53ddb667 LP |
50 | |
51 | <listitem><para>The Microsoft Windows EFI boot manager, if installed</para></listitem> | |
52 | ||
53 | <listitem><para>The Apple MacOS X boot manager, if installed</para></listitem> | |
54 | ||
55 | <listitem><para>The EFI Shell binary, if installed</para></listitem> | |
56 | ||
57 | <listitem><para>A reboot into the UEFI firmware setup option, if supported by the firmware</para></listitem> | |
58 | </itemizedlist> | |
59 | ||
60 | <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> may be | |
61 | used to copy kernel images onto the ESP and to generate description files compliant with the Boot Loader | |
62 | Specification. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> may be | |
63 | used from a running system to locate the ESP, list available entries, and install systemd-boot itself.</para> | |
64 | ||
65 | <para>systemd-boot will provide information about the time spent in UEFI firmware using the <ulink | |
66 | url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>. This | |
67 | information can be displayed using | |
f37d3835 ZJS |
68 | <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>. |
69 | </para> | |
70 | </refsect1> | |
71 | ||
f37d3835 ZJS |
72 | <refsect1> |
73 | <title>Key bindings</title> | |
74 | <para>The following keys may be used in the boot menu:</para> | |
75 | ||
76 | <variablelist> | |
77 | <varlistentry> | |
78 | <term>↑ (Up)</term> | |
79 | <term>↓ (Down)</term> | |
80 | <term>j</term> | |
81 | <term>k</term> | |
82 | <term>PageUp</term> | |
83 | <term>PageDown</term> | |
84 | <term>Home</term> | |
85 | <term>End</term> | |
86 | <listitem><para>Navigate up/down in the entry list</para></listitem> | |
87 | </varlistentry> | |
88 | ||
89 | <varlistentry> | |
90 | <term>↵ (Enter)</term> | |
91 | <listitem><para>Boot selected entry</para></listitem> | |
92 | </varlistentry> | |
93 | ||
94 | <varlistentry> | |
95 | <term>d</term> | |
96 | <listitem><para>Make selected entry the default</para></listitem> | |
97 | </varlistentry> | |
98 | ||
99 | <varlistentry> | |
100 | <term>e</term> | |
101 | <listitem><para>Edit the kernel command line for selected entry</para></listitem> | |
102 | </varlistentry> | |
103 | ||
104 | <varlistentry> | |
105 | <term>+</term> | |
106 | <term>t</term> | |
107 | <listitem><para>Increase the timeout before default entry is booted</para></listitem> | |
108 | </varlistentry> | |
109 | ||
110 | <varlistentry> | |
111 | <term>-</term> | |
112 | <term>T</term> | |
113 | <listitem><para>Decrease the timeout</para></listitem> | |
114 | </varlistentry> | |
115 | ||
116 | <varlistentry> | |
117 | <term>v</term> | |
70c8db75 | 118 | <listitem><para>Show systemd-boot, UEFI, and firmware versions</para></listitem> |
f37d3835 ZJS |
119 | </varlistentry> |
120 | ||
121 | <varlistentry> | |
122 | <term>P</term> | |
123 | <listitem><para>Print status</para></listitem> | |
124 | </varlistentry> | |
125 | ||
126 | <varlistentry> | |
127 | <term>Q</term> | |
128 | <listitem><para>Quit</para></listitem> | |
129 | </varlistentry> | |
130 | ||
131 | <varlistentry> | |
132 | <term>h</term> | |
133 | <term>?</term> | |
134 | <listitem><para>Show a help screen</para></listitem> | |
135 | </varlistentry> | |
136 | ||
137 | <varlistentry> | |
138 | <term>Ctrl + l</term> | |
139 | <listitem><para>Reprint the screen</para></listitem> | |
140 | </varlistentry> | |
141 | </variablelist> | |
142 | ||
143 | <para>The following keys may be used during bootup or in the boot menu to | |
144 | directly boot a specific entry:</para> | |
145 | ||
146 | <variablelist> | |
147 | <varlistentry> | |
148 | <term>l</term> | |
149 | <listitem><para>Linux</para></listitem> | |
150 | </varlistentry> | |
151 | ||
152 | <varlistentry> | |
153 | <term>w</term> | |
154 | <listitem><para>Windows</para></listitem> | |
155 | </varlistentry> | |
156 | ||
157 | <varlistentry> | |
158 | <term>a</term> | |
159 | <listitem><para>OS X</para></listitem> | |
160 | </varlistentry> | |
161 | ||
162 | <varlistentry> | |
163 | <term>s</term> | |
164 | <listitem><para>EFI shell</para></listitem> | |
165 | </varlistentry> | |
166 | ||
167 | <varlistentry> | |
168 | <term>1</term> | |
169 | <term>2</term> | |
170 | <term>3</term> | |
171 | <term>4</term> | |
172 | <term>5</term> | |
173 | <term>6</term> | |
174 | <term>7</term> | |
175 | <term>8</term> | |
176 | <term>9</term> | |
53ddb667 | 177 | <listitem><para>Boot entry number 1 … 9</para></listitem> |
f37d3835 ZJS |
178 | </varlistentry> |
179 | </variablelist> | |
180 | ||
181 | <para>In the editor, most keys simply insert themselves, but the following keys | |
182 | may be used to perform additional actions:</para> | |
183 | ||
184 | <variablelist> | |
185 | <varlistentry> | |
186 | <term>← (Left)</term> | |
187 | <term>→ (Right)</term> | |
188 | <term>Home</term> | |
189 | <term>End</term> | |
190 | <listitem><para>Navigate left/right</para></listitem> | |
191 | </varlistentry> | |
192 | ||
193 | <varlistentry> | |
194 | <term>Esc</term> | |
195 | <listitem><para>Abort the edit and quit the editor</para></listitem> | |
196 | </varlistentry> | |
197 | ||
198 | <varlistentry> | |
199 | <term>Ctrl + k</term> | |
200 | <listitem><para>Clear the command line</para></listitem> | |
201 | </varlistentry> | |
202 | ||
203 | <varlistentry> | |
204 | <term>Ctrl + w</term> | |
205 | <term>Alt + Backspace</term> | |
206 | <listitem><para>Delete word backwards</para></listitem> | |
207 | </varlistentry> | |
208 | ||
209 | <varlistentry> | |
210 | <term>Alt + d </term> | |
211 | <listitem><para>Delete word forwards</para></listitem> | |
212 | </varlistentry> | |
213 | ||
214 | <varlistentry> | |
215 | <term>↵ (Enter)</term> | |
216 | <listitem><para>Boot entry with the edited command line</para></listitem> | |
217 | </varlistentry> | |
218 | </variablelist> | |
219 | ||
70c8db75 | 220 | <para>Note that unless configured otherwise in the UEFI firmware, systemd-boot will |
f37d3835 ZJS |
221 | use the US keyboard layout, so key labels might not match for keys like +/-. |
222 | </para> | |
223 | </refsect1> | |
224 | ||
53ddb667 LP |
225 | <refsect1> |
226 | <title>Files</title> | |
227 | ||
228 | <para>The files systemd-boot reads generally reside on the UEFI ESP which is usually mounted to | |
229 | <filename>/boot/</filename>, <filename>/efi/</filename> or <filename>/boot/efi</filename> during OS | |
230 | runtime. systemd-boot reads runtime configuration such as the boot timeout and default entry from | |
231 | <filename>/loader/loader.conf</filename> on the ESP (in combination with data read from EFI variables). See | |
232 | <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Boot entry | |
233 | description files following the <ulink | |
a0848495 | 234 | url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader |
53ddb667 | 235 | Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP. Unified kernel boot entries |
a0848495 | 236 | following the <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot |
53ddb667 LP |
237 | Loader Specification</ulink> are read from <filename>/EFI/Linux/</filename> on the ESP.</para> |
238 | </refsect1> | |
239 | ||
8eebff9e LP |
240 | <refsect1> |
241 | <title>EFI Variables</title> | |
242 | ||
243 | <para>The following EFI variables are defined, set and read by <command>systemd-boot</command>, under the vendor | |
244 | UUID <literal>4a67b082-0a4c-41cf-b6c7-440b29bb8c4</literal>, for communication between the OS and the boot | |
245 | loader:</para> | |
246 | ||
247 | <variablelist> | |
248 | <varlistentry> | |
249 | <term><varname>LoaderBootCountPath</varname></term> | |
250 | <listitem><para>If boot counting is enabled, contains the path to the file in whose name the boot counters are | |
251 | encoded. Set by the boot | |
252 | loader. <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
253 | uses this information to mark a boot as successful as determined by the successful activation of the | |
254 | <filename>boot-complete.target</filename> target unit.</para></listitem> | |
255 | </varlistentry> | |
256 | ||
257 | <varlistentry> | |
258 | <term><varname>LoaderConfigTimeout</varname></term> | |
259 | <listitem><para>The menu time-out. Read by the boot loader. (Also, modified by it when the | |
260 | <keycap>t</keycap>/<keycap>T</keycap> keys are used, see above.)</para></listitem> | |
261 | </varlistentry> | |
262 | ||
263 | <varlistentry> | |
264 | <term><varname>LoaderDevicePartUUID</varname></term> | |
265 | ||
266 | <listitem><para>Contains the partition UUID of the EFI System Partition the boot loader was run from. Set by | |
267 | the boot | |
268 | loader. <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
269 | uses this information to automatically find the disk booted from, in order to discover various other partitions | |
270 | on the same disk automatically.</para></listitem> | |
271 | </varlistentry> | |
272 | ||
273 | <varlistentry> | |
274 | <term><varname>LoaderEntries</varname></term> | |
275 | ||
276 | <listitem><para>A list of the identifiers of all discovered boot loader entries. Set by the boot | |
277 | loader.</para></listitem> | |
278 | </varlistentry> | |
279 | ||
280 | <varlistentry> | |
281 | <term><varname>LoaderEntryDefault</varname></term> | |
282 | <term><varname>LoaderEntryOneShot</varname></term> | |
283 | ||
284 | <listitem><para>The identifier of the default boot loader entry. Set primarily by the OS and read by the boot | |
285 | loader. <varname>LoaderEntryOneShot</varname> sets the default entry for the next boot only, while | |
286 | <varname>LoaderEntryDefault</varname> sets it persistently for all future | |
287 | boots. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s | |
288 | <option>set-default</option> and <option>set-oneshot</option> commands make use of these variables. The boot | |
289 | loader modifies <varname>LoaderEntryDefault</varname> on request, when the <keycap>d</keycap> key is used, see | |
290 | above.)</para></listitem> | |
291 | </varlistentry> | |
292 | ||
293 | <varlistentry> | |
294 | <term><varname>LoaderEntrySelected</varname></term> | |
295 | ||
296 | <listitem><para>The identifier of the boot loader entry currently being booted. Set by the boot | |
297 | loader.</para></listitem> | |
298 | </varlistentry> | |
299 | ||
300 | <varlistentry> | |
301 | <term><varname>LoaderFirmwareInfo</varname></term> | |
302 | <term><varname>LoaderFirmwareType</varname></term> | |
303 | ||
304 | <listitem><para>Brief firmware information. Set by the boot loader. Use | |
305 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this | |
306 | data.</para></listitem> | |
307 | </varlistentry> | |
308 | ||
309 | <varlistentry> | |
310 | <term><varname>LoaderImageIdentifier</varname></term> | |
311 | ||
312 | <listitem><para>The path of executable of the boot loader used for the current boot, relative to the EFI System | |
313 | Partition's root directory. Set by the boot loader. Use | |
314 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this | |
315 | data.</para></listitem> | |
316 | </varlistentry> | |
317 | ||
318 | <varlistentry> | |
319 | <term><varname>LoaderInfo</varname></term> | |
320 | ||
321 | <listitem><para>Brief information about the boot loader. Set by the boot loader. Use | |
322 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this | |
323 | data.</para></listitem> | |
324 | </varlistentry> | |
325 | ||
326 | <varlistentry> | |
327 | <term><varname>LoaderTimeExecUSec</varname></term> | |
328 | <term><varname>LoaderTimeInitUSec</varname></term> | |
329 | <term><varname>LoaderTimeMenuUsec</varname></term> | |
330 | ||
331 | <listitem><para>Information about the time spent in various parts of the boot loader. Set by the boot | |
332 | loader. Use <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
333 | to view this data. These variables are defined by the <ulink | |
334 | url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader | |
335 | Interface</ulink>.</para></listitem> | |
336 | </varlistentry> | |
337 | </variablelist> | |
338 | </refsect1> | |
339 | ||
f37d3835 ZJS |
340 | <refsect1> |
341 | <title>See Also</title> | |
342 | <para> | |
343 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
344 | <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
a0848495 | 345 | <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, |
41e3f73d | 346 | <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink> |
f37d3835 ZJS |
347 | </para> |
348 | </refsect1> | |
349 | </refentry> |