2018-03-11 13:22:09 +03:00
<?xml version='1.0'?> <!-- * - nxml - * -->
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX - License - Identifier: LGPL - 2.1+ -->
2018-06-15 08:25:22 +03:00
<refentry id= "systemd-boot" conditional= 'ENABLE_EFI'
2018-03-11 13:22:09 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo >
2018-06-15 08:25:22 +03:00
<title > systemd-boot</title>
2018-03-11 13:22:09 +03:00
<productname > systemd</productname>
</refentryinfo>
<refmeta >
2018-06-15 08:25:22 +03:00
<refentrytitle > systemd-boot</refentrytitle>
2018-03-11 13:22:09 +03:00
<manvolnum > 7</manvolnum>
</refmeta>
<refnamediv >
2018-06-15 08:25:22 +03:00
<refname > systemd-boot</refname>
2018-03-11 13:22:09 +03:00
<refname > sd-boot</refname>
<refpurpose > A simple UEFI boot manager</refpurpose>
</refnamediv>
<refsect1 >
<title > Description</title>
2018-06-20 12:59:11 +03:00
<para > <command > systemd-boot</command> (short: <command > sd-boot</command> ) is a simple UEFI boot manager. It
provides a graphical menu to select the entry to boot and an editor for the kernel command line. systemd-boot
2018-06-22 14:03:21 +03:00
supports systems with UEFI firmware only.</para>
2018-06-20 12:59:11 +03:00
<para > systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at
<filename > /boot</filename> , <filename > /efi</filename> , or <filename > /boot/efi</filename> during OS
runtime. Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on
the ESP. Linux kernels must be built with <option > CONFIG_EFI_STUB</option> to be able to be directly executed as an
EFI image. During boot systemd-boot automatically assembles a list of boot entries from the following
sources:</para>
<itemizedlist >
<listitem > <para > Boot entries defined with <ulink
2018-10-12 15:00:20 +03:00
url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
2018-06-20 12:59:11 +03:00
Specification</ulink> description files located in <filename > /loader/entries/</filename> on the ESP. These
usually describe Linux kernel images with associated initrd images, but alternatively may also describe
arbitrary other EFI executables.</para> </listitem>
<listitem > <para > Unified kernel images following the <ulink
2018-10-12 15:00:20 +03:00
url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
2018-06-22 14:03:21 +03:00
Specification</ulink> , as executable EFI binaries in <filename > /EFI/Linux/</filename> on the ESP.
</para> </listitem>
2018-06-20 12:59:11 +03:00
<listitem > <para > The Microsoft Windows EFI boot manager, if installed</para> </listitem>
<listitem > <para > The Apple MacOS X boot manager, if installed</para> </listitem>
<listitem > <para > The EFI Shell binary, if installed</para> </listitem>
<listitem > <para > A reboot into the UEFI firmware setup option, if supported by the firmware</para> </listitem>
</itemizedlist>
<para > <citerefentry > <refentrytitle > kernel-install</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> may be
used to copy kernel images onto the ESP and to generate description files compliant with the Boot Loader
Specification. <citerefentry > <refentrytitle > bootctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> may be
used from a running system to locate the ESP, list available entries, and install systemd-boot itself.</para>
<para > systemd-boot will provide information about the time spent in UEFI firmware using the <ulink
url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink> . This
information can be displayed using
2018-03-11 13:22:09 +03:00
<citerefentry > <refentrytitle > systemd-analyze</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> .
</para>
</refsect1>
<refsect1 >
<title > Key bindings</title>
<para > The following keys may be used in the boot menu:</para>
<variablelist >
<varlistentry >
<term > ↑ (Up)</term>
<term > ↓ (Down)</term>
<term > j</term>
<term > k</term>
<term > PageUp</term>
<term > PageDown</term>
<term > Home</term>
<term > End</term>
<listitem > <para > Navigate up/down in the entry list</para> </listitem>
</varlistentry>
<varlistentry >
<term > ↵ (Enter)</term>
<listitem > <para > Boot selected entry</para> </listitem>
</varlistentry>
<varlistentry >
<term > d</term>
<listitem > <para > Make selected entry the default</para> </listitem>
</varlistentry>
<varlistentry >
<term > e</term>
<listitem > <para > Edit the kernel command line for selected entry</para> </listitem>
</varlistentry>
<varlistentry >
<term > +</term>
<term > t</term>
<listitem > <para > Increase the timeout before default entry is booted</para> </listitem>
</varlistentry>
<varlistentry >
<term > -</term>
<term > T</term>
<listitem > <para > Decrease the timeout</para> </listitem>
</varlistentry>
<varlistentry >
<term > v</term>
2018-06-15 08:25:22 +03:00
<listitem > <para > Show systemd-boot, UEFI, and firmware versions</para> </listitem>
2018-03-11 13:22:09 +03:00
</varlistentry>
<varlistentry >
<term > P</term>
<listitem > <para > Print status</para> </listitem>
</varlistentry>
<varlistentry >
<term > Q</term>
<listitem > <para > Quit</para> </listitem>
</varlistentry>
<varlistentry >
<term > h</term>
<term > ?</term>
<listitem > <para > Show a help screen</para> </listitem>
</varlistentry>
<varlistentry >
<term > Ctrl + l</term>
<listitem > <para > Reprint the screen</para> </listitem>
</varlistentry>
</variablelist>
<para > The following keys may be used during bootup or in the boot menu to
directly boot a specific entry:</para>
<variablelist >
<varlistentry >
<term > l</term>
<listitem > <para > Linux</para> </listitem>
</varlistentry>
<varlistentry >
<term > w</term>
<listitem > <para > Windows</para> </listitem>
</varlistentry>
<varlistentry >
<term > a</term>
<listitem > <para > OS X</para> </listitem>
</varlistentry>
<varlistentry >
<term > s</term>
<listitem > <para > EFI shell</para> </listitem>
</varlistentry>
<varlistentry >
<term > 1</term>
<term > 2</term>
<term > 3</term>
<term > 4</term>
<term > 5</term>
<term > 6</term>
<term > 7</term>
<term > 8</term>
<term > 9</term>
2018-06-20 12:59:11 +03:00
<listitem > <para > Boot entry number 1 … 9</para> </listitem>
2018-03-11 13:22:09 +03:00
</varlistentry>
</variablelist>
<para > In the editor, most keys simply insert themselves, but the following keys
may be used to perform additional actions:</para>
<variablelist >
<varlistentry >
<term > ← (Left)</term>
<term > → (Right)</term>
<term > Home</term>
<term > End</term>
<listitem > <para > Navigate left/right</para> </listitem>
</varlistentry>
<varlistentry >
<term > Esc</term>
<listitem > <para > Abort the edit and quit the editor</para> </listitem>
</varlistentry>
<varlistentry >
<term > Ctrl + k</term>
<listitem > <para > Clear the command line</para> </listitem>
</varlistentry>
<varlistentry >
<term > Ctrl + w</term>
<term > Alt + Backspace</term>
<listitem > <para > Delete word backwards</para> </listitem>
</varlistentry>
<varlistentry >
<term > Alt + d </term>
<listitem > <para > Delete word forwards</para> </listitem>
</varlistentry>
<varlistentry >
<term > ↵ (Enter)</term>
<listitem > <para > Boot entry with the edited command line</para> </listitem>
</varlistentry>
</variablelist>
2018-06-15 08:25:22 +03:00
<para > Note that unless configured otherwise in the UEFI firmware, systemd-boot will
2018-03-11 13:22:09 +03:00
use the US keyboard layout, so key labels might not match for keys like +/-.
</para>
</refsect1>
2018-06-20 12:59:11 +03:00
<refsect1 >
<title > Files</title>
<para > The files systemd-boot reads generally reside on the UEFI ESP which is usually mounted to
<filename > /boot/</filename> , <filename > /efi/</filename> or <filename > /boot/efi</filename> during OS
runtime. systemd-boot reads runtime configuration such as the boot timeout and default entry from
<filename > /loader/loader.conf</filename> on the ESP (in combination with data read from EFI variables). See
<citerefentry > <refentrytitle > loader.conf</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> . Boot entry
description files following the <ulink
2018-10-12 15:00:20 +03:00
url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
2018-06-20 12:59:11 +03:00
Specification</ulink> are read from <filename > /loader/entries/</filename> on the ESP. Unified kernel boot entries
2018-10-12 15:00:20 +03:00
following the <ulink url= "https://systemd.io/BOOT_LOADER_SPECIFICATION" > Boot
2018-06-20 12:59:11 +03:00
Loader Specification</ulink> are read from <filename > /EFI/Linux/</filename> on the ESP.</para>
</refsect1>
2018-06-25 22:48:33 +03:00
<refsect1 >
<title > EFI Variables</title>
<para > The following EFI variables are defined, set and read by <command > systemd-boot</command> , under the vendor
UUID <literal > 4a67b082-0a4c-41cf-b6c7-440b29bb8c4</literal> , for communication between the OS and the boot
loader:</para>
<variablelist >
<varlistentry >
<term > <varname > LoaderBootCountPath</varname> </term>
<listitem > <para > If boot counting is enabled, contains the path to the file in whose name the boot counters are
encoded. Set by the boot
loader. <citerefentry > <refentrytitle > systemd-bless-boot.service</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry>
uses this information to mark a boot as successful as determined by the successful activation of the
<filename > boot-complete.target</filename> target unit.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderConfigTimeout</varname> </term>
<listitem > <para > The menu time-out. Read by the boot loader. (Also, modified by it when the
<keycap > t</keycap> /<keycap > T</keycap> keys are used, see above.)</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderDevicePartUUID</varname> </term>
<listitem > <para > Contains the partition UUID of the EFI System Partition the boot loader was run from. Set by
the boot
loader. <citerefentry > <refentrytitle > systemd-gpt-auto-generator</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry>
uses this information to automatically find the disk booted from, in order to discover various other partitions
on the same disk automatically.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderEntries</varname> </term>
<listitem > <para > A list of the identifiers of all discovered boot loader entries. Set by the boot
loader.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderEntryDefault</varname> </term>
<term > <varname > LoaderEntryOneShot</varname> </term>
<listitem > <para > The identifier of the default boot loader entry. Set primarily by the OS and read by the boot
loader. <varname > LoaderEntryOneShot</varname> sets the default entry for the next boot only, while
<varname > LoaderEntryDefault</varname> sets it persistently for all future
boots. <citerefentry > <refentrytitle > bootctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> 's
<option > set-default</option> and <option > set-oneshot</option> commands make use of these variables. The boot
loader modifies <varname > LoaderEntryDefault</varname> on request, when the <keycap > d</keycap> key is used, see
above.)</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderEntrySelected</varname> </term>
<listitem > <para > The identifier of the boot loader entry currently being booted. Set by the boot
loader.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderFirmwareInfo</varname> </term>
<term > <varname > LoaderFirmwareType</varname> </term>
<listitem > <para > Brief firmware information. Set by the boot loader. Use
<citerefentry > <refentrytitle > bootctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> to view this
data.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderImageIdentifier</varname> </term>
<listitem > <para > The path of executable of the boot loader used for the current boot, relative to the EFI System
Partition's root directory. Set by the boot loader. Use
<citerefentry > <refentrytitle > bootctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> to view this
data.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderInfo</varname> </term>
<listitem > <para > Brief information about the boot loader. Set by the boot loader. Use
<citerefentry > <refentrytitle > bootctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> to view this
data.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > LoaderTimeExecUSec</varname> </term>
<term > <varname > LoaderTimeInitUSec</varname> </term>
<term > <varname > LoaderTimeMenuUsec</varname> </term>
<listitem > <para > Information about the time spent in various parts of the boot loader. Set by the boot
loader. Use <citerefentry > <refentrytitle > systemd-analyze</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
to view this data. These variables are defined by the <ulink
url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader
Interface</ulink> .</para> </listitem>
</varlistentry>
</variablelist>
</refsect1>
2018-03-11 13:22:09 +03:00
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > bootctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > loader.conf</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> ,
2018-10-12 15:00:20 +03:00
<ulink url= "https://systemd.io/BOOT_LOADER_SPECIFICATION" > Boot Loader Specification</ulink> ,
2018-06-20 12:56:39 +03:00
<ulink url= "https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface" > Boot Loader Interface</ulink>
2018-03-11 13:22:09 +03:00
</para>
</refsect1>
</refentry>