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.5/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-poweroff</entry>
 105                 <entry>Power Off The System</entry>
 106               </row>
 107               <row>
 108                 <entry>auto-reboot</entry>
 109                 <entry>Reboot The System</entry>
 110               </row>
 111               <row>
 112                 <entry>auto-reboot-to-firmware-setup</entry>
 113                 <entry>Reboot Into Firmware Interface</entry>
 114               </row>
 115               <row>
 116                 <entry>auto-windows</entry>
 117                 <entry>Windows Boot Manager</entry>
 118               </row>
 119             </tbody>
 120           </tgroup>
 121         </table>
 122
 123         <para>Supported glob wildcard patterns are <literal>?</literal>, <literal>*</literal>, and
 124         <literal>[…]</literal> (including ranges). Note that these patterns use the same syntax as
 125         <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 126         but do not support all features. In particular, set negation and named character classes are not
 127         supported. The matching is done case-insensitively on the entry ID (as shown by <command>bootctl
 128         list</command>).</para>
 129
 130         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term>timeout</term>
 135
 136         <listitem><para>How long the boot menu should be shown before the default
 137         entry is booted, in seconds. This may be changed in the boot menu itself and
 138         will be stored as an EFI variable in that case, overriding this option.
 139         </para>
 140
 141         <para>If set to <literal>menu-disabled</literal> or <literal>menu-hidden</literal> or <literal>0</literal>
 142         (the default), no menu is shown and the default entry will be booted immediately. Unless
 143         <literal>menu-disabled</literal> is used, the menu can be shown
 144         by pressing and holding a key before systemd-boot is launched. Setting this to
 145         <literal>menu-force</literal> disables the timeout while always showing the menu.</para>
 146
 147         <xi:include href="version-info.xml" xpointer="v239"/>
 148         </listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term>console-mode</term>
 153
 154         <listitem><para>This option configures the resolution of the console. This may be changed in
 155         the boot menu itself and will be stored as an EFI variable in that case, overriding this
 156         option.</para>
 157
 158         <para>Takes a number or one of the special values listed below. The following
 159         values may be used:</para>
 160
 161         <variablelist>
 162           <varlistentry>
 163             <term>0</term>
 164             <listitem>
 165               <para>Standard UEFI 80x25 mode</para>
 166
 167             <xi:include href="version-info.xml" xpointer="v239"/>
 168             </listitem>
 169           </varlistentry>
 170
 171           <varlistentry>
 172             <term>1</term>
 173             <listitem>
 174               <para>80x50 mode, not supported by all devices</para>
 175
 176             <xi:include href="version-info.xml" xpointer="v239"/>
 177             </listitem>
 178           </varlistentry>
 179
 180           <varlistentry>
 181             <term>2</term>
 182             <listitem>
 183               <para>the first non-standard mode provided by the device
 184               firmware, if any</para>
 185
 186               <xi:include href="version-info.xml" xpointer="v239"/>
 187             </listitem>
 188           </varlistentry>
 189
 190           <varlistentry>
 191             <term>auto</term>
 192             <listitem>
 193               <para>Pick a suitable mode automatically using heuristics</para>
 194
 195             <xi:include href="version-info.xml" xpointer="v239"/>
 196             </listitem>
 197           </varlistentry>
 198
 199           <varlistentry>
 200             <term>max</term>
 201             <listitem>
 202               <para>Pick the highest-numbered available mode</para>
 203
 204             <xi:include href="version-info.xml" xpointer="v239"/>
 205             </listitem>
 206           </varlistentry>
 207
 208           <varlistentry>
 209             <term>keep</term>
 210             <listitem>
 211               <para>Keep the mode selected by firmware (the default)</para>
 212
 213             <xi:include href="version-info.xml" xpointer="v239"/>
 214             </listitem>
 215           </varlistentry>
 216         </variablelist>
 217
 218           <xi:include href="version-info.xml" xpointer="v239"/>
 219
 220         </listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term>editor</term>
 225
 226         <listitem><para>Takes a boolean argument. Enable (the default) or disable the
 227         editor. The editor should be disabled if the machine can be accessed by
 228         unauthorized persons.</para>
 229
 230         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term>auto-entries</term>
 235
 236         <listitem><para>Takes a boolean argument. Enable (the default) or disable
 237         entries for other boot entries found on the boot partition. In particular,
 238         this may be useful when loader entries are created to show replacement
 239         descriptions for those entries.</para>
 240
 241         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term>auto-firmware</term>
 246
 247         <listitem><para>A boolean controlling the presence of the <literal>Reboot Into Firmware
 248         Interface</literal> entry (enabled by default). If this is disabled, the firmware interface may still
 249         be reached by using the <keycap>f</keycap> key.</para>
 250
 251         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 252       </varlistentry>
 253
 254       <varlistentry>
 255         <term>beep</term>
 256
 257         <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).
 258         Currently, only x86 is supported, where it uses the PC speaker.</para>
 259
 260         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term>secure-boot-enroll</term>
 265
 266         <listitem><para>Danger: this feature might soft-brick your device if used improperly.</para>
 267
 268         <para>Controls enrollment of secure boot keys found on the ESP if the system is in setup mode:
 269         <variablelist>
 270           <varlistentry>
 271             <term><option>off</option></term>
 272             <listitem><para>No action is taken.</para>
 273
 274             <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 275           </varlistentry>
 276
 277           <varlistentry>
 278             <term><option>manual</option></term>
 279             <listitem><para>Boot entries for found secure boot keys are created that allow manual
 280             enrollment.</para>
 281
 282             <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 283           </varlistentry>
 284
 285           <varlistentry>
 286             <term><option>if-safe</option></term>
 287             <listitem><para>Same behavior as <option>manual</option>, but will try to automatically
 288             enroll the key <literal>auto</literal> if it is considered to be safe. Currently, this is only
 289             the case if the system is running inside a virtual machine.</para>
 290
 291             <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 292           </varlistentry>
 293
 294           <varlistentry>
 295             <term><option>force</option></term>
 296             <listitem><para>Always enroll the <literal>auto</literal> key if found. Note that a warning
 297             message with a timeout will still be shown if this operation is unknown to be safe.</para>
 298
 299             <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 300           </varlistentry>
 301         </variablelist>
 302         </para>
 303
 304         <para>The different sets of variables can be set up under
 305         <filename>/loader/keys/<replaceable>NAME</replaceable></filename> where
 306         <replaceable>NAME</replaceable> is the name that is going to be used as the name of the entry. This
 307         allows one to ship multiple sets of Secure Boot variables and choose which one to enroll at runtime.
 308         </para>
 309
 310         <para>Supported Secure Boot variables are one database for authorized images, one for the key
 311         exchange key (KEK) and one for the platform key (PK). For more information, refer to the
 312         <ulink url="https://uefi.org/specifications">UEFI specification</ulink>, under Secure Boot and Driver
 313         Signing. Another resource that describe the interplay of the different variables is the
 314         <ulink url="https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/uefi_secure_boot">
 315         EDK2 documentation</ulink>.</para>
 316
 317         <para>A complete set of UEFI variable includes <filename>db.auth</filename>, <filename>KEK.auth</filename>
 318         and <filename>PK.auth</filename>. Note that these files need to be authenticated UEFI variables. See
 319         below for an example of how to generate them from regular X.509 keys.</para>
 320
 321         <programlisting>uuid=$(systemd-id128 new --uuid)
 322 for key in PK KEK db; do
 323   openssl req -new -x509 -subj "/CN=${key}/" -keyout "${key}.key" -out "${key}.pem"
 324   openssl x509 -outform DER -in "${key}.pem" -out "${key}.der"
 325   sbsiglist --owner "${uuid}" --type x509 --output "${key}.esl" "${key}.der"
 326 done
 327
 328 # See also: <ulink url="https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/windows-secure-boot-key-creation-and-management-guidance">Windows Secure Boot Key Creation and Management Guidance</ulink>
 329 curl --location \
 330      "https://go.microsoft.com/fwlink/p/?linkid=321192" -o ms-db-2011.der \
 331      "https://go.microsoft.com/fwlink/p/?linkid=321185" -o ms-kek-2011.der \
 332      "https://go.microsoft.com/fwlink/p/?linkid=321194" -o ms-uefi-db-2011.der \
 333      "https://go.microsoft.com/fwlink/p/?linkid=2239776" -o ms-db-2023.der \
 334      "https://go.microsoft.com/fwlink/p/?linkid=2239775" -o ms-kek-2023.der \
 335      "https://go.microsoft.com/fwlink/p/?linkid=2239872" -o ms-uefi-db-2023.der
 336 sha1sum -c &lt;&lt;END
 337 580a6f4cc4e4b669b9ebdc1b2b3e087b80d0678d  ms-db-2011.der
 338 31590bfd89c9d74ed087dfac66334b3931254b30  ms-kek-2011.der
 339 46def63b5ce61cf8ba0de2e6639c1019d0ed14f3  ms-uefi-db-2011.der
 340 45a0fa32604773c82433c3b7d59e7466b3ac0c67  ms-db-2023.der
 341 459ab6fb5e284d272d5e3e6abc8ed663829d632b  ms-kek-2023.der
 342 b5eeb4a6706048073f0ed296e7f580a790b59eaa  ms-uefi-db-2023.der
 343 END
 344 for key in ms-*.der; do
 345   sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output "${key%der}esl" "${key}"
 346 done
 347
 348 # Optionally add Microsoft Windows certificates (needed to boot into Windows).
 349 cat ms-db-*.esl >>db.esl
 350
 351 # Optionally add Microsoft UEFI certificates for firmware drivers / option ROMs and third-party
 352 # boot loaders (including shim). This is highly recommended on real hardware as not including this
 353 # may soft-brick your device (see next paragraph).
 354 cat ms-uefi-*.esl >>db.esl
 355
 356 # Optionally add Microsoft KEK certificates. Recommended if either of the Microsoft keys is used as
 357 # the official UEFI revocation database is signed with this key. The revocation database can be
 358 # updated with <citerefentry project='man-pages'><refentrytitle>fwupdmgr</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 359 cat ms-kek-*.esl >>KEK.esl
 360
 361 attr=NON_VOLATILE,RUNTIME_ACCESS,BOOTSERVICE_ACCESS,TIME_BASED_AUTHENTICATED_WRITE_ACCESS
 362 sbvarsign --attr "${attr}" --key PK.key --cert PK.pem --output PK.auth PK PK.esl
 363 sbvarsign --attr "${attr}" --key PK.key --cert PK.pem --output KEK.auth KEK KEK.esl
 364 sbvarsign --attr "${attr}" --key KEK.key --cert KEK.pem --output db.auth db db.esl
 365         </programlisting>
 366
 367         <para>This feature is considered dangerous because even if all the required files are signed with the
 368         keys being loaded, some files necessary for the system to function properly still won't be. This
 369         is especially the case with Option ROMs (e.g. for storage controllers or graphics cards). See
 370         <ulink url="https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom">Secure Boot and Option ROMs</ulink>
 371         for more details.</para>
 372
 373         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 374       </varlistentry>
 375
 376       <varlistentry>
 377         <term>reboot-for-bitlocker</term>
 378
 379         <listitem><para>Caveat: This feature is experimental, and is likely to be changed (or removed in its
 380         current form) in a future version of systemd.</para>
 381
 382         <para>Work around BitLocker requiring a recovery key when the boot loader was
 383         updated (disabled by default).</para>
 384
 385         <para>Try to detect BitLocker encrypted drives along with an active TPM. If both are found and
 386         Windows Boot Manager is selected in the boot menu, set the <literal>BootNext</literal> EFI variable
 387         and restart the system. The firmware will then start Windows Boot Manager directly, leaving the TPM
 388         PCRs in expected states so that Windows can unseal the encryption key. This allows
 389         <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> to
 390         be updated without having to provide the recovery key for BitLocker drive unlocking.</para>
 391
 392         <para>Note that the PCRs that Windows uses can be configured with the
 393         <literal>Configure TPM platform validation profile for native UEFI firmware configurations</literal>
 394         group policy under <literal>Computer Configuration\Administrative Templates\Windows Components\BitLocker Drive Encryption</literal>.
 395         When Secure Boot is enabled, changing this to PCRs <literal>0,2,7,11</literal> should be safe.
 396         The TPM key protector needs to be removed and then added back for the PCRs on an already
 397         encrypted drive to change. If PCR 4 is not measured, this setting can be disabled to speed
 398         up booting into Windows.</para>
 399
 400         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 401       </varlistentry>
 402     </variablelist>
 403   </refsect1>
 404
 405   <refsect1>
 406     <title>Example</title>
 407
 408     <programlisting># /boot/efi/loader/loader.conf
 409 timeout 0
 410 default 01234567890abcdef1234567890abdf0-*
 411 editor no
 412     </programlisting>
 413
 414     <para>The menu will not be shown by default (the menu can still be shown by
 415     pressing and holding a key during boot). One of the entries with files with a
 416     name starting with <literal>01234567890abcdef1234567890abdf0-</literal> will be
 417     selected by default. If more than one entry matches, the one with the highest
 418     priority will be selected (generally the one with the highest version number).
 419     The editor will be disabled, so it is not possible to alter the kernel command
 420     line.</para>
 421   </refsect1>
 422
 423   <refsect1>
 424       <title>See Also</title>
 425       <para><simplelist type="inline">
 426         <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 427         <member><citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 428       </simplelist></para>
 429   </refsect1>
 430 </refentry>