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