]>
Commit | Line | Data |
---|---|---|
f37d3835 | 1 | <?xml version='1.0'?> <!--*-nxml-*--> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
f37d3835 | 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
f37d3835 | 5 | |
ba38a24d | 6 | <refentry id="loader.conf" conditional='HAVE_GNU_EFI' |
f37d3835 ZJS |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
8 | <refentryinfo> | |
9 | <title>loader.conf</title> | |
10 | <productname>systemd</productname> | |
f37d3835 ZJS |
11 | </refentryinfo> |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>loader.conf</refentrytitle> | |
15 | <manvolnum>5</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>loader.conf</refname> | |
70c8db75 | 20 | <refpurpose>Configuration file for systemd-boot</refpurpose> |
f37d3835 ZJS |
21 | </refnamediv> |
22 | ||
23 | <refsynopsisdiv> | |
24 | <para><filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>, | |
cbae79b8 | 25 | <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename> |
cafa9d87 | 26 | <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/*.conf</filename> |
f37d3835 ZJS |
27 | </para> |
28 | </refsynopsisdiv> | |
29 | ||
30 | <refsect1> | |
31 | <title>Description</title> | |
32 | ||
33 | <para> | |
a0aa3838 ZJS |
34 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> will |
35 | read <filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>, and any files with the | |
f37d3835 | 36 | <literal>.conf</literal> extension under |
cafa9d87 LP |
37 | <filename><replaceable>ESP</replaceable>/loader/entries/</filename> on the EFI system partition (ESP), |
38 | and <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/</filename> on the extended boot loader | |
db811444 | 39 | partition (XBOOTLDR) as defined by <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader |
cafa9d87 | 40 | Specification</ulink>. |
f37d3835 ZJS |
41 | </para> |
42 | ||
84df0f31 LP |
43 | <para>Each of these configuration files must consist of series of newline (i.e. ASCII code 10) separated |
44 | lines, each consisting of an option name, followed by whitespace, and the option | |
45 | value. <literal>#</literal> may be used to start a comment line. Empty and comment lines are ignored. The | |
46 | files use UTF-8 encoding.</para> | |
f37d3835 ZJS |
47 | |
48 | <para>Boolean arguments may be written as | |
dba0c983 JJ |
49 | <literal>yes</literal>/<literal>y</literal>/<literal>true</literal>/<literal>t</literal>/<literal>on</literal>/<literal>1</literal> or |
50 | <literal>no</literal>/<literal>n</literal>/<literal>false</literal>/<literal>f</literal>/<literal>off</literal>/<literal>0</literal>. | |
f37d3835 ZJS |
51 | </para> |
52 | </refsect1> | |
53 | ||
54 | <refsect1> | |
55 | <title>Options</title> | |
56 | ||
d212b862 | 57 | <para>The configuration options supported by |
cafa9d87 LP |
58 | <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename> and |
59 | <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/*.conf</filename> files are defined as part | |
db811444 | 60 | of the <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader |
cafa9d87 | 61 | Specification</ulink>.</para> |
d212b862 LP |
62 | |
63 | <para>The following configuration are supported by the <filename>loader.conf</filename> configuration | |
64 | file:</para> | |
f37d3835 ZJS |
65 | |
66 | <variablelist> | |
67 | <varlistentry> | |
68 | <term>default</term> | |
69 | ||
70 | <listitem><para>A glob pattern to select the default entry. The default entry | |
71 | may be changed in the boot menu itself, in which case the name of the | |
72 | selected entry will be stored as an EFI variable, overriding this option. | |
64bb56e5 JJ |
73 | </para> |
74 | ||
ee4fd9cb JJ |
75 | <para>If set to <literal>@saved</literal> the chosen entry will be saved as an EFI variable |
76 | on every boot and automatically selected the next time the boot loader starts.</para> | |
77 | ||
64bb56e5 JJ |
78 | <table> |
79 | <title>Automatically detected entries will use the following names:</title> | |
80 | ||
81 | <tgroup cols='2'> | |
82 | <colspec colname='name' /> | |
83 | <colspec colname='expl' /> | |
84 | <thead> | |
85 | <row> | |
86 | <entry>Name</entry> | |
87 | <entry>Description</entry> | |
88 | </row> | |
89 | </thead> | |
90 | <tbody> | |
91 | <row> | |
92 | <entry>auto-efi-default</entry> | |
93 | <entry>EFI Default Loader</entry> | |
94 | </row> | |
95 | <row> | |
96 | <entry>auto-efi-shell</entry> | |
97 | <entry>EFI Shell</entry> | |
98 | </row> | |
99 | <row> | |
100 | <entry>auto-osx</entry> | |
101 | <entry>macOS</entry> | |
102 | </row> | |
103 | <row> | |
104 | <entry>auto-reboot-to-firmware-setup</entry> | |
105 | <entry>Reboot Into Firmware Interface</entry> | |
106 | </row> | |
107 | <row> | |
108 | <entry>auto-windows</entry> | |
109 | <entry>Windows Boot Manager</entry> | |
110 | </row> | |
111 | </tbody> | |
112 | </tgroup> | |
23742af5 JJ |
113 | </table> |
114 | ||
172cbcdc | 115 | <para>Supported glob wildcard patterns are <literal>?</literal>, <literal>*</literal>, and |
23742af5 | 116 | <literal>[…]</literal> (including ranges). Note that these patterns use the same syntax as |
6f52e1c6 ZJS |
117 | <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>, |
118 | but do not support all features. In particular, set negation and named character classes are not | |
119 | supported. The matching is done case-insensitively on the entry ID (as shown by <command>bootctl | |
23742af5 | 120 | list</command>).</para></listitem> |
f37d3835 ZJS |
121 | </varlistentry> |
122 | ||
123 | <varlistentry> | |
124 | <term>timeout</term> | |
125 | ||
126 | <listitem><para>How long the boot menu should be shown before the default | |
127 | entry is booted, in seconds. This may be changed in the boot menu itself and | |
128 | will be stored as an EFI variable in that case, overriding this option. | |
129 | </para> | |
130 | ||
815068d3 | 131 | <para>If set to <literal>menu-hidden</literal> or <literal>0</literal> (the default) no menu |
52b6b356 JJ |
132 | is shown and the default entry will be booted immediately. The menu can be shown |
133 | by pressing and holding a key before systemd-boot is launched. Setting this to | |
134 | <literal>menu-force</literal> disables the timeout while always showing the menu.</para> | |
f37d3835 ZJS |
135 | </listitem> |
136 | </varlistentry> | |
137 | ||
138 | <varlistentry> | |
139 | <term>console-mode</term> | |
140 | ||
141 | <listitem><para>This option configures the resolution of the console. Takes a | |
142 | number or one of the special values listed below. The following values may be | |
143 | used:</para> | |
144 | ||
145 | <variablelist> | |
146 | <varlistentry> | |
147 | <term>0</term> | |
148 | <listitem> | |
149 | <para>Standard UEFI 80x25 mode</para> | |
150 | </listitem> | |
151 | </varlistentry> | |
152 | ||
153 | <varlistentry> | |
154 | <term>1</term> | |
155 | <listitem> | |
156 | <para>80x50 mode, not supported by all devices</para> | |
157 | </listitem> | |
158 | </varlistentry> | |
159 | ||
160 | <varlistentry> | |
161 | <term>2</term> | |
162 | <listitem> | |
163 | <para>the first non-standard mode provided by the device | |
164 | firmware, if any</para> | |
165 | </listitem> | |
166 | </varlistentry> | |
167 | ||
168 | <varlistentry> | |
169 | <term>auto</term> | |
170 | <listitem> | |
171 | <para>Pick a suitable mode automatically using heuristics</para> | |
172 | </listitem> | |
173 | </varlistentry> | |
174 | ||
175 | <varlistentry> | |
176 | <term>max</term> | |
177 | <listitem> | |
178 | <para>Pick the highest-numbered available mode</para> | |
179 | </listitem> | |
180 | </varlistentry> | |
181 | ||
182 | <varlistentry> | |
183 | <term>keep</term> | |
184 | <listitem> | |
185 | <para>Keep the mode selected by firmware (the default)</para> | |
186 | </listitem> | |
187 | </varlistentry> | |
188 | </variablelist> | |
189 | ||
190 | </listitem> | |
191 | </varlistentry> | |
192 | ||
193 | <varlistentry> | |
194 | <term>editor</term> | |
195 | ||
196 | <listitem><para>Takes a boolean argument. Enable (the default) or disable the | |
197 | editor. The editor should be disabled if the machine can be accessed by | |
198 | unauthorized persons.</para></listitem> | |
199 | </varlistentry> | |
200 | ||
201 | <varlistentry> | |
202 | <term>auto-entries</term> | |
203 | ||
204 | <listitem><para>Takes a boolean argument. Enable (the default) or disable | |
205 | entries for other boot entries found on the boot partition. In particular, | |
206 | this may be useful when loader entries are created to show replacement | |
207 | descriptions for those entries.</para></listitem> | |
208 | </varlistentry> | |
209 | ||
210 | <varlistentry> | |
211 | <term>auto-firmware</term> | |
212 | ||
e6cab77e JJ |
213 | <listitem><para>A boolean controlling the presence of the "Reboot into firmware" entry |
214 | (enabled by default). If this is disabled, the firmware interface may still be reached | |
215 | by using the <keycap>f</keycap> key.</para></listitem> | |
f37d3835 | 216 | </varlistentry> |
39867bb9 | 217 | |
85d2f13b JJ |
218 | <varlistentry> |
219 | <term>beep</term> | |
220 | ||
97e7d494 | 221 | <listitem><para>Takes a boolean argument. If timeout enabled beep every second, otherwise beep n times when n-th entry in boot menu is selected (default disabled). |
cc25bedb | 222 | Currently, only x86 is supported, where it uses the PC speaker.</para></listitem> |
85d2f13b JJ |
223 | </varlistentry> |
224 | ||
e6b0cfad VD |
225 | <varlistentry> |
226 | <term>secure-boot-enroll</term> | |
227 | ||
228 | <listitem><para>Danger: this feature might soft-brick your device if used improperly.</para> | |
229 | ||
1e8e7f44 JJ |
230 | <para>Controls enrollment of secure boot keys found on the ESP if the system is in setup mode: |
231 | <variablelist> | |
232 | <varlistentry> | |
233 | <term><option>off</option></term> | |
234 | <listitem><para>No action is taken.</para></listitem> | |
235 | </varlistentry> | |
236 | ||
237 | <varlistentry> | |
238 | <term><option>manual</option></term> | |
239 | <listitem><para>Boot entries for found secure boot keys are created that allow manual | |
240 | enrollment.</para></listitem> | |
241 | </varlistentry> | |
242 | ||
243 | <varlistentry> | |
244 | <term><option>if-safe</option></term> | |
245 | <listitem><para>Same behavior as <option>manual</option>, but will try to automatically | |
246 | enroll the key <literal>auto</literal> if it is considered to be safe. Currently, this is only | |
247 | the case if the system is running inside a virtual machine.</para></listitem> | |
248 | </varlistentry> | |
249 | ||
250 | <varlistentry> | |
251 | <term><option>force</option></term> | |
252 | <listitem><para>Always enroll the <literal>auto</literal> key if found. Note that a warning | |
253 | message with a timeout will still be shown if this operation is unknown to be safe.</para></listitem> | |
254 | </varlistentry> | |
255 | </variablelist> | |
256 | </para> | |
e6b0cfad | 257 | |
8b9f0921 ZJS |
258 | <para>The different sets of variables can be set up under |
259 | <filename>/loader/keys/<replaceable>NAME</replaceable></filename> where | |
260 | <replaceable>NAME</replaceable> is the name that is going to be used as the name of the entry. This | |
261 | allows one to ship multiple sets of Secure Boot variables and choose which one to enroll at runtime. | |
262 | </para> | |
e6b0cfad | 263 | |
8b9f0921 ZJS |
264 | <para>Supported Secure Boot variables are one database for authorized images, one key exchange key |
265 | (KEK) and one platform key (PK). For more information, refer to the <ulink | |
266 | url="https://uefi.org/specifications">UEFI specification</ulink>, under Secure Boot and Driver | |
267 | Signing. Another resource that describe the interplay of the different variables is the | |
e6b0cfad VD |
268 | <ulink url="https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/uefi_secure_boot"> |
269 | EDK2 documentation</ulink>.</para> | |
270 | ||
adb9485a JJ |
271 | <para>A complete set of UEFI variable includes <filename>db.auth</filename>, <filename>KEK.auth</filename> |
272 | and <filename>PK.auth</filename>. Note that these files need to be authenticated UEFI variables. See | |
e6b0cfad VD |
273 | below for an example of how to generate them from regular X.509 keys.</para> |
274 | ||
f234a56d | 275 | <programlisting>uuid=$(systemd-id128 new --uuid) |
e6b0cfad | 276 | for key in PK KEK db; do |
f234a56d | 277 | openssl req -new -x509 -subj "/CN=${key}/" -keyout "${key}.key" -out "${key}.crt" |
6ba14371 JJ |
278 | openssl x509 -outform DER -in "${key}.crt" -out "${key}.der" |
279 | sbsiglist --owner "${uuid}" --type x509 --output "${key}.esl" "${key}.der" | |
e6b0cfad VD |
280 | done |
281 | ||
adb9485a JJ |
282 | for key in MicWinProPCA2011_2011-10-19.crt MicCorUEFCA2011_2011-06-27.crt MicCorKEKCA2011_2011-06-24.crt; do |
283 | curl "https://www.microsoft.com/pkiops/certs/${key}" --output "${key}" | |
284 | sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output "${key%crt}esl" "${key}" | |
285 | done | |
286 | ||
287 | # Optionally add Microsoft Windows Production CA 2011 (needed to boot into Windows). | |
7a17e41d | 288 | cat MicWinProPCA2011_2011-10-19.esl >>db.esl |
adb9485a | 289 | |
6ba14371 | 290 | # Optionally add Microsoft Corporation UEFI CA 2011 for firmware drivers / option ROMs |
adb9485a JJ |
291 | # and third-party boot loaders (including shim). This is highly recommended on real |
292 | # hardware as not including this may soft-brick your device (see next paragraph). | |
7a17e41d | 293 | cat MicCorUEFCA2011_2011-06-27.esl >>db.esl |
adb9485a JJ |
294 | |
295 | # Optionally add Microsoft Corporation KEK CA 2011. Recommended if either of the | |
296 | # Microsoft keys is used as the official UEFI revocation database is signed with this | |
297 | # key. The revocation database can be updated with <citerefentry><refentrytitle>fwupdmgr</refentrytitle><manvolnum>1</manvolnum></citerefentry>. | |
7a17e41d | 298 | cat MicCorKEKCA2011_2011-06-24.esl >>KEK.esl |
adb9485a | 299 | |
6ba14371 JJ |
300 | attr=NON_VOLATILE,RUNTIME_ACCESS,BOOTSERVICE_ACCESS,TIME_BASED_AUTHENTICATED_WRITE_ACCESS |
301 | sbvarsign --attr ${attr} --key PK.key --cert PK.crt --output PK.auth PK PK.esl | |
302 | sbvarsign --attr ${attr} --key PK.key --cert PK.crt --output KEK.auth KEK KEK.esl | |
303 | sbvarsign --attr ${attr} --key KEK.key --cert KEK.crt --output db.auth db db.esl | |
e6b0cfad VD |
304 | </programlisting> |
305 | ||
306 | <para>This feature is considered dangerous because even if all the required files are signed with the | |
307 | keys being loaded, some files necessary for the system to function properly still won't be. This | |
308 | is especially the case with Option ROMs (e.g. for storage controllers or graphics cards). See | |
309 | <ulink url="https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom">Secure Boot and Option ROMs</ulink> | |
310 | for more details.</para></listitem> | |
311 | </varlistentry> | |
312 | ||
661615a0 JJ |
313 | <varlistentry> |
314 | <term>reboot-for-bitlocker</term> | |
315 | ||
deb5c820 LP |
316 | <listitem><para>Caveat: This feature is experimental, and is likely to be changed (or removed in its |
317 | current form) in a future version of systemd.</para> | |
318 | ||
319 | <para>Work around BitLocker requiring a recovery key when the boot loader was | |
320 | updated (disabled by default).</para> | |
661615a0 | 321 | |
8b9f0921 ZJS |
322 | <para>Try to detect BitLocker encrypted drives along with an active TPM. If both are found and |
323 | Windows Boot Manager is selected in the boot menu, set the <literal>BootNext</literal> EFI variable | |
324 | and restart the system. The firmware will then start Windows Boot Manager directly, leaving the TPM | |
325 | PCRs in expected states so that Windows can unseal the encryption key. This allows | |
326 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> to | |
327 | be updated without having to provide the recovery key for BitLocker drive unlocking.</para> | |
661615a0 JJ |
328 | |
329 | <para>Note that the PCRs that Windows uses can be configured with the | |
330 | <literal>Configure TPM platform validation profile for native UEFI firmware configurations</literal> | |
331 | group policy under <literal>Computer Configuration\Administrative Templates\Windows Components\BitLocker Drive Encryption</literal>. | |
8b9f0921 | 332 | When Secure Boot is enabled, changing this to PCRs <literal>0,2,7,11</literal> should be safe. |
661615a0 JJ |
333 | The TPM key protector needs to be removed and then added back for the PCRs on an already |
334 | encrypted drive to change. If PCR 4 is not measured, this setting can be disabled to speed | |
335 | up booting into Windows.</para></listitem> | |
336 | </varlistentry> | |
f37d3835 ZJS |
337 | </variablelist> |
338 | </refsect1> | |
339 | ||
340 | <refsect1> | |
341 | <title>Example</title> | |
342 | ||
343 | <programlisting># /boot/efi/loader/loader.conf | |
344 | timeout 0 | |
345 | default 01234567890abcdef1234567890abdf0-* | |
346 | editor no | |
347 | </programlisting> | |
348 | ||
349 | <para>The menu will not be shown by default (the menu can still be shown by | |
350 | pressing and holding a key during boot). One of the entries with files with a | |
351 | name starting with <literal>01234567890abcdef1234567890abdf0-</literal> will be | |
352 | selected by default. If more than one entry matches, the one with the highest | |
353 | priority will be selected (generally the one with the highest version number). | |
354 | The editor will be disabled, so it is not possible to alter the kernel command | |
355 | line.</para> | |
356 | </refsect1> | |
357 | ||
358 | <refsect1> | |
359 | <title>See Also</title> | |
360 | <para> | |
70c8db75 | 361 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, |
f37d3835 ZJS |
362 | <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
363 | </para> | |
364 | </refsect1> | |
365 | </refentry> |