man/loader.conf.xml

   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='ENABLE_BOOTLOADER'
   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://uapi-group.org/specifications/specs/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://uapi-group.org/specifications/specs/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>
 114
 115         <para>Supported glob wildcard patterns are <literal>?</literal>, <literal>*</literal>, and
 116         <literal>[…]</literal> (including ranges). Note that these patterns use the same syntax as
 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
 120         list</command>).</para></listitem>
 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
 131         <para>If set to <literal>menu-hidden</literal> or <literal>0</literal> (the default) no menu
 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>
 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
 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>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term>beep</term>
 220
 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).
 222         Currently, only x86 is supported, where it uses the PC speaker.</para></listitem>
 223       </varlistentry>
 224
 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
 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>
 257
 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>
 263
 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
 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
 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
 273         below for an example of how to generate them from regular X.509 keys.</para>
 274
 275         <programlisting>uuid=$(systemd-id128 new --uuid)
 276 for key in PK KEK db; do
 277   openssl req -new -x509 -subj "/CN=${key}/" -keyout "${key}.key" -out "${key}.crt"
 278   openssl x509 -outform DER -in "${key}.crt" -out "${key}.der"
 279   sbsiglist --owner "${uuid}" --type x509 --output "${key}.esl" "${key}.der"
 280 done
 281
 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).
 288 cat MicWinProPCA2011_2011-10-19.esl >>db.esl
 289
 290 # Optionally add Microsoft Corporation UEFI CA 2011 for firmware drivers / option ROMs
 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).
 293 cat MicCorUEFCA2011_2011-06-27.esl >>db.esl
 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 project='man-pages'><refentrytitle>fwupdmgr</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 298 cat MicCorKEKCA2011_2011-06-24.esl >>KEK.esl
 299
 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
 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
 313       <varlistentry>
 314         <term>reboot-for-bitlocker</term>
 315
 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>
 321
 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>
 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>.
 332         When Secure Boot is enabled, changing this to PCRs <literal>0,2,7,11</literal> should be safe.
 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>
 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>
 361         <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 362         <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 363       </para>
 364   </refsect1>
 365 </refentry>