| <?xml version='1.0'?> <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
| |
| <refentry id="loader.conf" conditional='HAVE_GNU_EFI' |
| 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> |
| <refpurpose>Configuration file for systemd-boot</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <para><filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>, |
| <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename> |
| <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/*.conf</filename> |
| </para> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para> |
| <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> will |
| read <filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>, and any files with the |
| <literal>.conf</literal> extension under |
| <filename><replaceable>ESP</replaceable>/loader/entries/</filename> on the EFI system partition (ESP), |
| and <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/</filename> on the extended boot loader |
| partition (XBOOTLDR) as defined by <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader |
| Specification</ulink>. |
| </para> |
| |
| <para>Each of these configuration files must consist of series of newline (i.e. ASCII code 10) separated |
| lines, each consisting 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. The |
| files use UTF-8 encoding.</para> |
| |
| <para>Boolean arguments may be written as |
| <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>. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>The configuration options supported by |
| <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename> and |
| <filename><replaceable>XBOOTLDR</replaceable>/loader/entries/*.conf</filename> files are defined as part |
| of the <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader |
| Specification</ulink>.</para> |
| |
| <para>The following configuration are supported by the <filename>loader.conf</filename> configuration |
| file:</para> |
| |
| <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. |
| </para> |
| |
| <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> |
| |
| <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> |
| </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> |
| |
| <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> |
| </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> |
| |
| <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> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>beep</term> |
| |
| <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> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>reboot-for-bitlocker</term> |
| |
| <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> |
| |
| <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> |
| |
| <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 |
| concern, and the random seed shall be used even with no further setup in place. Use <command>bootctl |
| random-seed</command> to initialize both the random seed file in the ESP and the system token EFI |
| variable.</para> |
| |
| <para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further |
| information.</para></listitem> |
| </varlistentry> |
| </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> |
| <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| </refentry> |