From 55944e5e40b1be2afc4855d8d2baf4b73d1876b5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 22:49:52 +0200 Subject: Adding upstream version 255.4. Signed-off-by: Daniel Baumann --- man/systemd-boot.xml | 650 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 650 insertions(+) create mode 100644 man/systemd-boot.xml (limited to 'man/systemd-boot.xml') diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml new file mode 100644 index 0000000..2b0ea9b --- /dev/null +++ b/man/systemd-boot.xml @@ -0,0 +1,650 @@ + + + + + + + systemd-boot + systemd + + + + systemd-boot + 7 + + + + systemd-boot + sd-boot + A simple UEFI boot manager + + + + Description + + systemd-boot (short: sd-boot) is a simple UEFI boot + manager. It provides a textual menu to select the entry to boot and an editor for the kernel command + line. systemd-boot supports systems with UEFI firmware only. + + systemd-boot loads boot entry information from the EFI system partition (ESP), + usually mounted at /efi/, /boot/, or + /boot/efi/ during OS runtime, as well as from the Extended Boot Loader partition + (XBOOTLDR) if it exists (usually mounted to /boot/). Configuration file fragments, + kernels, initrds and other EFI images to boot generally need to reside on the ESP or the Extended Boot + Loader partition. 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: + + + Boot entries defined with Boot Loader Specification Type #1 + description files located in /loader/entries/ on the ESP and the Extended Boot + Loader Partition. These usually describe Linux kernel images with associated initrd images, but + alternatively may also describe other arbitrary EFI executables. + + Unified kernel images, Boot + Loader Specification Type #2, which are executable EFI binaries in + /EFI/Linux/ on the ESP and the Extended Boot Loader Partition. + + The Microsoft Windows EFI boot manager, if installed. + + The Apple macOS boot manager, if installed. + + The EFI Shell binary, if installed. + + A Reboot Into Firmware Interface option, if supported by the UEFI + firmware. + + Secure Boot variables enrollment if the UEFI firmware is in setup-mode and files are provided + on the ESP. + + + systemd-boot supports the following features: + + + Basic boot manager configuration changes (such as timeout + configuration, default boot entry selection, …) may be made directly from the boot loader UI at + boot-time, as well as during system runtime with EFI variables. + + The boot manager integrates with the systemctl command to implement + features such as systemctl reboot --boot-loader-entry=… (for rebooting into a + specific boot menu entry, i.e. "reboot into Windows") and systemctl reboot + --boot-loader-menu=… (for rebooting into the boot loader menu), by implementing the Boot Loader Interface. See + systemctl1 for + details. + + An EFI variable set by the boot loader informs the OS about the EFI System Partition used + during boot. This is then used to automatically mount the correct EFI System Partition to + /efi/ or /boot/ during OS runtime. See + systemd-gpt-auto-generator8 + for details. + + The boot manager provides information about the boot time spent in UEFI firmware using + the Boot Loader Interface. This + information can be displayed using + systemd-analyze1. + + + The boot manager implements boot counting and automatic fallback to older, working boot + entries on failure. See Automatic Boot + Assessment. + + The boot manager optionally reads a random seed from the ESP partition, combines it + with a 'system token' stored in a persistent EFI variable and derives a random seed to use by the OS as + entropy pool initialization, providing a full entropy pool during early boot. + + The boot manager allows for Secure Boot variables to be enrolled if the UEFI firmware is + in setup-mode. Additionally, variables can be automatically enrolled if configured. + + + bootctl1 + may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list + available entries, and install systemd-boot itself. + + kernel-install8 + may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate + description files compliant with the Boot Loader + Specification. + + systemd-stub7 + may be used as UEFI boot stub for executed kernels, which is useful to show graphical boot splashes + before transitioning into the Linux world. It is also capable of automatically picking up auxiliary + credential files (for boot parameterization) and system extension images, as companion files to the + booted kernel images. + + + + Key bindings + The following keys may be used in the boot menu: + + + + + + ↑ (Up) + ↓ (Down) + j + k + PageUp + PageDown + Home + End + Navigate up/down in the entry list + + + + + + ↵ (Enter) + → (Right) + Boot selected entry + + + + + + d + Make selected entry the default + + + + + + e + Edit the kernel command line for selected entry + + + + + + + + t + Increase the timeout before default entry is booted + + + + + + - + T + Decrease the timeout + + + + + + r + Change screen resolution, skipping any unsupported modes. + + + + + + R + Reset screen resolution to firmware or configuration file default. + + + + + + p + Print status + + + + + + h + ? + F1 + Show a help screen + + + + + + f + Reboot into firmware interface. + + For compatibility with the keybindings of several firmware implementations this operation + may also be reached with F2, F10, Del and + Esc. + + + + + + Shifto + Power off the system. + + + + + + Shiftb + Reboot the system. + + + + + + The following keys may be pressed during bootup or in the boot menu to directly boot a specific + entry: + + + + l + Linux + + + + + + w + Windows + + + + + + a + macOS + + + + + + s + EFI shell + + + + + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + Boot entry number 1 … 9 + + + + + + The boot menu is shown when a non-zero menu timeout has been configured. If the menu timeout has + been set to zero, it is sufficient to press any key — before the boot loader initializes — to bring up + the boot menu, except for the keys listed immediately above as they directly boot into the selected boot + menu item. Note that depending on the firmware implementation the time window where key presses are + accepted before the boot loader initializes might be short. If the window is missed, reboot and try + again, possibly pressing a suitable key (e.g. the space bar) continuously; on most systems it should be + possible to hit the time window after a few attempts. To avoid this problem, consider setting a non-zero + timeout, thus showing the boot menu unconditionally. Some desktop environments might offer an option to + directly boot into the boot menu, to avoid the problem altogether. Alternatively, use the command line + systemctl reboot --boot-loader-menu=0 from the shell. + + In the editor, most keys simply insert themselves, but the following keys + may be used to perform additional actions: + + + + ← (Left) + → (Right) + Home + End + Navigate left/right + + + + + + Esc + Ctrlc + Abort the edit and quit the editor + + + + + + Ctrlk + Clear the command line forwards + + + + + + Ctrlw + AltBackspace + Delete word backwards + + + + + + CtrlDel + Altd + Delete word forwards + + + + + + ↵ (Enter) + Boot entry with the edited command line + + + + + + Note that unless configured otherwise in the UEFI firmware, systemd-boot will + use the US keyboard layout, so key labels might not match for keys like +/-. + + + + + Files + + The files systemd-boot processes generally reside on the UEFI ESP which is + usually mounted to /efi/, /boot/ or + /boot/efi/ during OS runtime. It also processes files on the Extended Boot Loader + partition which is typically mounted to /boot/, if it + exists. + + 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 and the Extended Boot Loader partition. + + Unified kernel boot entries following the Boot Loader Specification are read from + /EFI/Linux/ on the ESP and the Extended Boot Loader partition. + + Optionally, a random seed for early boot entropy pool provisioning is stored in + /loader/random-seed in the ESP. + + During initialization, sd-boot automatically loads all driver files placed in + the /EFI/systemd/drivers/ directory of the ESP. The files placed there must have an + extension of the EFI architecture ID followed by .efi (e.g. for x86-64 this means a + suffix of x64.efi). This may be used to automatically load file system drivers and + similar, to extend the native firmware support. + + Enrollment of Secure Boot variables can be performed manually or automatically if files are available + under /loader/keys/NAME/{db,KEK,PK}.auth, NAME + being the display name for the set of variables in the menu. If one of the sets is named auto + then it might be enrolled automatically depending on whether secure-boot-enroll is set + to force or not. + + + + EFI Variables + + The following EFI variables are defined, set and read by systemd-boot, under the + vendor UUID 4a67b082-0a4c-41cf-b6c7-440b29bb8c4f, for communication between the boot + loader and the OS: + + + + LoaderBootCountPath + If boot counting is enabled, contains the path to the file in whose name the boot counters are + encoded. Set by the boot + loader. systemd-bless-boot.service8 + uses this information to mark a boot as successful as determined by the successful activation of the + boot-complete.target target unit. + + + + + + LoaderConfigTimeout + LoaderConfigTimeoutOneShot + The menu timeout in seconds. Read by the boot loader. LoaderConfigTimeout + is maintained persistently, while LoaderConfigTimeoutOneShot is a one-time override which is + read once (in which case it takes precedence over LoaderConfigTimeout) and then + removed. LoaderConfigTimeout may be manipulated with the + t/T keys, see above. + + + + + + LoaderConfigConsoleMode + The numerical menu console mode. Read by the boot loader. LoaderConfigConsoleMode + is maintained persistently. LoaderConfigConsoleMode may be manipulated with the + r/R keys, see above. + + + + + + LoaderDevicePartUUID + + Contains the partition UUID of the EFI System Partition the boot loader was run from. Set by + the boot + loader. systemd-gpt-auto-generator8 + uses this information to automatically find the disk booted from, in order to discover various other partitions + on the same disk automatically. + + + + + + LoaderEntries + + A list of the identifiers of all discovered boot loader entries. Set by the boot + loader. + + + + + + LoaderEntryDefault + LoaderEntryOneShot + + The identifier of the default boot loader entry. Set primarily by the OS and read by the boot + loader. LoaderEntryOneShot sets the default entry for the next boot only, while + LoaderEntryDefault sets it persistently for all future + boots. bootctl1's + and commands make use of these variables. The boot + loader modifies LoaderEntryDefault on request, when the d key is used, see + above. + + + + + + LoaderEntryLastBooted + + The identifier of the boot loader entry last attempted. Set and read by the boot loader, + only when /loader/loader.conf has default set to @saved. See + loader.conf5. + + The boot loader will ensure LoaderEntryLastBooted is up-to date for every boot, + updating it as needed and will omit changing it all together when LoaderEntryOneShot + is set. + + The boot loader reads the variable, which takes higher priority than + LoaderEntryDefault. The variable is ignored when LoaderEntryOneShot + is set. + + LoaderEntryLastBooted cannot be used as indication that the last boot was + successful or not. + + + + + + LoaderEntrySelected + + The identifier of the boot loader entry currently being booted. Set by the boot + loader. + + + + + + LoaderFeatures + + A set of flags indicating the features the boot loader supports. Set by the boot loader. Use + bootctl1 to view this + data. + + + + + + LoaderFirmwareInfo + LoaderFirmwareType + + Brief firmware information. Set by the boot loader. Use + bootctl1 to view this + data. + + + + + + LoaderImageIdentifier + + 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 + bootctl1 to view this + data. + + + + + + LoaderInfo + + Brief information about the boot loader. Set by the boot loader. Use + bootctl1 to view this + data. + + + + + + LoaderTimeExecUSec + LoaderTimeInitUSec + LoaderTimeMenuUsec + + Information about the time spent in various parts of the boot loader. Set by the boot + loader. Use systemd-analyze1 + to view this data. + + + + + + LoaderSystemToken + + A binary random data field, that is used for generating the random seed to pass to + the OS (see above). Note that this random data is generally only generated once, during OS + installation, and is then never updated again. + + + + + + Many of these variables are defined by the Boot Loader Interface. + + + + Boot Counting + + systemd-boot implements a simple boot counting mechanism on top of the Boot Loader Specification, for automatic and unattended + fallback to older kernel versions/boot loader entries when a specific entry continuously fails. Any boot loader + entry file and unified kernel image file that contains a + followed by one or two numbers (if + two they need to be separated by a -), before the .conf or + .efi suffix is subject to boot counting: the first of the two numbers ('tries left') is + decreased by one on every boot attempt, the second of the two numbers ('tries done') is increased by one (if 'tries + done' is absent it is considered equivalent to 0). Depending on the current value of these two counters the boot + entry is considered to be in one of three states: + + + If the 'tries left' counter of an entry is greater than zero the entry is considered to be in + 'indeterminate' state. This means the entry has not completed booting successfully yet, but also hasn't been + determined not to work. + + If the 'tries left' counter of an entry is zero it is considered to be in 'bad' state. This means + no further attempts to boot this item will be made (that is, unless all other boot entries are also in 'bad' + state), as all attempts to boot this entry have not completed successfully. + + If the 'tries left' and 'tries done' counters of an entry are absent it is considered to be in + 'good' state. This means further boot counting for the entry is turned off, as it successfully booted at least + once. The + systemd-bless-boot.service8 + service moves the currently booted entry from 'indeterminate' into 'good' state when a boot attempt completed + successfully. + + + Generally, when new entries are added to the boot loader, they first start out in 'indeterminate' state, + i.e. with a 'tries left' counter greater than zero. The boot entry remains in this state until either it managed to + complete a full boot successfully at least once (in which case it will be in 'good' state) — or the 'tries left' + counter reaches zero (in which case it will be in 'bad' state). + + Example: let's say a boot loader entry file foo.conf is set up for 3 boot tries. The + installer will hence create it under the name foo+3.conf. On first boot, the boot loader will + rename it to foo+2-1.conf. If that boot does not complete successfully, the boot loader will + rename it to foo+1-2.conf on the following boot. If that fails too, it will finally be renamed + foo+0-3.conf by the boot loader on next boot, after which it will be considered 'bad'. If the + boot succeeds however the entry file will be renamed to foo.conf by the OS, so that it is + considered 'good' from then on. + + The boot menu takes the 'tries left' counter into account when sorting the menu entries: entries in 'bad' + state are ordered at the beginning of the list, and entries in 'good' or 'indeterminate' at the end. The user can + freely choose to boot any entry of the menu, including those already marked 'bad'. If the menu entry to boot is + automatically determined, this means that 'good' or 'indeterminate' entries are generally preferred (as the bottom + item of the menu is the one booted by default), and 'bad' entries will only be considered if there are no 'good' or + 'indeterminate' entries left. + + The kernel-install8 kernel + install framework optionally sets the initial 'tries left' counter to the value specified in + /etc/kernel/tries when a boot loader entry is first created. + + + + Using <command>systemd-boot</command> in virtual machines + + When using qemu with OVMF (UEFI Firmware for virtual machines) the switch + works not only for linux kernels, but for any EFI binary, including sd-boot and unified linux + kernels. Example command line for loading systemd-boot on x64: + + + qemu-system-x86_64 [ ... ] + -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi + + + systemd-boot will detect that it was started directly instead of being loaded from ESP and will + search for the ESP in that case, taking into account boot order information from the hypervisor (if + available). + + + + See Also + + bootctl1, + loader.conf5, + systemd-bless-boot.service8, + systemd-boot-random-seed.service8, + kernel-install8, + systemd-stub7, + Boot Loader Specification, + Boot Loader Interface, + TPM2 PCR Measurements Made by systemd + + + -- cgit v1.2.3