From 4f4226283b54fa0553cd553bc0ee52fe82ef5dc4 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 Jun 2018 11:13:22 +0200 Subject: [PATCH 1/7] doc: add a second indentation level to partition list, to separate MBR and GPT partitions --- doc/BOOT_LOADER_SPECIFICATION.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/BOOT_LOADER_SPECIFICATION.md b/doc/BOOT_LOADER_SPECIFICATION.md index d31bd341f7..796a621b1e 100644 --- a/doc/BOOT_LOADER_SPECIFICATION.md +++ b/doc/BOOT_LOADER_SPECIFICATION.md @@ -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. From a893ec6a93f71d5391600c2bca845d6952f029ae Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 Jun 2018 11:13:41 +0200 Subject: [PATCH 2/7] doc: update BLS links list let's make these proper links --- doc/BOOT_LOADER_SPECIFICATION.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/BOOT_LOADER_SPECIFICATION.md b/doc/BOOT_LOADER_SPECIFICATION.md index 796a621b1e..d6c9cb39a0 100644 --- a/doc/BOOT_LOADER_SPECIFICATION.md +++ b/doc/BOOT_LOADER_SPECIFICATION.md @@ -133,8 +133,7 @@ There are a couple of items that are out of focus for this specifications: ## Links -http://www.freedesktop.org/wiki/Software/gummiboot/
-https://www.freedesktop.org/software/systemd/man/systemd-boot.html
-https://www.freedesktop.org/software/systemd/man/bootctl.html +[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
+[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) From 1d8a48e8e3b52a2fa18d094489c2cfe298b5b51b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 Jun 2018 11:54:52 +0200 Subject: [PATCH 3/7] doc: allow multiple initrd entries per BLS snippet sd-boot already supports that anyway, and the Fedora folks asked for this on the fedora mailing list, hence let's simply add this. --- doc/BOOT_LOADER_SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/BOOT_LOADER_SPECIFICATION.md b/doc/BOOT_LOADER_SPECIFICATION.md index d6c9cb39a0..ef5b1c5c86 100644 --- a/doc/BOOT_LOADER_SPECIFICATION.md +++ b/doc/BOOT_LOADER_SPECIFICATION.md @@ -66,7 +66,7 @@ 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 From 48a7ebb877f8d8d4fe4939334e31bfac87514fb6 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 Jun 2018 11:55:45 +0200 Subject: [PATCH 4/7] doc: document the `architecture` setting --- doc/BOOT_LOADER_SPECIFICATION.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/BOOT_LOADER_SPECIFICATION.md b/doc/BOOT_LOADER_SPECIFICATION.md index ef5b1c5c86..dc67f2ffc8 100644 --- a/doc/BOOT_LOADER_SPECIFICATION.md +++ b/doc/BOOT_LOADER_SPECIFICATION.md @@ -72,6 +72,7 @@ These configuration snippets shall be Unix-style text files (i.e. line separatio * `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: From 41e3f73dc24f1372e7a817ed80e12b35489eb3fb Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 Jun 2018 11:56:39 +0200 Subject: [PATCH 5/7] man: fix URL to BLS Let's refer to our own version now. --- man/bootctl.xml | 2 +- man/kernel-install.xml | 2 +- man/systemd-boot.xml | 5 ++--- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/man/bootctl.xml b/man/bootctl.xml index 0f8d0e0147..9521dc9d98 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -126,7 +126,7 @@ See Also systemd-boot7, - Boot Loader Specification, + Boot Loader Specification, Boot Loader Interface diff --git a/man/kernel-install.xml b/man/kernel-install.xml index 6d8201af1a..cd9756662a 100644 --- a/man/kernel-install.xml +++ b/man/kernel-install.xml @@ -167,7 +167,7 @@ machine-id5, os-release5, - Boot loader specification + Boot Loader Specification diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 09efbd34a5..0a1543d590 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -224,9 +224,8 @@ bootctl1, loader.conf5, - Boot Loader Specification, - Boot Loader Interface, - upstream wiki page + Boot Loader Specification, + Boot Loader Interface From 53ddb667a9ac3462c490af14c5c533bf9f60104b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 Jun 2018 11:59:11 +0200 Subject: [PATCH 6/7] man: update systemd-boot(7) man page in many ways Let's fully document where the list of entries come from, including unified images and such. Let's add a "Files" section (replacing the "Configuration" section), and let's move it after they keybinding section (why? because keybinds are primary UI material, while configuration is one level more complex than that). Also, reword lot's of stuff to make it more precise. Fixes: #5127 --- man/systemd-boot.xml | 88 ++++++++++++++++++++++++++------------------ 1 file changed, 53 insertions(+), 35 deletions(-) diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 0a1543d590..5cd8a38152 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -25,47 +25,50 @@ Description - systemd-boot or sd-boot is a simple - UEFI boot manager, previously known as gummiboot. 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. - + systemd-boot (short: sd-boot) 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. - systemd-boot loads information from the EFI system partition (ESP), usually - mounted at /boot, /efi, or - /boot/efi. Configuration file fragments, kernels, initrds, - other EFI images need to reside on the ESP. Linux kernels must be built with - 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 Boot Loader - Specification located under /loader/entries/ on the - ESP. + systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at + /boot, /efi, or /boot/efi 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 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: - kernel-install8 - may be used to copy kernel images onto the ESP and to generate entries compliant - with the Boot Loader Specification. - bootctl1 - may be used from a running system to locate the ESP, list available entries, and - install systemd-boot itself. + + Boot entries defined with Boot Loader + Specification description files located in /loader/entries/ on the ESP. These + usually describe Linux kernel images with associated initrd images, but alternatively may also describe + arbitrary other EFI executables. - systemd-boot will provide information about the time spent in UEFI firmware - using the - Boot Loader Interface. - This information can be displayed using + Unified kernel images following the Boot + Loader Specification, as executable EFI binaries in + /EFI/Linux/ on the ESP + + The Microsoft Windows EFI boot manager, if installed + + The Apple MacOS X boot manager, if installed + + The EFI Shell binary, if installed + + A reboot into the UEFI firmware setup option, if supported by the firmware + + + kernel-install8 may be + used to copy kernel images onto the ESP and to generate description files compliant with the Boot Loader + Specification. bootctl1 may be + used from a running system to locate the ESP, list available entries, and install systemd-boot itself. + + systemd-boot will provide information about the time spent in UEFI firmware using the Boot Loader Interface. This + information can be displayed using systemd-analyze1. - - Configuration - - systemd-boot reads configuration like the timeout and default entry from - /loader/loader.conf on the ESP and from EFI variables. See - loader.conf5. - - - Key bindings The following keys may be used in the boot menu: @@ -171,7 +174,7 @@ 7 8 9 - Entry number 1 .. 9 + Boot entry number 1 … 9 @@ -219,6 +222,21 @@ + + Files + + The files systemd-boot reads generally reside on the UEFI ESP which is usually mounted to + /boot/, /efi/ or /boot/efi during OS + runtime. systemd-boot reads runtime configuration such as the boot timeout and default entry from + /loader/loader.conf on the ESP (in combination with data read from EFI variables). See + loader.conf5. Boot entry + description files following the Boot Loader + Specification are read from /loader/entries/ on the ESP. Unified kernel boot entries + following the Boot + Loader Specification are read from /EFI/Linux/ on the ESP. + + See Also From d69061080172b3805b9824b582ec870f53af3531 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 Jun 2018 11:54:25 +0200 Subject: [PATCH 7/7] NEWS: document that the BLS is now part of our tree --- NEWS | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/NEWS b/NEWS index ddf6b031e7..10f632216f 100644 --- a/NEWS +++ b/NEWS @@ -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