1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="loader.conf" conditional='HAVE_GNU_EFI'
7    xmlns:xi="http://www.w3.org/2001/XInclude">
8  <refentryinfo>
9    <title>loader.conf</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>loader.conf</refentrytitle>
15    <manvolnum>5</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>loader.conf</refname>
20    <refpurpose>Configuration file for systemd-boot</refpurpose>
21  </refnamediv>
22
23  <refsynopsisdiv>
24    <para><filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>,
25    <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename>
26    <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/*.conf</filename>
27    </para>
28  </refsynopsisdiv>
29
30  <refsect1>
31    <title>Description</title>
32
33    <para>
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
36    <literal>.conf</literal> extension under
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
39    partition (XBOOTLDR) as defined by <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
40    Specification</ulink>.
41    </para>
42
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>
47
48    <para>Boolean arguments may be written as
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>.
51    </para>
52  </refsect1>
53
54  <refsect1>
55    <title>Options</title>
56
57    <para>The configuration options supported by
58    <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename> and
59    <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/*.conf</filename> files are defined as part
60    of the <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
61    Specification</ulink>.</para>
62
63    <para>The following configuration are supported by the <filename>loader.conf</filename> configuration
64    file:</para>
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.
73        </para>
74
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
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>
113        </table></listitem>
114      </varlistentry>
115
116      <varlistentry>
117        <term>timeout</term>
118
119        <listitem><para>How long the boot menu should be shown before the default
120        entry is booted, in seconds. This may be changed in the boot menu itself and
121        will be stored as an EFI variable in that case, overriding this option.
122        </para>
123
124        <para>If set to <literal>menu-hidden</literal> or <literal>0</literal> no menu
125        is shown and the default entry will be booted immediately. The menu can be shown
126        by pressing and holding a key before systemd-boot is launched. Setting this to
127        <literal>menu-force</literal> disables the timeout while always showing the menu.</para>
128        </listitem>
129      </varlistentry>
130
131      <varlistentry>
132        <term>console-mode</term>
133
134        <listitem><para>This option configures the resolution of the console. Takes a
135        number or one of the special values listed below. The following values may be
136        used:</para>
137
138        <variablelist>
139          <varlistentry>
140            <term>0</term>
141            <listitem>
142              <para>Standard UEFI 80x25 mode</para>
143            </listitem>
144          </varlistentry>
145
146          <varlistentry>
147            <term>1</term>
148            <listitem>
149              <para>80x50 mode, not supported by all devices</para>
150            </listitem>
151          </varlistentry>
152
153          <varlistentry>
154            <term>2</term>
155            <listitem>
156              <para>the first non-standard mode provided by the device
157              firmware, if any</para>
158            </listitem>
159          </varlistentry>
160
161          <varlistentry>
162            <term>auto</term>
163            <listitem>
164              <para>Pick a suitable mode automatically using heuristics</para>
165            </listitem>
166          </varlistentry>
167
168          <varlistentry>
169            <term>max</term>
170            <listitem>
171              <para>Pick the highest-numbered available mode</para>
172            </listitem>
173          </varlistentry>
174
175          <varlistentry>
176            <term>keep</term>
177            <listitem>
178              <para>Keep the mode selected by firmware (the default)</para>
179            </listitem>
180          </varlistentry>
181        </variablelist>
182
183        </listitem>
184      </varlistentry>
185
186      <varlistentry>
187        <term>editor</term>
188
189        <listitem><para>Takes a boolean argument. Enable (the default) or disable the
190        editor. The editor should be disabled if the machine can be accessed by
191        unauthorized persons.</para></listitem>
192      </varlistentry>
193
194      <varlistentry>
195        <term>auto-entries</term>
196
197        <listitem><para>Takes a boolean argument. Enable (the default) or disable
198        entries for other boot entries found on the boot partition. In particular,
199        this may be useful when loader entries are created to show replacement
200        descriptions for those entries.</para></listitem>
201      </varlistentry>
202
203      <varlistentry>
204        <term>auto-firmware</term>
205
206        <listitem><para>A boolean controlling the presence of the "Reboot into firmware" entry
207        (enabled by default). If this is disabled, the firmware interface may still be reached
208        by using the <keycap>f</keycap> key.</para></listitem>
209      </varlistentry>
210
211      <varlistentry>
212        <term>beep</term>
213
214        <listitem><para>Beep n times when the n-th entry in the boot menu is shown (default disabled).
215        Currently, only x86 is supported, where it uses the PC speaker.</para></listitem>
216      </varlistentry>
217
218      <varlistentry>
219        <term>reboot-for-bitlocker</term>
220
221        <listitem><para>Caveat: This feature is experimental, and is likely to be changed (or removed in its
222        current form) in a future version of systemd.</para>
223
224        <para>Work around BitLocker requiring a recovery key when the boot loader was
225        updated (disabled by default).</para>
226
227        <para>Try to detect BitLocker encrypted drives along with an active TPM. If both are found
228        and Windows Boot Manager is selected in the boot menu, set the <literal>BootNext</literal>
229        EFI variable and restart the system. The firmware will then start Windows Boot Manager
230        directly, leaving the TPM PCRs in expected states so that Windows can unseal the encryption
231        key. This allows systemd-boot to be updated without having to provide the recovery key for
232        BitLocker drive unlocking.</para>
233
234        <para>Note that the PCRs that Windows uses can be configured with the
235        <literal>Configure TPM platform validation profile for native UEFI firmware configurations</literal>
236        group policy under <literal>Computer Configuration\Administrative Templates\Windows Components\BitLocker Drive Encryption</literal>.
237        When secure boot is enabled, changing this to PCRs <literal>0,2,7,11</literal> should be safe.
238        The TPM key protector needs to be removed and then added back for the PCRs on an already
239        encrypted drive to change. If PCR 4 is not measured, this setting can be disabled to speed
240        up booting into Windows.</para></listitem>
241      </varlistentry>
242
243      <varlistentry>
244        <term>random-seed-mode</term>
245
246        <listitem><para>Takes one of <literal>off</literal>, <literal>with-system-token</literal> and
247        <literal>always</literal>. If <literal>off</literal> no random seed data is read off the ESP, nor
248        passed to the OS. If <literal>with-system-token</literal> (the default)
249        <command>systemd-boot</command> will read a random seed from the ESP (from the file
250        <filename>/loader/random-seed</filename>) only if the <varname>LoaderSystemToken</varname> EFI
251        variable is set, and then derive the random seed to pass to the OS from the combination. If
252        <literal>always</literal> the boot loader will do so even if <varname>LoaderSystemToken</varname> is
253        not set. This mode is useful in environments where protection against OS image reuse is not a
254        concern, and the random seed shall be used even with no further setup in place. Use <command>bootctl
255        random-seed</command> to initialize both the random seed file in the ESP and the system token EFI
256        variable.</para>
257
258        <para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further
259        information.</para></listitem>
260      </varlistentry>
261    </variablelist>
262  </refsect1>
263
264  <refsect1>
265    <title>Example</title>
266
267    <programlisting># /boot/efi/loader/loader.conf
268timeout 0
269default 01234567890abcdef1234567890abdf0-*
270editor no
271    </programlisting>
272
273    <para>The menu will not be shown by default (the menu can still be shown by
274    pressing and holding a key during boot). One of the entries with files with a
275    name starting with <literal>01234567890abcdef1234567890abdf0-</literal> will be
276    selected by default. If more than one entry matches, the one with the highest
277    priority will be selected (generally the one with the highest version number).
278    The editor will be disabled, so it is not possible to alter the kernel command
279    line.</para>
280  </refsect1>
281
282  <refsect1>
283      <title>See Also</title>
284      <para>
285        <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
286        <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
287      </para>
288  </refsect1>
289</refentry>
290