]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd-boot.xml
Merge pull request #8822 from fbuihuu/rfc-tmpfiles-safe-upstream
[thirdparty/systemd.git] / man / systemd-boot.xml
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
7 <refentry id="systemd-boot" conditional='ENABLE_EFI'
8 xmlns:xi="http://www.w3.org/2001/XInclude">
9 <refentryinfo>
10 <title>systemd-boot</title>
11 <productname>systemd</productname>
12 </refentryinfo>
13
14 <refmeta>
15 <refentrytitle>systemd-boot</refentrytitle>
16 <manvolnum>7</manvolnum>
17 </refmeta>
18
19 <refnamediv>
20 <refname>systemd-boot</refname>
21 <refname>sd-boot</refname>
22 <refpurpose>A simple UEFI boot manager</refpurpose>
23 </refnamediv>
24
25 <refsect1>
26 <title>Description</title>
27
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
30 supports systems with UEFI firmware only.</para>
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
41 url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
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
47 url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
48 Specification</ulink>, as executable EFI binaries in <filename>/EFI/Linux/</filename> on the ESP.
49 </para></listitem>
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
68 <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
69 </para>
70 </refsect1>
71
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>
118 <listitem><para>Show systemd-boot, UEFI, and firmware versions</para></listitem>
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>
177 <listitem><para>Boot entry number 19</para></listitem>
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
220 <para>Note that unless configured otherwise in the UEFI firmware, systemd-boot will
221 use the US keyboard layout, so key labels might not match for keys like +/-.
222 </para>
223 </refsect1>
224
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
234 url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
235 Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP. Unified kernel boot entries
236 following the <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot
237 Loader Specification</ulink> are read from <filename>/EFI/Linux/</filename> on the ESP.</para>
238 </refsect1>
239
240 <refsect1>
241 <title>See Also</title>
242 <para>
243 <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
244 <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
245 <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>,
246 <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
247 </para>
248 </refsect1>
249 </refentry>