picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

man: add some basic documentation for sd-boot (#8379) 

I'm sure this can be improved in various ways, but I think
it's a good start.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2018-03-11 11:22:09 +01:00 committed by Yu Watanabe
parent 9aa2e409bc
commit f37d383582
4 changed files with 462 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
man/bootctl.xml
View File

@ -68,32 +68,37 @@
<refsect1>
<title>Description</title>
<para><command>bootctl</command> checks, updates,
installs or removes the boot loader from the current
system.</para>
<para><command>bootctl</command> can check the EFI boot loader status, list
available entries, and install, update, or remove the
<citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
boot loader on the current system.</para>
<para><command>bootctl status</command> checks and prints the
currently installed versions of the boot loader binaries and
all current EFI boot variables.</para>
<para><command>bootctl status</command> shows the currently installed versions of
the boot loader binaries and all current EFI boot variables.</para>
<para><command>bootctl list</command> displays all configured boot loader entries.
</para>
<para><command>bootctl update</command> updates all installed versions of systemd-boot, if the current version is
newer than the version installed in the EFI system partition. This also includes the EFI default/fallback loader at
<filename>/EFI/BOOT/BOOT*.EFI</filename>. A systemd-boot entry in the EFI boot variables is created if there is no
current entry. The created entry will be added to the end of the boot order list.</para>
<para><command>bootctl update</command> updates all installed versions of
<citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
if the current version is newer than the version installed in the EFI system
partition. This also includes the EFI default/fallback loader at
<filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. A
systemd-boot entry in the EFI boot variables is created if there is no current
entry. The created entry will be added to the end of the boot order list.</para>
<para><command>bootctl install</command> installs systemd-boot into the EFI system partition. A copy of
systemd-boot will be stored as the EFI default/fallback loader at <filename>/EFI/BOOT/BOOT*.EFI</filename>. A
systemd-boot entry in the EFI boot variables is created and added to the top of the boot order list.</para>
<para><command>bootctl install</command> installs systemd-boot into the EFI
system partition. A copy of systemd-boot will be stored as the EFI
default/fallback loader at
<filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. A
systemd-boot entry in the EFI boot variables is created and added to the top of
the boot order list.</para>
<para><command>bootctl remove</command> removes all installed
versions of systemd-boot from the EFI system partition, and removes
systemd-boot from the EFI boot variables.</para>
<para><command>bootctl remove</command> removes all installed versions of
systemd-boot from the EFI system partition, and removes systemd-boot from the EFI
boot variables.</para>
<para>If no command is passed, <command>status</command> is
implied.</para>
<para>If no command is passed, <command>status</command> is implied.</para>
</refsect1>
<refsect1>
@ -134,8 +139,9 @@
<refsect1>
<title>See Also</title>
<para>
<ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">systemd boot loader interface</ulink>
<citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader Specification</ulink>,
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
</para>
</refsect1>
</refentry>

194
man/loader.conf.xml Normal file
View File

@ -0,0 +1,194 @@
<?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+ -->
<refentry id="loader.conf" conditional='ENABLE_EFI'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>loader.conf</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>I wrote this page</contrib>
<firstname>Zbigniew</firstname>
<surname>Jędrzejewski-Szmek</surname>
<email>zbyszek@in.waw.pl</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>loader.conf</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>loader.conf</refname>
<refpurpose>Configuration file for sd-boot</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>,
<filename><replaceable>ESP</replaceable>/loader/loader.conf.d/*.conf</filename>
</para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
will read <filename>/loader/loader.conf</filename> and any files with the
<literal>.conf</literal> extension under
<filename>/loader/loader.conf.d/</filename> on the EFI system partition (ESP).
</para>
<para>Each configuration file must consist of an option name, followed by
whitespace, and the option value. <literal>#</literal> may be used to start
a comment line. Empty and comment lines are ignored.</para>
<para>Boolean arguments may be written as
<literal>yes</literal>/<literal>y</literal>/<literal>true</literal>/<literal>1</literal> or
<literal>no</literal>/<literal>n</literal>/<literal>false</literal>/<literal>0</literal>.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>The following configuration options are understood:</para>
<variablelist>
<varlistentry>
<term>default</term>
<listitem><para>A glob pattern to select the default entry. The default entry
may be changed in the boot menu itself, in which case the name of the
selected entry will be stored as an EFI variable, overriding this option.
</para></listitem>
</varlistentry>
<varlistentry>
<term>timeout</term>
<listitem><para>How long the boot menu should be shown before the default
entry is booted, in seconds. This may be changed in the boot menu itself and
will be stored as an EFI variable in that case, overriding this option.
</para>
<para>If the timeout is disabled, the default entry will be booted
immediately. The menu can be shown by pressing and holding a key before
sd-boot is launched.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>console-mode</term>
<listitem><para>This option configures the resolution of the console. Takes a
number or one of the special values listed below. The following values may be
used:</para>
<variablelist>
<varlistentry>
<term>0</term>
<listitem>
<para>Standard UEFI 80x25 mode</para>
</listitem>
</varlistentry>
<varlistentry>
<term>1</term>
<listitem>
<para>80x50 mode, not supported by all devices</para>
</listitem>
</varlistentry>
<varlistentry>
<term>2</term>
<listitem>
<para>the first non-standard mode provided by the device
firmware, if any</para>
</listitem>
</varlistentry>
<varlistentry>
<term>auto</term>
<listitem>
<para>Pick a suitable mode automatically using heuristics</para>
</listitem>
</varlistentry>
<varlistentry>
<term>max</term>
<listitem>
<para>Pick the highest-numbered available mode</para>
</listitem>
</varlistentry>
<varlistentry>
<term>keep</term>
<listitem>
<para>Keep the mode selected by firmware (the default)</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>editor</term>
<listitem><para>Takes a boolean argument. Enable (the default) or disable the
editor. The editor should be disabled if the machine can be accessed by
unauthorized persons.</para></listitem>
</varlistentry>
<varlistentry>
<term>auto-entries</term>
<listitem><para>Takes a boolean argument. Enable (the default) or disable
entries for other boot entries found on the boot partition. In particular,
this may be useful when loader entries are created to show replacement
descriptions for those entries.</para></listitem>
</varlistentry>
<varlistentry>
<term>auto-firmware</term>
<listitem><para>Takes a boolean argument. Enable (the default) or disable
the "Reboot into firmware" entry.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Example</title>
<programlisting># /boot/efi/loader/loader.conf
timeout 0
default 01234567890abcdef1234567890abdf0-*
editor no
</programlisting>
<para>The menu will not be shown by default (the menu can still be shown by
pressing and holding a key during boot). One of the entries with files with a
name starting with <literal>01234567890abcdef1234567890abdf0-</literal> will be
selected by default. If more than one entry matches, the one with the highest
priority will be selected (generally the one with the highest version number).
The editor will be disabled, so it is not possible to alter the kernel command
line.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

2
man/rules/meson.build
View File

@ -25,6 +25,7 @@ manpages = [
['kernel-command-line', '7', [], ''],
['kernel-install', '8', [], ''],
['libudev', '3', [], ''],
['loader.conf', '5', [], 'ENABLE_EFI'],
['locale.conf', '5', [], ''],
['localectl', '1', [], 'ENABLE_LOCALED'],
['localtime', '5', [], ''],
@ -44,6 +45,7 @@ manpages = [
['pam_systemd', '8', [], 'HAVE_PAM'],
['resolved.conf', '5', ['resolved.conf.d'], 'ENABLE_RESOLVE'],
['runlevel', '8', [], 'ENABLE_UTMP'],
['sd-boot', '7', [], 'ENABLE_EFI'],
['sd-bus-errors',
'3',
['SD_BUS_ERROR_ACCESS_DENIED',

240
man/sd-boot.xml Normal file
View File

@ -0,0 +1,240 @@
<?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+ -->
<refentry id="sd-boot" conditional='ENABLE_EFI'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd-boot</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>I wrote this page</contrib>
<firstname>Zbigniew</firstname>
<surname>Jędrzejewski-Szmek</surname>
<email>zbyszek@in.waw.pl</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd-boot</refentrytitle>
<manvolnum>7</manvolnum>
</refmeta>
<refnamediv>
<refname>sd-boot</refname>
<refpurpose>A simple UEFI boot manager</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para><command>systemd-boot</command> or <command>sd-boot</command> is a simple
UEFI boot manager, previously known as <command>gummiboot</command>. It provides
a graphical menu to select the entry to boot and an editor for the kernel command
line. sd-boot is only useful on machines using UEFI.
</para>
<para>sd-boot loads information from the EFI system partition (ESP), usually
mounted at <filename>/boot</filename>, <filename>/efi</filename>, or
<filename>/boot/efi</filename>. Configuration file fragments, kernels, initrds,
other EFI images 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. sd-boot will automatically list other boot entries registered as EFI boot
variables, and a list of kernels from configuration files following the <ulink
url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader
Specification</ulink> located under <filename>/loader/entries/</filename> on the
ESP.</para>
<para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
may be used to copy kernel images onto the ESP and to generate entries 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 sd-boot itself.</para>
<para>sd-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
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
</refsect1>
<refsect1>
<title>Configuration</title>
<para>sd-boot reads configuration like the timeout and default entry from
<filename>/loader/loader.conf</filename> on the ESP and from EFI variables. See
<citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</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>
<listitem><para>Show sd-boot, UEFI, and firmware versions</para></listitem>
</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>
<listitem><para>Entry number 1 .. 9</para></listitem>
</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>
<para>Note that unless configured otherwise in the UEFI firmware, sd-boot will
use the US keyboard layout, so key labels might not match for keys like +/-.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader Specification</ulink>,
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>,
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/">upstream wiki page</ulink>
</para>
</refsect1>
</refentry>