man/systemd-boot.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   6
   7 <refentry id="systemd-boot" conditional='ENABLE_EFI'
   8     xmlns:xi="http://www.w3.org/2001/XInclude">
   9   <refentryinfo>
  10     <title>systemd-boot</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-boot</refentrytitle>
  16     <manvolnum>7</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-boot</refname>
  21     <refname>sd-boot</refname>
  22     <refpurpose>A simple UEFI boot manager</refpurpose>
  23   </refnamediv>
  24
  25   <refsect1>
  26     <title>Description</title>
  27
  28     <para><command>systemd-boot</command> (short: <command>sd-boot</command>) is a simple UEFI boot manager. It
  29     provides a graphical menu to select the entry to boot and an editor for the kernel command line. systemd-boot
  30     supports systems with UEFI firmware only.</para>
  31
  32     <para>systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at
  33     <filename>/boot</filename>, <filename>/efi</filename>, or <filename>/boot/efi</filename> during OS
  34     runtime. Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on
  35     the ESP. Linux kernels must be built with <option>CONFIG_EFI_STUB</option> to be able to be directly executed as an
  36     EFI image. During boot systemd-boot automatically assembles a list of boot entries from the following
  37     sources:</para>
  38
  39     <itemizedlist>
  40       <listitem><para>Boot entries defined with <ulink
  41       url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
  42       Specification</ulink> description files located in <filename>/loader/entries/</filename> on the ESP. These
  43       usually describe Linux kernel images with associated initrd images, but alternatively may also describe
  44       arbitrary other EFI executables.</para></listitem>
  45
  46       <listitem><para>Unified kernel images following the <ulink
  47       url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
  48       Specification</ulink>, as executable EFI binaries in <filename>/EFI/Linux/</filename> on the ESP.
  49       </para></listitem>
  50
  51       <listitem><para>The Microsoft Windows EFI boot manager, if installed</para></listitem>
  52
  53       <listitem><para>The Apple MacOS X boot manager, if installed</para></listitem>
  54
  55       <listitem><para>The EFI Shell binary, if installed</para></listitem>
  56
  57       <listitem><para>A reboot into the UEFI firmware setup option, if supported by the firmware</para></listitem>
  58     </itemizedlist>
  59
  60     <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> may be
  61     used to copy kernel images onto the ESP and to generate description files compliant with the Boot Loader
  62     Specification. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> may be
  63     used from a running system to locate the ESP, list available entries, and install systemd-boot itself.</para>
  64
  65     <para>systemd-boot will provide information about the time spent in UEFI firmware using the <ulink
  66     url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. This information can be displayed
  67     using <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  68     </para>
  69   </refsect1>
  70
  71   <refsect1>
  72     <title>Key bindings</title>
  73     <para>The following keys may be used in the boot menu:</para>
  74
  75     <variablelist>
  76       <varlistentry>
  77         <term><keycap>↑</keycap> (Up)</term>
  78         <term><keycap>↓</keycap> (Down)</term>
  79         <term><keycap>j</keycap></term>
  80         <term><keycap>k</keycap></term>
  81         <term><keycap>PageUp</keycap></term>
  82         <term><keycap>PageDown</keycap></term>
  83         <term><keycap>Home</keycap></term>
  84         <term><keycap>End</keycap></term>
  85         <listitem><para>Navigate up/down in the entry list</para></listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><keycap>↵</keycap> (Enter)</term>
  90         <listitem><para>Boot selected entry</para></listitem>
  91       </varlistentry>
  92
  93       <varlistentry>
  94         <term><keycap>d</keycap></term>
  95         <listitem><para>Make selected entry the default</para></listitem>
  96       </varlistentry>
  97
  98       <varlistentry>
  99         <term><keycap>e</keycap></term>
 100         <listitem><para>Edit the kernel command line for selected entry</para></listitem>
 101       </varlistentry>
 102
 103       <varlistentry>
 104         <term><keycap>+</keycap></term>
 105         <term><keycap>t</keycap></term>
 106         <listitem><para>Increase the timeout before default entry is booted</para></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><keycap>-</keycap></term>
 111         <term><keycap>T</keycap></term>
 112         <listitem><para>Decrease the timeout</para></listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><keycap>v</keycap></term>
 117         <listitem><para>Show systemd-boot, UEFI, and firmware versions</para></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><keycap>P</keycap></term>
 122         <listitem><para>Print status</para></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><keycap>Q</keycap></term>
 127         <listitem><para>Quit</para></listitem>
 128       </varlistentry>
 129
 130       <varlistentry>
 131         <term><keycap>h</keycap></term>
 132         <term><keycap>?</keycap></term>
 133         <listitem><para>Show a help screen</para></listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><keycombo><keycap>Ctrl</keycap><keycap>l</keycap></keycombo></term>
 138         <listitem><para>Reprint the screen</para></listitem>
 139       </varlistentry>
 140     </variablelist>
 141
 142     <para>The following keys may be used during bootup or in the boot menu to
 143     directly boot a specific entry:</para>
 144
 145     <variablelist>
 146       <varlistentry>
 147         <term><keycap>l</keycap></term>
 148         <listitem><para>Linux</para></listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term><keycap>w</keycap></term>
 153         <listitem><para>Windows</para></listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term><keycap>a</keycap></term>
 158         <listitem><para>OS X</para></listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><keycap>s</keycap></term>
 163         <listitem><para>EFI shell</para></listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><keycap>1</keycap></term>
 168         <term><keycap>2</keycap></term>
 169         <term><keycap>3</keycap></term>
 170         <term><keycap>4</keycap></term>
 171         <term><keycap>5</keycap></term>
 172         <term><keycap>6</keycap></term>
 173         <term><keycap>7</keycap></term>
 174         <term><keycap>8</keycap></term>
 175         <term><keycap>9</keycap></term>
 176         <listitem><para>Boot entry number 1 … 9</para></listitem>
 177       </varlistentry>
 178     </variablelist>
 179
 180     <para>In the editor, most keys simply insert themselves, but the following keys
 181     may be used to perform additional actions:</para>
 182
 183     <variablelist>
 184       <varlistentry>
 185         <term><keycap>←</keycap> (Left)</term>
 186         <term><keycap>→</keycap> (Right)</term>
 187         <term><keycap>Home</keycap></term>
 188         <term><keycap>End</keycap></term>
 189         <listitem><para>Navigate left/right</para></listitem>
 190       </varlistentry>
 191
 192       <varlistentry>
 193         <term><keycap>Esc</keycap></term>
 194         <listitem><para>Abort the edit and quit the editor</para></listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term><keycombo><keycap>Ctrl</keycap><keycap>k</keycap></keycombo></term>
 199         <listitem><para>Clear the command line</para></listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term><keycombo><keycap>Ctrl</keycap><keycap>w</keycap></keycombo></term>
 204         <term><keycombo><keycap>Alt</keycap><keycap>Backspace</keycap></keycombo></term>
 205         <listitem><para>Delete word backwards</para></listitem>
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term><keycombo><keycap>Alt</keycap><keycap>d</keycap></keycombo></term>
 210         <listitem><para>Delete word forwards</para></listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term><keycap>↵</keycap> (Enter)</term>
 215         <listitem><para>Boot entry with the edited command line</para></listitem>
 216       </varlistentry>
 217     </variablelist>
 218
 219     <para>Note that unless configured otherwise in the UEFI firmware, systemd-boot will
 220     use the US keyboard layout, so key labels might not match for keys like +/-.
 221     </para>
 222   </refsect1>
 223
 224   <refsect1>
 225     <title>Files</title>
 226
 227     <para>The files systemd-boot reads generally reside on the UEFI ESP which is usually mounted to
 228     <filename>/boot/</filename>, <filename>/efi/</filename> or <filename>/boot/efi</filename> during OS
 229     runtime. systemd-boot reads runtime configuration such as the boot timeout and default entry from
 230     <filename>/loader/loader.conf</filename> on the ESP (in combination with data read from EFI variables). See
 231     <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Boot entry
 232     description files following the <ulink
 233     url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
 234     Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP. Unified kernel boot entries
 235     following the <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot
 236     Loader Specification</ulink> are read from <filename>/EFI/Linux/</filename> on the ESP.</para>
 237   </refsect1>
 238
 239   <refsect1>
 240     <title>EFI Variables</title>
 241
 242     <para>The following EFI variables are defined, set and read by <command>systemd-boot</command>, under the vendor
 243     UUID <literal>4a67b082-0a4c-41cf-b6c7-440b29bb8c4</literal>, for communication between the OS and the boot
 244     loader:</para>
 245
 246     <variablelist class='efi-variables'>
 247       <varlistentry>
 248         <term><varname>LoaderBootCountPath</varname></term>
 249         <listitem><para>If boot counting is enabled, contains the path to the file in whose name the boot counters are
 250         encoded. Set by the boot
 251         loader. <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 252         uses this information to mark a boot as successful as determined by the successful activation of the
 253         <filename>boot-complete.target</filename> target unit.</para></listitem>
 254       </varlistentry>
 255
 256       <varlistentry>
 257         <term><varname>LoaderConfigTimeout</varname></term>
 258         <term><varname>LoaderConfigTimeoutOneShot</varname></term>
 259         <listitem><para>The menu timeout in seconds. Read by the boot loader. <varname>LoaderConfigTimeout</varname>
 260         is maintained persistently, while <varname>LoaderConfigTimeoutOneShot</varname> is a one-time override which is
 261         read once (in which case it takes precedence over <varname>LoaderConfigTimeout</varname>) and then
 262         removed. <varname>LoaderConfigTimeout</varname> may be manipulated with the
 263         <keycap>t</keycap>/<keycap>T</keycap> keys, see above.)</para></listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><varname>LoaderDevicePartUUID</varname></term>
 268
 269         <listitem><para>Contains the partition UUID of the EFI System Partition the boot loader was run from. Set by
 270         the boot
 271         loader. <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 272         uses this information to automatically find the disk booted from, in order to discover various other partitions
 273         on the same disk automatically.</para></listitem>
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term><varname>LoaderEntries</varname></term>
 278
 279         <listitem><para>A list of the identifiers of all discovered boot loader entries. Set by the boot
 280         loader.</para></listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term><varname>LoaderEntryDefault</varname></term>
 285         <term><varname>LoaderEntryOneShot</varname></term>
 286
 287         <listitem><para>The identifier of the default boot loader entry. Set primarily by the OS and read by the boot
 288         loader. <varname>LoaderEntryOneShot</varname> sets the default entry for the next boot only, while
 289         <varname>LoaderEntryDefault</varname> sets it persistently for all future
 290         boots. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 291         <option>set-default</option> and <option>set-oneshot</option> commands make use of these variables. The boot
 292         loader modifies <varname>LoaderEntryDefault</varname> on request, when the <keycap>d</keycap> key is used, see
 293         above.)</para></listitem>
 294       </varlistentry>
 295
 296       <varlistentry>
 297         <term><varname>LoaderEntrySelected</varname></term>
 298
 299         <listitem><para>The identifier of the boot loader entry currently being booted. Set by the boot
 300         loader.</para></listitem>
 301       </varlistentry>
 302
 303       <varlistentry>
 304         <term><varname>LoaderFeatures</varname></term>
 305
 306         <listitem><para>A set of flags indicating the features the boot loader supports. Set by the boot loader. Use
 307         <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this
 308         data.</para></listitem>
 309       </varlistentry>
 310
 311       <varlistentry>
 312         <term><varname>LoaderFirmwareInfo</varname></term>
 313         <term><varname>LoaderFirmwareType</varname></term>
 314
 315         <listitem><para>Brief firmware information. Set by the boot loader. Use
 316         <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this
 317         data.</para></listitem>
 318       </varlistentry>
 319
 320       <varlistentry>
 321         <term><varname>LoaderImageIdentifier</varname></term>
 322
 323         <listitem><para>The path of executable of the boot loader used for the current boot, relative to the EFI System
 324         Partition's root directory. Set by the boot loader. Use
 325         <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this
 326         data.</para></listitem>
 327       </varlistentry>
 328
 329       <varlistentry>
 330         <term><varname>LoaderInfo</varname></term>
 331
 332         <listitem><para>Brief information about the boot loader. Set by the boot loader. Use
 333         <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this
 334         data.</para></listitem>
 335       </varlistentry>
 336
 337       <varlistentry>
 338         <term><varname>LoaderTimeExecUSec</varname></term>
 339         <term><varname>LoaderTimeInitUSec</varname></term>
 340         <term><varname>LoaderTimeMenuUsec</varname></term>
 341
 342         <listitem><para>Information about the time spent in various parts of the boot loader. Set by the boot
 343         loader. Use <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 344         to view this data. These variables are defined by the <ulink
 345         url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para></listitem>
 346       </varlistentry>
 347     </variablelist>
 348   </refsect1>
 349
 350   <refsect1>
 351     <title>Boot Counting</title>
 352
 353     <para><command>systemd-boot</command> implements a simple boot counting mechanism on top of the <ulink
 354     url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, for automatic and unattended
 355     fallback to older kernel versions/boot loader entries when a specific entry continously fails. Any boot loader
 356     entry file and unified kernel image file that contains a <literal>+</literal> followed by one or two numbers (if
 357     two they need to be separated by a <literal>-</literal>), before the <filename>.conf</filename> or
 358     <filename>.efi</filename> suffix is subject to boot counting: the first of the two numbers ('tries left') is
 359     decreased by one on every boot attempt, the second of the two numbers ('tries done') is increased by one (if 'tries
 360     done' is absent it is considered equivalent to 0). Depending on the current value of these two counters the boot
 361     entry is considered to be in one of three states:</para>
 362
 363     <orderedlist>
 364       <listitem><para>If the 'tries left' counter of an entry is greater than zero the entry is considered to be in
 365       'indeterminate' state. This means the entry has not completed booting successfully yet, but also hasn't been
 366       determined not to work.</para></listitem>
 367
 368       <listitem><para>If the 'tries left' counter of an entry is zero it is considered to be in 'bad' state. This means
 369       no further attempts to boot this item will be made (that is, unless all other boot entries are also in 'bad'
 370       state), as all attempts to boot this entry have not completed successfully.</para></listitem>
 371
 372       <listitem><para>If the 'tries left' and 'tries done' counters of an entry are absent it is considered to be in
 373       'good' state. This means further boot counting for the entry is turned off, as it successfully booted at least
 374       once. The
 375       <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 376       service moves the currently booted entry from 'indeterminate' into 'good' state when a boot attempt completed
 377       successfully.</para></listitem>
 378     </orderedlist>
 379
 380     <para>Generally, when new entries are added to the boot loader, they first start out in 'indeterminate' state,
 381     i.e. with a 'tries left' counter greater than zero. The boot entry remains in this state until either it managed to
 382     complete a full boot successfully at least once (in which case it will be in 'good' state) — or the 'tries left'
 383     counter reaches zero (in which case it will be in 'bad' state).</para>
 384
 385     <para>Example: let's say a boot loader entry file <filename>foo.conf</filename> is set up for 3 boot tries. The
 386     installer will hence create it under the name <filename>foo+3.conf</filename>. On first boot, the boot loader will
 387     rename it to <filename>foo+2-1.conf</filename>. If that boot does not complete successfully, the boot loader will
 388     rename it to <filename>foo+1-2.conf</filename> on the following boot. If that fails too, it will finally be renamed
 389     <filename>foo+0-3.conf</filename> by the boot loader on next boot, after which it will be considered 'bad'. If the
 390     boot succeeds however the entry file will be renamed to <filename>foo.conf</filename> by the OS, so that it is
 391     considered 'good' from then on.</para>
 392
 393     <para>The boot menu takes the 'tries left' counter into account when sorting the menu entries: entries in 'bad'
 394     state are ordered at the end of the list, and entries in 'good' or 'indeterminate' at the beginning. The user can
 395     freely choose to boot any entry of the menu, including those already marked 'bad'. If the menu entry to boot is
 396     automatically determined, this means that 'good' or 'indeterminate' entries are generally preferred (as the top item of
 397     the menu is the one booted by default), and 'bad' entries will only be considered if there are no 'good' or
 398     'indeterminate' entries left.</para>
 399
 400     <para>The <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> kernel
 401     install framework optionally sets the initial 'tries left' counter to the value specified in
 402     <filename>/etc/kernel/tries</filename> when a boot loader entry is first created.</para>
 403   </refsect1>
 404
 405   <refsect1>
 406     <title>See Also</title>
 407     <para>
 408       <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 409       <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 410       <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 411       <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 412       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
 413       <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
 414     </para>
 415   </refsect1>
 416 </refentry>