2018-03-11 10:22:09 +00:00
|
|
|
<?xml version='1.0'?> <!--*-nxml-*-->
|
2019-03-14 13:40:58 +00:00
|
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
2018-03-11 10:22:09 +00:00
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
2020-11-09 04:23:58 +00:00
|
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
2018-03-11 10:22:09 +00:00
|
|
|
|
2021-12-13 17:27:20 +00:00
|
|
|
<refentry id="loader.conf" conditional='HAVE_GNU_EFI'
|
2018-03-11 10:22:09 +00:00
|
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
|
|
<title>loader.conf</title>
|
|
|
|
<productname>systemd</productname>
|
|
|
|
</refentryinfo>
|
|
|
|
|
|
|
|
<refmeta>
|
|
|
|
<refentrytitle>loader.conf</refentrytitle>
|
|
|
|
<manvolnum>5</manvolnum>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>loader.conf</refname>
|
2018-06-15 05:25:22 +00:00
|
|
|
<refpurpose>Configuration file for systemd-boot</refpurpose>
|
2018-03-11 10:22:09 +00:00
|
|
|
</refnamediv>
|
|
|
|
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<para><filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>,
|
2018-11-25 21:58:28 +00:00
|
|
|
<filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename>
|
2018-03-11 10:22:09 +00:00
|
|
|
</para>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
2022-03-21 11:16:35 +00:00
|
|
|
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> will
|
|
|
|
read <filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>, and any files with the
|
2018-03-11 10:22:09 +00:00
|
|
|
<literal>.conf</literal> extension under
|
2022-03-21 11:16:35 +00:00
|
|
|
<filename><replaceable>ESP</replaceable>/loader/entries/</filename> on the EFI system partition (ESP) as
|
|
|
|
defined by <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>.
|
2018-03-11 10:22:09 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>Each configuration file must consist of an option name, followed by
|
|
|
|
whitespace, and the option value. <literal>#</literal> may be used to start
|
|
|
|
a comment line. Empty and comment lines are ignored.</para>
|
|
|
|
|
|
|
|
<para>Boolean arguments may be written as
|
2021-08-11 12:59:46 +00:00
|
|
|
<literal>yes</literal>/<literal>y</literal>/<literal>true</literal>/<literal>t</literal>/<literal>on</literal>/<literal>1</literal> or
|
|
|
|
<literal>no</literal>/<literal>n</literal>/<literal>false</literal>/<literal>f</literal>/<literal>off</literal>/<literal>0</literal>.
|
2018-03-11 10:22:09 +00:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Options</title>
|
|
|
|
|
2018-11-25 21:58:28 +00:00
|
|
|
<para>The following configuration options in <filename>loader.conf</filename> are understood:</para>
|
2018-03-11 10:22:09 +00:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>default</term>
|
|
|
|
|
|
|
|
<listitem><para>A glob pattern to select the default entry. The default entry
|
|
|
|
may be changed in the boot menu itself, in which case the name of the
|
|
|
|
selected entry will be stored as an EFI variable, overriding this option.
|
2021-08-14 11:06:37 +00:00
|
|
|
</para>
|
|
|
|
|
2021-10-28 11:00:13 +00:00
|
|
|
<para>If set to <literal>@saved</literal> the chosen entry will be saved as an EFI variable
|
|
|
|
on every boot and automatically selected the next time the boot loader starts.</para>
|
|
|
|
|
2021-08-14 11:06:37 +00:00
|
|
|
<table>
|
|
|
|
<title>Automatically detected entries will use the following names:</title>
|
|
|
|
|
|
|
|
<tgroup cols='2'>
|
|
|
|
<colspec colname='name' />
|
|
|
|
<colspec colname='expl' />
|
|
|
|
<thead>
|
|
|
|
<row>
|
|
|
|
<entry>Name</entry>
|
|
|
|
<entry>Description</entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<row>
|
|
|
|
<entry>auto-efi-default</entry>
|
|
|
|
<entry>EFI Default Loader</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>auto-efi-shell</entry>
|
|
|
|
<entry>EFI Shell</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>auto-osx</entry>
|
|
|
|
<entry>macOS</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>auto-reboot-to-firmware-setup</entry>
|
|
|
|
<entry>Reboot Into Firmware Interface</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>auto-windows</entry>
|
|
|
|
<entry>Windows Boot Manager</entry>
|
|
|
|
</row>
|
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</table></listitem>
|
2018-03-11 10:22:09 +00:00
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>timeout</term>
|
|
|
|
|
|
|
|
<listitem><para>How long the boot menu should be shown before the default
|
|
|
|
entry is booted, in seconds. This may be changed in the boot menu itself and
|
|
|
|
will be stored as an EFI variable in that case, overriding this option.
|
|
|
|
</para>
|
|
|
|
|
2021-09-16 08:25:10 +00:00
|
|
|
<para>If set to <literal>menu-hidden</literal> or <literal>0</literal> no menu
|
|
|
|
is shown and the default entry will be booted immediately. The menu can be shown
|
|
|
|
by pressing and holding a key before systemd-boot is launched. Setting this to
|
|
|
|
<literal>menu-force</literal> disables the timeout while always showing the menu.</para>
|
2018-03-11 10:22:09 +00:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>console-mode</term>
|
|
|
|
|
|
|
|
<listitem><para>This option configures the resolution of the console. Takes a
|
|
|
|
number or one of the special values listed below. The following values may be
|
|
|
|
used:</para>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>0</term>
|
|
|
|
<listitem>
|
|
|
|
<para>Standard UEFI 80x25 mode</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>1</term>
|
|
|
|
<listitem>
|
|
|
|
<para>80x50 mode, not supported by all devices</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>2</term>
|
|
|
|
<listitem>
|
|
|
|
<para>the first non-standard mode provided by the device
|
|
|
|
firmware, if any</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>auto</term>
|
|
|
|
<listitem>
|
|
|
|
<para>Pick a suitable mode automatically using heuristics</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>max</term>
|
|
|
|
<listitem>
|
|
|
|
<para>Pick the highest-numbered available mode</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>keep</term>
|
|
|
|
<listitem>
|
|
|
|
<para>Keep the mode selected by firmware (the default)</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>editor</term>
|
|
|
|
|
|
|
|
<listitem><para>Takes a boolean argument. Enable (the default) or disable the
|
|
|
|
editor. The editor should be disabled if the machine can be accessed by
|
|
|
|
unauthorized persons.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>auto-entries</term>
|
|
|
|
|
|
|
|
<listitem><para>Takes a boolean argument. Enable (the default) or disable
|
|
|
|
entries for other boot entries found on the boot partition. In particular,
|
|
|
|
this may be useful when loader entries are created to show replacement
|
|
|
|
descriptions for those entries.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>auto-firmware</term>
|
|
|
|
|
2021-10-20 10:15:03 +00:00
|
|
|
<listitem><para>A boolean controlling the presence of the "Reboot into firmware" entry
|
|
|
|
(enabled by default). If this is disabled, the firmware interface may still be reached
|
|
|
|
by using the <keycap>f</keycap> key.</para></listitem>
|
2018-03-11 10:22:09 +00:00
|
|
|
</varlistentry>
|
2019-07-22 12:19:33 +00:00
|
|
|
|
2022-01-14 13:27:08 +00:00
|
|
|
<varlistentry>
|
|
|
|
<term>beep</term>
|
|
|
|
|
2022-01-16 14:57:38 +00:00
|
|
|
<listitem><para>Beep n times when the n-th entry in the boot menu is shown (default disabled).
|
|
|
|
Currently, only x86 is supported, where it uses the PC speaker.</para></listitem>
|
2022-01-14 13:27:08 +00:00
|
|
|
</varlistentry>
|
|
|
|
|
2022-01-07 10:15:28 +00:00
|
|
|
<varlistentry>
|
|
|
|
<term>reboot-for-bitlocker</term>
|
|
|
|
|
2022-03-16 11:01:37 +00:00
|
|
|
<listitem><para>Caveat: This feature is experimental, and is likely to be changed (or removed in its
|
|
|
|
current form) in a future version of systemd.</para>
|
|
|
|
|
|
|
|
<para>Work around BitLocker requiring a recovery key when the boot loader was
|
|
|
|
updated (disabled by default).</para>
|
2022-01-07 10:15:28 +00:00
|
|
|
|
|
|
|
<para>Try to detect BitLocker encrypted drives along with an active TPM. If both are found
|
|
|
|
and Windows Boot Manager is selected in the boot menu, set the <literal>BootNext</literal>
|
|
|
|
EFI variable and restart the system. The firmware will then start Windows Boot Manager
|
|
|
|
directly, leaving the TPM PCRs in expected states so that Windows can unseal the encryption
|
|
|
|
key. This allows systemd-boot to be updated without having to provide the recovery key for
|
|
|
|
BitLocker drive unlocking.</para>
|
|
|
|
|
|
|
|
<para>Note that the PCRs that Windows uses can be configured with the
|
|
|
|
<literal>Configure TPM platform validation profile for native UEFI firmware configurations</literal>
|
|
|
|
group policy under <literal>Computer Configuration\Administrative Templates\Windows Components\BitLocker Drive Encryption</literal>.
|
|
|
|
When secure boot is enabled, changing this to PCRs <literal>0,2,7,11</literal> should be safe.
|
|
|
|
The TPM key protector needs to be removed and then added back for the PCRs on an already
|
|
|
|
encrypted drive to change. If PCR 4 is not measured, this setting can be disabled to speed
|
|
|
|
up booting into Windows.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2019-07-22 12:19:33 +00:00
|
|
|
<varlistentry>
|
|
|
|
<term>random-seed-mode</term>
|
|
|
|
|
|
|
|
<listitem><para>Takes one of <literal>off</literal>, <literal>with-system-token</literal> and
|
|
|
|
<literal>always</literal>. If <literal>off</literal> no random seed data is read off the ESP, nor
|
|
|
|
passed to the OS. If <literal>with-system-token</literal> (the default)
|
|
|
|
<command>systemd-boot</command> will read a random seed from the ESP (from the file
|
|
|
|
<filename>/loader/random-seed</filename>) only if the <varname>LoaderSystemToken</varname> EFI
|
|
|
|
variable is set, and then derive the random seed to pass to the OS from the combination. If
|
|
|
|
<literal>always</literal> the boot loader will do so even if <varname>LoaderSystemToken</varname> is
|
|
|
|
not set. This mode is useful in environments where protection against OS image reuse is not a
|
2020-03-22 18:00:21 +00:00
|
|
|
concern, and the random seed shall be used even with no further setup in place. Use <command>bootctl
|
2019-07-22 12:19:33 +00:00
|
|
|
random-seed</command> to initialize both the random seed file in the ESP and the system token EFI
|
2019-07-22 16:13:26 +00:00
|
|
|
variable.</para>
|
|
|
|
|
|
|
|
<para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further
|
|
|
|
information.</para></listitem>
|
2019-07-22 12:19:33 +00:00
|
|
|
</varlistentry>
|
2018-03-11 10:22:09 +00:00
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Example</title>
|
|
|
|
|
|
|
|
<programlisting># /boot/efi/loader/loader.conf
|
|
|
|
timeout 0
|
|
|
|
default 01234567890abcdef1234567890abdf0-*
|
|
|
|
editor no
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
<para>The menu will not be shown by default (the menu can still be shown by
|
|
|
|
pressing and holding a key during boot). One of the entries with files with a
|
|
|
|
name starting with <literal>01234567890abcdef1234567890abdf0-</literal> will be
|
|
|
|
selected by default. If more than one entry matches, the one with the highest
|
|
|
|
priority will be selected (generally the one with the highest version number).
|
|
|
|
The editor will be disabled, so it is not possible to alter the kernel command
|
|
|
|
line.</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
<para>
|
2018-06-15 05:25:22 +00:00
|
|
|
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
|
2018-03-11 10:22:09 +00:00
|
|
|
<citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|