1
1
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-23 17:34:00 +03:00

Merge pull request #9350 from poettering/bls-fixes

various fixes to the systemd-boot documentation
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2018-06-20 22:22:06 +02:00 committed by GitHub
commit 4e6acc912d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 77 additions and 51 deletions

7
NEWS
View File

@ -302,6 +302,13 @@ CHANGES WITH 239 in spe:
https://github.com/systemd/systemd/blob/master/doc/PORTABLE_SERVICES.md
https://github.com/systemd/systemd/blob/master/doc/CODE_QUALITY.md
* The Boot Loader Specification has been added to the source tree.
https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md
While moving it into our source tree we have updated it and further
changes are now accepted through the usual github PR workflow.
* pam_systemd will now look for PAM userdata fields systemd.memory_max,
systemd.tasks_max, systemd.cpu_weight, systemd.io_weight set by
earlier PAM modules. The data in these fields is used to initialize

View File

@ -34,12 +34,14 @@ The EFI specification provides a boot options logic that can offer similar funct
Everything described below is located on a placeholder file system `$BOOT`. The installer program should pick `$BOOT` according to the following rules:
* If the OS is installed on a disk with MBR disk label, and a partition with the MBR type id of 0xEA already exists it should be used as `$BOOT`.
* Otherwise, if the the OS is installed on a disk with MBR disk label, a new partition with MBR type id of 0xEA shall be created, of a suitable size (let's say 500MB), and it should be used as `$BOOT`.
* If the OS is installed on a disk with GPT disk label, and a partition with the GPT type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 already exists, it should be used as `$BOOT`.
* Otherwise, if the OS is installed on a disk with GPT disk label, and an ESP partition (i.e. with the GPT type UID of c12a7328-f81f-11d2-ba4b-00a0c93ec93b) already exists and is large enough (let's say 250MB) and otherwise qualifies, it should be used as `$BOOT`.
* Otherwise, if the OS is installed on a disk with GPT disk label, and if the ESP partition already exists but is too small, a new suitably sized (let's say 500MB) partition with GPT type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 shall be created and it should be used as `$BOOT`.
* Otherwise, if the OS is installed on a disk with GPT disk label, and no ESP partition exists yet, a new suitably sized (let's say 500MB) ESP should be created and should be used as `$BOOT`.
* On disks with MBR disk labels
* If the OS is installed on a disk with MBR disk label, and a partition with the MBR type id of 0xEA already exists it should be used as `$BOOT`.
* Otherwise, if the the OS is installed on a disk with MBR disk label, a new partition with MBR type id of 0xEA shall be created, of a suitable size (let's say 500MB), and it should be used as `$BOOT`.
* On disks with GPT disk labels
* If the OS is installed on a disk with GPT disk label, and a partition with the GPT type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 already exists, it should be used as `$BOOT`.
* Otherwise, if the OS is installed on a disk with GPT disk label, and an ESP partition (i.e. with the GPT type UID of c12a7328-f81f-11d2-ba4b-00a0c93ec93b) already exists and is large enough (let's say 250MB) and otherwise qualifies, it should be used as `$BOOT`.
* Otherwise, if the OS is installed on a disk with GPT disk label, and if the ESP partition already exists but is too small, a new suitably sized (let's say 500MB) partition with GPT type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 shall be created and it should be used as `$BOOT`.
* Otherwise, if the OS is installed on a disk with GPT disk label, and no ESP partition exists yet, a new suitably sized (let's say 500MB) ESP should be created and should be used as `$BOOT`.
This placeholder file system shall be determined during _installation time_, and an fstab entry maybe be created. It should be mounted to either /boot or /efi. Additional locations like /boot/efi, with /boot being a separate file system, might be supported by implementations. This is not recommended because the mounting of `$BOOT` is then dependent on and requires the mounting of the intermediate file system.
@ -64,12 +66,13 @@ These configuration snippets shall be Unix-style text files (i.e. line separatio
* `version` shall contain a human readable version string for this menu item. This is usually the kernel version and is intended for use by OSes to install multiple kernel versions at the same time with the same `title` field. This field shall be in a syntax that is useful for Debian-style version sorts, so that the boot loader UI can determine the newest version easily and show it first or preselect it automatically. This field is optional. Example: `3.7.2-201.fc18.x86_64`
* `machine-id` shall contain the machine ID of the OS `/etc/machine-id`. This is useful for boot loaders and applications to filter out boot entries, for example to show only a single newest kernel per OS, or to group items by OS, or to maybe filter out the currently booted OS in UIs that want to show only other installed operating systems. This ID shall be formatted as 32 lower case hexadecimal characters (i.e. without any UUID formatting). This key is optional. Example: `4098b3f648d74c13b1f04ccfba7798e8`
* `linux` refers to the kernel to spawn, and shall be a path relative to the `$BOOT` directory. It is recommended that every distribution creates a machine id and version specific subdirectory below `$BOOT` and places its kernels and initial RAM disk images there. Example: `/6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux`.
* `initrd` refers to the initrd to use when executing the kernel. This also shall be a path relative to the `$BOOT` directory. This key is optional. Example: `6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd`
* `initrd` refers to the initrd to use when executing the kernel. This also shall be a path relative to the `$BOOT` directory. This key is optional. This key may appear more than once in which case all specified images are used, in the order they are listed. Example: `6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd`
* `efi` to spawn arbitrary EFI programs. This also takes a path relative to `$BOOT`. This key is only available on EFI systems.
* `options` shall contain kernel parameters to pass to the Linux kernel to spawn. This key is optional.
* `devicetree` refers to the binary device tree to use when executing the
kernel. This also shall be a path relative to the `$BOOT` directory. This
key is optional. Example: `6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.armv7hl/tegra20-paz00.dtb`
* `architecture` refers to the UEFI architecture this entry is defined for. If specified and this does not match the local UEFI system architecture the entry is hidden.
Each configuration drop-in snippet must include at least a `linux` or an `efi` key, and is otherwise not valid. Here's an example for a complete drop-in file:
@ -131,8 +134,7 @@ There are a couple of items that are out of focus for this specifications:
## Links
<strike>http://www.freedesktop.org/wiki/Software/gummiboot/</strike><br>
https://www.freedesktop.org/software/systemd/man/systemd-boot.html<br>
https://www.freedesktop.org/software/systemd/man/bootctl.html
[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)
http://pkgs.fedoraproject.org/cgit/grub2.git/tree/0460-blscfg-add-blscfg-module-to-parse-Boot-Loader-Specif.patch?h=f20
[Obsolete patch adding Boot Loader Specification support to GNU grub 2](http://pkgs.fedoraproject.org/cgit/grub2.git/tree/0460-blscfg-add-blscfg-module-to-parse-Boot-Loader-Specif.patch?h=f20)

View File

@ -126,7 +126,7 @@
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader Specification</ulink>,
<ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>,
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
</para>
</refsect1>

View File

@ -167,7 +167,7 @@
<para>
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>
<ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>
</para>
</refsect1>

View File

@ -25,47 +25,50 @@
<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. systemd-boot is only useful on machines using UEFI.
</para>
<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
supports systems with an UEFI firmware only.</para>
<para>systemd-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. systemd-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>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>
<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 systemd-boot itself.</para>
<itemizedlist>
<listitem><para>Boot entries defined with <ulink
url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
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>
<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
<listitem><para>Unified kernel images following the <ulink
url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot
Loader Specification</ulink>, as executable EFI binaries in
<filename>/EFI/Linux/</filename> on the ESP</para></listitem>
<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
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
</refsect1>
<refsect1>
<title>Configuration</title>
<para>systemd-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>
@ -171,7 +174,7 @@
<term>7</term>
<term>8</term>
<term>9</term>
<listitem><para>Entry number 1 .. 9</para></listitem>
<listitem><para>Boot entry number 1 … 9</para></listitem>
</varlistentry>
</variablelist>
@ -219,14 +222,28 @@
</para>
</refsect1>
<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
url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP. Unified kernel boot entries
following the <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot
Loader Specification</ulink> are read from <filename>/EFI/Linux/</filename> on the ESP.</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>
<ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>,
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
</para>
</refsect1>
</refentry>