Systemd-boot: Difference between revisions

From ArchWiki
VisualWikitext
(→‎Loader configuration: Added the case where 'editor no' is useful)
m (→‎UEFI Shells or other EFI applications: Fix some spelling errors)
 
(334 intermediate revisions by 98 users not shown)
Line 1: Line 1:
{{lowercase title}}
{{Lowercase title}}
[[Category:Boot loaders]]
[[Category:Boot loaders]]
[[de:Systemd-boot]]
[[de:Systemd-boot]]
[[es:Systemd-boot]]
[[es:Systemd-boot]]
[[ja:Systemd-boot]]
[[ja:Systemd-boot]]
[[pt:Systemd-boot]]
[[ru:Systemd-boot]]
[[ru:Systemd-boot]]
[[zh-hans:Systemd-boot]]
[[zh-hans:Systemd-boot]]
Line 12: Line 13:
{{Related articles end}}
{{Related articles end}}


'''systemd-boot''', previously called '''gummiboot''' (German for: 'rubber dinghy'), is a simple UEFI [[boot manager]] which executes configured EFI images. The default entry is selected by a configured pattern (glob) or an on-screen menu to be navigated via arrow-keys. It is included with {{pkg|systemd}}, which is installed on an Arch system by default.
{{man|7|systemd-boot}}, previously called '''gummiboot''' (German for "rubber dinghy"), is an easy-to-configure [[UEFI]] [[boot manager]]. It provides a textual menu to select the boot entry and an editor for the kernel command line.


It is simple to configure but it can only start EFI executables such as the Linux kernel [[EFISTUB]], UEFI Shell, GRUB, or the Windows Boot Manager.
Note that ''systemd-boot'' can only start EFI executables (e.g., the Linux kernel [[EFISTUB]], [[UEFI shell]], [[GRUB]], or the [https://learn.microsoft.com/en-us/windows-hardware/drivers/bringup/boot-and-uefi#understanding-the-windows-boot-manager Windows Boot Manager]).
 
== Supported file systems ==
 
systemd-boot inherits the support for the file systems [[Arch boot process#UEFI|from the firmware]] (i.e. at least FAT12, FAT16 and FAT32). Additionally it loads any [[Unified Extensible Firmware Interface#UEFI drivers|UEFI drivers]] placed in {{ic|''esp''/EFI/systemd/drivers/}}.


== Installation ==
== Installation ==


=== Installing the EFI boot manager ===
''systemd-boot'' is shipped with the {{Pkg|systemd}} package which is a dependency of the {{Pkg|base}} meta package, so no additional packages need to be installed manually.
 
== Installing the UEFI boot manager ==
 
To install ''systemd-boot'', first make sure that the system is booted into UEFI mode and [[Unified Extensible Firmware Interface#UEFI variables|UEFI variables]] are accessible. This can be verified by running {{ic|efivar --list}} or, if {{Pkg|efivar}} is not installed, by running {{ic|ls /sys/firmware/efi/efivars}} (if the directory exists, the system is booted into UEFI mode.)
 
Throughout, {{ic|''esp''}} will denote the [[EFI system partition#Typical mount points|ESP mountpoint]], e.g. {{ic|/efi}} or {{ic|/boot}}. This assumes that you have [[chroot]]ed to the system's mount point.
 
Use {{man|1|bootctl}} to install ''systemd-boot'' to the ESP:
 
# bootctl install
 
This will copy the ''systemd-boot'' UEFI boot manager to the ESP, create a UEFI boot entry for it and set it as the first in the UEFI boot order.


To install the ''systemd-boot'' EFI boot manager, first make sure the system has booted in UEFI mode and that [[Unified Extensible Firmware Interface#UEFI variables|UEFI variables]] are accessible. This can be checked by running the command {{ic|efivar --list}}.
* On an x64 UEFI, {{ic|/usr/lib/systemd/boot/efi/systemd-bootx64.efi}} will be copied to {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} and {{ic|''esp''/EFI/BOOT/BOOTX64.EFI}}.
* On an IA32 UEFI, {{ic|/usr/lib/systemd/boot/efi/systemd-bootia32.efi}} will be copied to {{ic|''esp''/EFI/systemd/systemd-bootia32.efi}} and {{ic|''esp''/EFI/BOOT/BOOTIA32.EFI}}.


It should be noted that ''systemd-boot'' is only able to load the [[EFISTUB]] kernel from the [[EFI system partition]] (ESP). To keep the kernel updated, it is simpler and therefore '''recommended''' to mount the ESP to {{ic|/boot}}. If the ESP is '''not''' mounted to {{ic|/boot}}, the kernel and initramfs files must be copied onto that ESP. See [[EFI system partition#Alternative mount points]] for details.
The UEFI boot entry will be called "Linux Boot Manager" and will point to, depending on the UEFI bitness, either {{ic|\EFI\systemd\systemd-bootx64.efi}} or {{ic|\EFI\systemd\systemd-bootia32.efi}} on the ESP.


{{ic|''esp''}} will be used throughout this page to denote the ESP mountpoint, e.g. {{ic|/boot}}.
{{Note|
* When running {{ic|bootctl install}}, ''systemd-boot'' will try to locate the ESP at {{ic|/efi}}, {{ic|/boot}}, and {{ic|/boot/efi}}. Setting {{ic|''esp''}} to a different location requires passing the {{ic|1=--esp-path=''esp''}} option. (See {{man|1|bootctl|OPTIONS}} for details.)
* Installing ''systemd-boot'' will overwrite any existing {{ic|''esp''/EFI/BOOT/BOOTX64.EFI}} (or {{ic|''esp''/EFI/BOOT/BOOTIA32.EFI}} on IA32 UEFI), e.g. Microsoft's version of the file.
}}


With the ESP mounted to {{ic|''esp''}}, use {{man|1|bootctl}} to install ''systemd-boot'' into the EFI system partition by running:
To conclude the installation, [[#Configuration|configure]] ''systemd-boot''.
# bootctl --path=''esp'' install
This will copy the ''systemd-boot'' boot loader to the EFI partition: on a x64 architecture system the two identical binaries {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} and {{ic|''esp''/EFI/BOOT/BOOTX64.EFI}} will be transferred to the ESP. It will then set ''systemd-boot'' as the default EFI application (default boot entry) loaded by the EFI Boot Manager.


Then, go to the [[#Configuration]] section to add boot loaders to make ''systemd-boot'' to function properly at boot time.
=== Installation using XBOOTLDR ===


=== Updating the EFI boot manager ===
A separate [[Partitioning#/boot|/boot partition]] of type "Linux extended boot" (XBOOTLDR) can be created to keep the kernel and initramfs separate from the ESP. This is particularly helpful to [[dual boot with Windows]] with an existing ESP that is too small.


Whenever there is a new version of ''systemd-boot'', the boot manager must be updated by the user. This can be performed manually or the update can be automatically triggered using pacman hooks. The two approaches are described thereafter.
Prepare an ESP as usual and create another partition for XBOOTLDR on the same physical drive. The XBOOTLDR partition must have a partition type GUID of {{ic|bc13c2ff-59e6-4262-a352-b275fd6f7172}} [https://uapi-group.org/specifications/specs/boot_loader_specification/] ({{ic|ea00}} type for [[gdisk]]). The size of the XBOOTLDR partition should be large enough to accommodate all of the kernels you are going to install.
 
{{Note|
* ''systemd-boot'' does not do a file system check like it does for the ESP. Hence, it is possible to use any file system that your UEFI implementation can read.
* UEFI may skip loading partitions other than the ESP when a "fast boot" mode is enabled. This can lead to ''systemd-boot'' failing to find entries on the XBOOTLDR partition; in that case, disable the "fast boot" mode.
* The XBOOTLDR partition must be on the same physical disk as the ESP for ''systemd-boot'' to recognize it.
}}
 
During install, mount the ESP to {{ic|/mnt/efi}} and the XBOOTLDR partition to {{ic|/mnt/boot}}.
 
Once in chroot, use the command:
 
# bootctl --esp-path=/efi --boot-path=/boot install
 
To conclude the installation, [[#Configuration|configure]] ''systemd-boot''.
 
=== Updating the UEFI boot manager ===
 
Whenever there is a new version of ''systemd-boot'', the UEFI boot manager can be optionally reinstalled by the user. This can be done manually or automatically; the two approaches are described thereafter.
 
{{Note|The UEFI boot manager is a standalone EFI executable and any version can be used to boot the system (partial updates do not apply, since pacman only installs the ''systemd-boot'' installer, not ''systemd-boot'' itself.) However, new versions may add new features or fix bugs, so it is probably a good idea to update ''systemd-boot''.}}


==== Manual update ====
==== Manual update ====


''bootctl'' must be used to update ''systemd-boot''. If the {{ic|path}} parameter is not specified, {{ic|/efi}}, {{ic|/boot}}, and {{ic|/boot/efi}} are checked in turn.
Use ''bootctl'' to update ''systemd-boot'':


  # bootctl update
  # bootctl update


If the ESP is mounted on a different location, the {{ic|path}} option can be passed as follows:
{{Note|As with {{ic|bootctl install}}, ''systemd-boot'' will try to locate the ESP at {{ic|/efi}}, {{ic|/boot}}, and {{ic|/boot/efi}}. Setting {{ic|''esp''}} to a different location requires passing the {{ic|1=--esp-path=''esp''}} option.}}


# bootctl --path=''esp'' update
==== Automatic update ====


{{Note|This is also the command to use when migrating from ''gummiboot'', before removing that package. If that package has already been removed, however, run {{ic|1=bootctl --path=''esp'' install}}.}}
To update ''systemd-boot'' automatically, either use a [[Systemd#Using units|systemd service]] or a [[pacman hook]]. The two methods are described below.


==== Automatic update ====
===== systemd service =====
 
As of version 250, {{Pkg|systemd}} ships with {{ic|systemd-boot-update.service}}. [[Enabling]] this service will update the bootloader upon the next boot.
 
{{Warning|If you have [[Secure Boot]] enabled, you need to sign your bootloader after updating. See [[#Signing for Secure Boot]] below for an example of how to do so.}}
 
{{Tip|If {{ic|/usr/lib/systemd/boot/efi/systemd-boot''arch''.efi.signed}} exists, it will be used in place of {{ic|/usr/lib/systemd/boot/efi/systemd-boot''arch''.efi}} when installing or updating the boot manager. See {{man|1|bootctl|SIGNED .EFI FILES}} for details.}}
 
===== pacman hook =====
 
The package {{AUR|systemd-boot-pacman-hook}} adds a pacman hook which is executed every time {{Pkg|systemd}} is upgraded.


The package {{AUR|systemd-boot-pacman-hook}} provides a [[Pacman hook]] to automate the update process. [[Install|Installing]] the package will add a hook which will be executed every time the {{Pkg|systemd}} package is upgraded.
Rather than installing ''systemd-boot-pacman-hook'', you may prefer to manually place the following file in {{ic|/etc/pacman.d/hooks/}}:
Alternatively, to replicate what the ''systemd-boot-pacman-hook'' package does without installing it, place the following pacman hook in the {{ic|/etc/pacman.d/hooks/}} directory:


{{hc|/etc/pacman.d/hooks/100-systemd-boot.hook|2=
{{hc|/etc/pacman.d/hooks/95-systemd-boot.hook|2=
[Trigger]
[Trigger]
Type = Package
Type = Package
Line 60: Line 108:


[Action]
[Action]
Description = Updating systemd-boot
Description = Gracefully upgrading systemd-boot...
When = PostTransaction
When = PostTransaction
Exec = /usr/bin/bootctl update
Exec = /usr/bin/systemctl restart systemd-boot-update.service
}}
}}
===== Signing for Secure Boot =====
If you have [[Secure Boot]] enabled, you may want to add a pacman hook to automatically sign the boot manager upon every upgrade of the package:
{{hc|/etc/pacman.d/hooks/80-secureboot.hook|2=
[Trigger]
Operation = Install
Operation = Upgrade
Type = Path
Target = usr/lib/systemd/boot/efi/systemd-boot*.efi
[Action]
Description = Signing systemd-boot EFI binary for Secure Boot
When = PostTransaction
Exec = /bin/sh -c 'while read -r i; do sbsign --key ''/path/to/keyfile.key'' --cert ''/path/to/certificate.crt'' "$i"; done;'
Depends = sh
Depends = sbsigntools
NeedsTargets
}}
Replace {{ic|''/path/to/keyfile.key''}} and {{ic|''/path/to/certificate.crt''}} with your signing key and certificate respectively. For better understanding of this hook, consult {{man|1|sbsign}}.
{{Tip|If you are using {{Pkg|sbctl}} then resigning of the files enrolled in its database is automatically done through the hook provided at {{ic|/usr/share/libalpm/hooks/zz-sbctl.hook}}. Remember to enroll the files necessary to your bootchain first.}}


== Configuration ==
== Configuration ==
Line 69: Line 141:
=== Loader configuration ===
=== Loader configuration ===


The loader configuration is stored in the file {{ic|''esp''/loader/loader.conf}} and it is composed of the following options:
The loader configuration is stored in the file {{ic|''esp''/loader/loader.conf}}. See {{man|5|loader.conf|OPTIONS}} for details.


* {{ic|default}} – default entry to select as defined in [[#Adding loaders]]; it is given without the ''.conf'' suffix and it can be a wildcard like {{ic|arch-*}}.
A loader configuration example is provided below:
* {{ic|timeout}} – menu timeout in seconds before the default entry is booted. If this is not set, the menu will only be shown on {{ic|Space}} key (or most other keys actually work too) press during boot.
* {{ic|editor}} – whether to enable the kernel parameters editor or not. {{ic|yes}} (default) is enabled, {{ic|no}} is disabled; since the user can add {{ic|1=init=/bin/bash}} to bypass root password and gain root access, it is strongly recommended to set this option to {{ic|no}} if the machine can be accessed by unauthorized persons.
* {{ic|auto-entries}} – shows automatic entries for Windows, EFI Shell, and Default Loader if set to {{ic|1}} (default), {{ic|0}} to hide;
* {{ic|auto-firmware}} – shows entry for rebooting into UEFI firmware settings if set to {{ic|1}} (default), {{ic|0}} to hide;
* {{ic|console-mode}} – changes UEFI console mode: {{ic|0}} for 80x25, {{ic|1}} for 80x50, {{ic|2}} and above for non-standard modes provided by the device firmware, if any, {{ic|auto}} picks a suitable mode automatically, {{ic|max}} for highest available mode, {{ic|keep}} (default) for the firmware selected mode.


See [https://www.freedesktop.org/software/systemd/man/loader.conf.html loader.conf manual] for the full list of options.
A loader configuration example is provided thereafter:
{{hc|''esp''/loader/loader.conf|
{{hc|''esp''/loader/loader.conf|
default  arch
default  arch.conf
timeout  4
timeout  4
console-mode max
console-mode max
Line 89: Line 153:


{{Tip|
{{Tip|
* {{ic|default}} and {{ic|timeout}} can be changed in the boot menu itself and changes will be stored as EFI variables, overriding these options.
* systemd-boot does not accept tabs for indentation, use spaces instead.
* A basic loader configuration file is located at {{ic|/usr/share/systemd/bootctl/loader.conf}}.}}
* {{ic|default}} and {{ic|timeout}} can be changed in the boot menu itself and changes will be stored as UEFI variables {{ic|LoaderEntryDefault}} and {{ic|LoaderConfigTimeout}}, overriding these options.
* {{ic|bootctl set-default ""}} and {{ic|bootctl set-timeout ""}} can be used to clear the UEFI variables overriding the {{ic|default}} and {{ic|timeout}} options, respectively.
* If you have set {{ic|timeout 0}}, the boot menu can be accessed by pressing {{ic|Space}}.
* A basic loader configuration file is located at {{ic|/usr/share/systemd/bootctl/loader.conf}}.
* If the bootloader (during the entry selection) appears distorted/uses the wrong resolution you can try to set the {{ic|console-mode}} to {{ic|auto}} (uses heuristics to select the best resolution), {{ic|keep}} (keeps the firmware provided resolution) or {{ic|2}} (tries to select the first non-UEFI-standard resolution).
}}
 
==== Remember last entry ====
 
As of systemd version 251 or later default can be changed to {{ic|@saved}} in order to remember the last picked entry on startup. This is useful for when dual booting Windows and the surprise windows auto update pushes you into Linux.
 
{{hc|''esp''/loader/loader.conf|
default @saved
...
}}
 
Consult {{man|5|loader.conf}} for more details.


=== Adding loaders ===
=== Adding loaders ===


''bootctl'' searches for boot menu items in {{ic|''esp''/loader/entries/*.conf}} – each file found must contain exactly one loader. The possible options are:
''systemd-boot'' will search for boot menu items in {{ic|''esp''/loader/entries/*.conf}} and additionally in {{ic|''boot''/loader/entries/*.conf}} if using [[#Installation using XBOOTLDR|XBOOTLDR]]. Note that entries in {{ic|''esp''}} can only use files (e.g. kernels, initramfs, images, etc.) in {{ic|''esp''}}. Similarly, entries in {{ic|''boot''}} can only use files in {{ic|''boot''}}.


* {{ic|title}} – operating system name. '''Required.'''
{{Note|When [[Secure Boot]] is active, [[unified kernel image]]s with an embedded {{ic|.cmdline}} ignore all command line options passed to them (either using a boot entry with {{ic|options}} or interactively). When Secure Boot is not active, the options passed via the command line override the embedded {{ic|.cmdline}}.}}
* {{ic|version}} – kernel version, shown only when multiple entries with same title exist. Optional.
* {{ic|machine-id}} – machine identifier from {{ic|/etc/machine-id}}, shown only when multiple entries with same title and version exist. Optional.
* {{ic|efi}} – EFI program to start, relative to your ESP ({{ic|''esp''}}); e.g. {{ic|/vmlinuz-linux}}. '''Either''' this parameter or {{ic|linux}} (see below) is '''required'''.
* {{ic|options}} – command line options to pass to the EFI program or [[kernel parameters]]. Optional, but you will need at least {{ic|1=initrd=''efipath''}} and {{ic|1=root=''dev''}} if booting Linux.


For Linux boot, you can also use {{ic|linux}} instead of {{ic|efi}}. Or {{ic|initrd}} in addition to {{ic|options}}. The syntax is:
An example of loader files launching Arch from a volume using its [[UUID]] {{ic|''xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx''}} is:
* {{ic|linux}} and {{ic|initrd}} followed by the relative path of the corresponding files in the ESP;  e.g. {{ic|/vmlinuz-linux}}; this will be automatically translated into {{ic|efi ''path''}} and {{ic|1=options initrd=''path''}} – this syntax is only supported for convenience and has no differences in function.


An example of a loader file to launch Arch from a partition with the label ''arch_os'' and loading the Intel CPU [[microcode]]  is:
{{hc|''esp''/loader/entries/arch.conf|2=
{{hc|''esp''/loader/entries/arch.conf|2=
title  Arch Linux
title  Arch Linux
linux  /vmlinuz-linux
linux  /vmlinuz-linux
initrd  /intel-ucode.img
initrd  /initramfs-linux.img
initrd  /initramfs-linux.img
options root=LABEL=''arch_os'' rw}}
options root=UUID=''xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'' rw
}}


''bootctl'' will automatically check at boot time for '''Windows Boot Manager''' at the location {{ic|/EFI/Microsoft/Boot/Bootmgfw.efi}}, '''EFI Shell''' {{ic|/shellx64.efi}} and '''EFI Default Loader''' {{ic|/EFI/BOOT/bootx64.efi}}, as well as specially prepared kernel files found in {{ic|/EFI/Linux}}. When detected, corresponding entries with titles {{ic|auto-windows}}, {{ic|auto-efi-shell}} and {{ic|auto-efi-default}}, respectively, will be generated. These entries do not require manual loader configuration. However, it does not auto-detect other EFI applications (unlike [[rEFInd]]), so for booting the Linux kernel, manual configuration entries must be created.
{{hc|''esp''/loader/entries/arch-fallback.conf|2=
title  Arch Linux (fallback initramfs)
linux  /vmlinuz-linux
initrd  /initramfs-linux-fallback.img
options root=UUID=''xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'' rw
}}
 
See the [https://uapi-group.org/specifications/specs/boot_loader_specification/#type-1-boot-loader-specification-entries Boot Loader Specification] for details on all configuration options.


{{Note|
''systemd-boot'' will automatically check at boot time for '''Windows Boot Manager''' at the location {{ic|/EFI/Microsoft/Boot/Bootmgfw.efi}}, [[UEFI shell]] {{ic|/shellx64.efi}} and '''EFI Default Loader''' {{ic|/EFI/BOOT/bootx64.efi}}, as well as specially prepared kernel files found in {{ic|/EFI/Linux/}}. When detected, corresponding entries with titles {{ic|auto-windows}}, {{ic|auto-efi-shell}} and {{ic|auto-efi-default}}, respectively, will be generated. These entries do not require manual loader configuration. However, it does not auto-detect other EFI applications (unlike [[rEFInd]]), so for booting the Linux kernel, manual configuration entries must be created.
* If you dual-boot Windows, it is strongly recommended to disable its default [[Dual boot with Windows#Fast_Start-Up|Fast Start-Up]] option.
* Remember to load the Intel ''microcode'' with {{ic|initrd}} if applicable, an example is provided in [[Microcode#systemd-boot]].
* The root partition can be identified with its {{ic|LABEL}} or its {{ic|PARTUUID}}. The latter can be found with the command {{ic|1=blkid -s PARTUUID -o value /dev/sd''xY''}}, where {{ic|''x''}} is the device letter and {{ic|''Y''}} is the partition number. This is required only to identify the root partition, not the {{ic|''esp''}}.
}}


{{Tip|
{{Tip|
* The available boot entries which have been configured can be listed with the command {{ic|bootctl list}}.
* The available boot entries which have been configured can be listed with the command {{ic|bootctl list}}.
* An example entry file is located at {{ic|/usr/share/systemd/bootctl/arch.conf}}.
* An example entry file is located at {{ic|/usr/share/systemd/bootctl/arch.conf}}.
* The [[kernel parameters]] for scenarios such as [[LVM]], [[LUKS]] or [[dm-crypt]] can be found on the relevant pages.
* The [[kernel parameters]] for scenarios such as [[LVM]], [[LUKS]], [[dm-crypt]] or [[Btrfs]] can be found on the relevant pages.
}}
 
{{Note|If [[Microcode#Microcode in a separate initramfs file|external microcode initramfs images]] are used (e.g. when using [[Booster]] as the initramfs generator), {{ic|/boot/amd-ucode.img}} or {{ic|/boot/intel-ucode.img}} must be specified in a separate {{ic|initrd}} and always be placed '''first''', before the main initramfs image.}}
 
==== UEFI Shells or other EFI applications ====
 
In case you installed a [[UEFI shell]] with the package {{Pkg|edk2-shell}}, ''systemd-boot'' will auto-detect and create a new entry if the EFI file is placed in {{ic|''esp''/shellx64.efi}}.
To perform this and example command after installing the package would be:
 
# cp /usr/share/edk2-shell/x64/Shell.efi /boot/shellx64.efi
 
Otherwise in case you installed [[rEFInd#Tools|other EFI applications]] into the ESP, you can use the following snippets.
 
{{Note|The file path parameter for the {{ic|efi}} line is relative to the root of your [[EFI system partition]]. If your EFI system partition is mounted at {{ic|/boot}} and your EFI binaries reside at {{ic|/boot/EFI/xx.efi}} and {{ic|/boot/yy.efi}}, then you would specify the parameters as {{ic|efi /EFI/xx.efi}} and {{ic|efi /yy.efi}} respectively.}}
 
{{hc|''esp''/loader/entries/fwupd.conf|
title  Firmware updater
efi    /EFI/tools/fwupdx64.efi
}}
}}
==== EFI Shells or other EFI apps ====


In case you installed [[Unified Extensible Firmware Interface#UEFI Shell|EFI shells]] and [[rEFInd#Tools|other EFI application]] into the ESP, you can use the following snippets.
{{hc|''esp''/loader/entries/gdisk.conf|
title  GPT fdisk (gdisk)
efi    /EFI/tools/gdisk_x64.efi
}}


{{Note|The file path parameter for the {{ic|efi}} line is relative to your ''esp'' mount point. If you are mounted on {{ic|/boot}} and your EFI binaries reside at {{ic|/boot/EFI/xx.efi}} and {{ic|/boot/yy.efi}}, then you would specify the parameters as {{ic|efi /EFI/xx.efi}} and {{ic|efi /yy.efi}} respectively.}}
===== Memtest86+ =====


Examples of loading custom UEFI Shell loaders:
You need to install {{Pkg|memtest86+-efi}} for this to work. Also sign the EFI binary when using Secure Boot.


{{hc|''esp''/loader/entries/uefi-shell-v1-x86_64.conf|
{{hc|''esp''/loader/entries/memtest.conf|
title   UEFI Shell x86_64 v1
title Memtest86+
efi     /EFI/shellx64_v1.efi
efi /memtest86+/memtest.efi
}}
}}


{{hc|''esp''/loader/entries/uefi-shell-v2-x86_64.conf|
===== Netboot =====
title   UEFI Shell x86_64 v2
 
efi     /EFI/shellx64_v2.efi
''systemd-boot'' can chainload [[Netboot]]. Download the {{ic|ipxe-arch.efi}} EFI binary and signature, verify it and place it as proposed in {{ic|''esp''/EFI/arch_netboot/arch_netboot.efi}}.
 
{{hc|''esp''/loader/entries/arch_netboot.conf|
title Arch Linux Netboot
efi /EFI/arch_netboot/arch_netboot.efi
}}
}}


=== Booting into EFI Firmware Setup ===
===== GRUB =====


Most system firmware configured for EFI booting will add its own [[efibootmgr]] entries to boot into UEFI Firmware Setup.
''systemd-boot'' can chainload [[GRUB]]. The location of the {{ic|grubx64.efi}} binary matches the used {{ic|--bootloader-id{{=}}}} when GRUB was installed to the ESP.


=== Preparing kernels for /EFI/Linux ===
{{hc|''esp''/loader/entries/grub.conf|
title GRUB
efi /EFI/GRUB/grubx64.efi
}}


{{Style|Does not belong here, not specific to systemd-boot.}}
==== Boot from another disk ====


''/EFI/Linux'' is searched for specially prepared kernel files, which bundle the kernel, the init RAM disk (initrd), the kernel command line and {{ic|/etc/os-release}} into one single file. This file can be easily signed for secure boot.
''systemd-boot'' cannot launch binaries from partitions other than the ESP or the XBOOTLDR partition, but it can run an external script to do so.


{{Note|{{ic|systemd-boot}} requires that the {{ic|os-release}} file contain either {{ic|VERSION_ID}} or {{ic|BUILD_ID}} to generate an ID and automatically add the entry, which the Arch {{ic|os-release}} does not. Either maintain your own copy with one of them, or make your bundling script generate it automatically.}}
First we need to install {{Pkg|edk2-shell}} (will be the interpreter to be used). We also need the PARTUUID of the partition where the destination EFI file is located which can be obtained by using the {{ic|blkid}} command. Using the UEFI shell (as explained above) we can use the ''map'' command to take notes of the '''FS alias''' (ex: HD0a66666a2) and the full '''path''' of the destination EFI file (ex: EFI\Microsoft\Boot\Bootmgfw.efi). The FS alias corresponds to the PARTUUID of the partition where the destination EFI file is located.


Put the kernel command line you want to use in a file, and create the bundle file like this:
Then using the ''exit'' command we can boot back into Linux where we can create the new entry.
To do so we need to first create in the root of the ''esp'' mount point a ''.nsh'' filename with the FS alias, a colon and the EFI path, here an example:


{{hc|Kernel packaging command:|2=objcopy \
{{hc|''esp''/windows.nsh|
    --add-section .osrel="/usr/lib/os-release" --change-section-vma .osrel=0x20000 \
HD0a66666a2:EFI\Microsoft\Boot\Bootmgfw.efi
    --add-section .cmdline="kernel-command-line.txt" --change-section-vma .cmdline=0x30000 \
}}
    --add-section .linux="vmlinuz-file" --change-section-vma .linux=0x40000 \
    --add-section .initrd="initrd-file" --change-section-vma .initrd=0x3000000 \
    "/usr/lib/systemd/boot/efi/linuxx64.efi.stub" "''linux''.efi"}}


Optionally sign the {{ic|''linux''.efi}} file produced above.
Once we created this file we can proceed to create the loader entry to run the script:


Copy {{ic|''linux''.efi}} into {{ic|''esp''/EFI/Linux}}.
{{hc|''esp''/loader/entries/windows.conf|
title  Windows
efi    /shellx64.efi
options -nointerrupt -noconsolein -noconsoleout windows.nsh
}}
 
{{Tip| To use Windows with Bitlocker and a PIN, remove {{ic|-noconsolein}}.}}
 
Its important that the ''efi'' path matches where the edk2-shell has been copied in the ''esp'' partition, and the last argument of options matches the ''.nsh'' filename in the root of the ''esp'' partition. Also note that the edk2-shell EFI file can be moved to avoid the entry auto-creation of ''systemd-boot''.
 
=== Booting into UEFI firmware setup ===
 
systemd-boot will automatically add an entry to boot into UEFI firmware setup if your device's firmware supports rebooting into setup from the OS.


=== Support hibernation ===
=== Support hibernation ===
Line 179: Line 293:
Install ''systemd-boot-password'' with the following command:
Install ''systemd-boot-password'' with the following command:


{{bc|1=# sbpctl install ''esp''}}
# sbpctl install ''esp''


With enabled editor you will be prompted for your password before you can edit kernel parameters.
With enabled editor you will be prompted for your password before you can edit kernel parameters.


== Keys inside the boot menu ==
== Tips and tricks ==


The following keys are used inside the menu:
=== Keys inside the boot menu ===
* {{ic|Up/Down}} - select entry
* {{ic|Enter}} - boot the selected entry
* {{ic|d}} - select the default entry to boot (stored in a non-volatile EFI variable)
* {{ic|-/T}} - decrease the timeout (stored in a non-volatile EFI variable)
* {{ic|+/t}} - increase the timeout (stored in a non-volatile EFI variable)
* {{ic|e}} - edit the kernel command line. It has no effect if the {{ic|editor}} config option is set to {{ic|0}}.
* {{ic|v}} - show the systemd-boot and UEFI version
* {{ic|Q}} - quit
* {{ic|P}} - print the current configuration
* {{ic|h/?}} - help


These hotkeys will, when pressed inside the menu or during bootup, directly boot
You can use {{ic|t}} and {{ic|T}} while in the menu to adjust the menu timeout and {{ic|e}} to edit the kernel parameters for this boot. Press {{ic|h}} to see a short list of useful hotkeys. See {{man|7|systemd-boot|KEY BINDINGS}} for the full list of available key bindings inside the boot menu.
a specific entry:


* {{ic|l}} - Linux
=== Choosing next boot ===
* {{ic|w}} - Windows
 
* {{ic|a}} - OS X
The boot manager is integrated with the systemctl command, allowing you to choose what option you want to boot after a reboot. For example, suppose you have built a custom kernel and created an entry file {{ic|''esp''/loader/entries/arch-custom.conf}} to boot into it, you can just launch
* {{ic|s}} - EFI Shell
 
* {{ic|1-9}} - number of entry
$ systemctl reboot --boot-loader-entry=arch-custom.conf
 
and your system will reboot into that entry maintaining the default option intact for subsequent boots. To see a list of possible entries pass the {{ic|1=--boot-loader-entry=help}} option.
 
If you want to boot into the firmware of your motherboard directly, then you can use this command:
 
$ systemctl reboot --firmware-setup
 
=== Unified kernel images ===
 
[[Unified kernel image]]s in {{ic|''esp''/EFI/Linux/}} are automatically sourced by systemd-boot, and do not need an entry in {{ic|''esp''/loader/entries}}. (Note that unified kernel images must have a {{ic|.efi}} extension to be identified by ''systemd-boot''.)
 
{{Tip|Files in {{ic|''esp''/loader/entries/}} will be booted first if no {{ic|default}} is set in {{ic|''esp''/loader/loader.conf}}. Remove those entries, or set the default with the full file name, i.e. {{ic|1=default arch-linux.efi}}}}
 
=== Grml on ESP ===
 
{{Note|The following instructions are not exclusive to Grml. With slight adjustments, installing other software (e.g., [https://www.system-rescue-cd.org/ SystemRescueCD]) is possible.}}
 
{{Tip|A {{ic|PKGBUILD}} is available: {{AUR|grml-systemd-boot}}.}}
 
[https://grml.org/ Grml] is a small live system with a collection of software for system administration and rescue.
 
In order to install Grml on the ESP, we only need to copy the kernel {{ic|vmlinuz}}, the initramfs {{ic|initrd.img}}, and the squashed image {{ic|grml64-small.squashfs}} from the iso file to the ESP. To do so, first download [https://grml.org/ grml64-small.iso] and mount the file (the mountpoint is henceforth denoted ''mnt''); the kernel and initramfs are located in {{ic|''mnt''/boot/grml64small/}}, and the squashed image resides in {{ic|''mnt''/live/grml64-small/}}.
 
Next, create a directory for Grml in your ESP,
 
# mkdir -p ''esp''/grml
 
and copy the above-mentioned files in there:
 
# cp ''mnt''/boot/grml64small/vmlinuz ''esp''/grml
# cp ''mnt''/boot/grml64small/initrd.img ''esp''/grml
# cp ''mnt''/live/grml64-small/grml64-small.squashfs ''esp''/grml
 
In the last step, create an entry for the systemd-boot loader: In {{ic|''esp''/loader/entries}} create a {{ic|grml.conf}} file with the following content:
 
{{hc|''esp''/loader/entries/grml.conf|2=
title  Grml Live Linux
linux  /grml/vmlinuz
initrd  /grml/initrd.img
options apm=power-off boot=live live-media-path=/grml/ nomce net.ifnames=0
}}
 
For an overview of the available boot options, consult the [https://git.grml.org/?p=grml-live.git;a=blob_plain;f=templates/GRML/grml-cheatcodes.txt;hb=HEAD cheatcode for Grml].
 
=== systemd-boot on BIOS systems ===
 
If you need a bootloader for BIOS systems that follows [https://uapi-group.org/specifications/specs/boot_loader_specification/ The Boot Loader Specification], then systemd-boot can be pressed into service on BIOS systems. The [[Clover]] boot loader supports booting from BIOS systems and provides a emulated UEFI environment.


== Troubleshooting ==
== Troubleshooting ==
Line 210: Line 360:
=== Installing after booting in BIOS mode ===
=== Installing after booting in BIOS mode ===


{{Warning|This is not recommended.}}
{{Note|This is not recommended.}}
 
If booted in BIOS mode, you can still install ''systemd-boot'', however this process requires you to tell firmware to launch ''systemd-boot'''s EFI file at boot:


If booted in BIOS mode, you can still install ''systemd-boot'', however this process requires you to tell firmware to launch ''systemd-boot'''s EFI file at boot, usually via two ways:
* you have a working UEFI Shell somewhere else.
* you have a working EFI Shell somewhere else.
* your firmware interface provides a way of properly setting the EFI file that needs to be loaded at boot time.
* your firmware interface provides a way of properly setting the EFI file that needs to be loaded at boot time.
* some firmware may use the default {{ic|''esp''/EFI/BOOT/BOOTX64.EFI}} if there is no other entry set in the UEFI.


If you can do it, the installation is easier: go into your EFI Shell or your firmware configuration interface and change your machine's default EFI file to {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} ( or {{ic|systemd-bootia32.efi}} depending if your system firmware is 32 bit).
If you can do it, the installation is easier: go into your UEFI Shell or your firmware configuration interface and change your machine's default EFI file to {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}}.


{{Note|The firmware interface of Dell Latitude series provides everything you need to setup EFI boot but the EFI Shell won't be able to write to the computer's ROM.}}
{{Note|The firmware interface of Dell Latitude series provides everything you need to setup UEFI boot but the UEFI Shell will not be able to write to the computer's ROM.}}


=== Manual entry using efibootmgr ===
=== Manual entry using efibootmgr ===


If the {{ic|bootctl install}} command failed, you can create a EFI boot entry manually using {{Pkg|efibootmgr}}:
If the {{ic|bootctl install}} command failed, you can create a UEFI boot entry manually using {{Pkg|efibootmgr}}:
 
# efibootmgr --create --disk /dev/sd''X'' --part ''Y'' --loader '\EFI\systemd\systemd-bootx64.efi' --label "Linux Boot Manager" --unicode
 
where {{ic|/dev/sd''XY''}} is the [[EFI system partition]].


# efibootmgr -c -d /dev/sdX -p Y -l "\EFI\systemd\systemd-bootx64.efi" -L "Linux Boot Manager"
{{Note|The path to the EFI binary must use the backslash ({{ic|\}}) as the separator}}


where {{ic|/dev/sdXY}} is the [[EFI system partition]].
=== Manual entry using bcdedit from Windows ===


{{Note|The path to the EFI image must use the backslash ({{ic|\}}) as the separator}}
If for any reason you need to create an UEFI boot entry from Windows, you can use the following commands from an Administrator prompt:
 
> bcdedit /copy {bootmgr} /d "Linux Boot Manager"
> bcdedit /set {''guid''} path \EFI\systemd\systemd-bootx64.efi
 
Replace {{ic|''guid''}} with the id returned by the first command. You can also set it as the default entry using
 
> bcdedit /default {''guid''}


=== Menu does not appear after Windows upgrade ===
=== Menu does not appear after Windows upgrade ===


See [[UEFI#Windows changes boot order]].
See [[UEFI#Windows changes boot order]].
=== Add support for Windows BitLocker TPM unlocking ===
To stop BitLocker from requesting the recovery key, add the following to ''loader.conf'':
{{hc|''esp''/loader/loader.conf|
reboot-for-bitlocker yes
}}
This will set the ''BootNext'' UEFI variable, whereby ''Windows Boot Manager'' is loaded without BitLocker requiring the recovery key. This is a one-time change, and ''systemd-boot'' remains the default bootloader. There is no need to specify Windows as an entry if it was autodetected.
This is an experimental feature, so make sure to consult {{man|5|loader.conf}}.


== See also ==
== See also ==


* http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/
* https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/
* https://github.com/systemd/systemd/tree/master/src/boot/efi
* https://github.com/systemd/systemd/tree/master/src/boot/efi
* https://bbs.archlinux.org/viewtopic.php?id=254374
* https://uapi-group.org/specifications/specs/boot_loader_specification/

Latest revision as of 04:24, 11 April 2024

Related articles

systemd-boot(7), previously called gummiboot (German for "rubber dinghy"), is an easy-to-configure UEFI boot manager. It provides a textual menu to select the boot entry and an editor for the kernel command line.

Note that systemd-boot can only start EFI executables (e.g., the Linux kernel EFISTUB, UEFI shell, GRUB, or the Windows Boot Manager).

Supported file systems

systemd-boot inherits the support for the file systems from the firmware (i.e. at least FAT12, FAT16 and FAT32). Additionally it loads any UEFI drivers placed in esp/EFI/systemd/drivers/.

Installation

systemd-boot is shipped with the systemd package which is a dependency of the base meta package, so no additional packages need to be installed manually.

Installing the UEFI boot manager

To install systemd-boot, first make sure that the system is booted into UEFI mode and UEFI variables are accessible. This can be verified by running efivar --list or, if efivar is not installed, by running ls /sys/firmware/efi/efivars (if the directory exists, the system is booted into UEFI mode.)

Throughout, esp will denote the ESP mountpoint, e.g. /efi or /boot. This assumes that you have chrooted to the system's mount point.

Use bootctl(1) to install systemd-boot to the ESP: 

# bootctl install

This will copy the systemd-boot UEFI boot manager to the ESP, create a UEFI boot entry for it and set it as the first in the UEFI boot order.

  • On an x64 UEFI, /usr/lib/systemd/boot/efi/systemd-bootx64.efi will be copied to esp/EFI/systemd/systemd-bootx64.efi and esp/EFI/BOOT/BOOTX64.EFI.
  • On an IA32 UEFI, /usr/lib/systemd/boot/efi/systemd-bootia32.efi will be copied to esp/EFI/systemd/systemd-bootia32.efi and esp/EFI/BOOT/BOOTIA32.EFI.

The UEFI boot entry will be called "Linux Boot Manager" and will point to, depending on the UEFI bitness, either \EFI\systemd\systemd-bootx64.efi or \EFI\systemd\systemd-bootia32.efi on the ESP.

Note:
  • When running bootctl install, systemd-boot will try to locate the ESP at /efi, /boot, and /boot/efi. Setting esp to a different location requires passing the --esp-path=esp option. (See bootctl(1) § OPTIONS for details.)
  • Installing systemd-boot will overwrite any existing esp/EFI/BOOT/BOOTX64.EFI (or esp/EFI/BOOT/BOOTIA32.EFI on IA32 UEFI), e.g. Microsoft's version of the file.

To conclude the installation, configure systemd-boot.

Installation using XBOOTLDR

A separate /boot partition of type "Linux extended boot" (XBOOTLDR) can be created to keep the kernel and initramfs separate from the ESP. This is particularly helpful to dual boot with Windows with an existing ESP that is too small.

Prepare an ESP as usual and create another partition for XBOOTLDR on the same physical drive. The XBOOTLDR partition must have a partition type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 [1] (ea00 type for gdisk). The size of the XBOOTLDR partition should be large enough to accommodate all of the kernels you are going to install.

Note:
  • systemd-boot does not do a file system check like it does for the ESP. Hence, it is possible to use any file system that your UEFI implementation can read.
  • UEFI may skip loading partitions other than the ESP when a "fast boot" mode is enabled. This can lead to systemd-boot failing to find entries on the XBOOTLDR partition; in that case, disable the "fast boot" mode.
  • The XBOOTLDR partition must be on the same physical disk as the ESP for systemd-boot to recognize it.

During install, mount the ESP to /mnt/efi and the XBOOTLDR partition to /mnt/boot.

Once in chroot, use the command: 

# bootctl --esp-path=/efi --boot-path=/boot install

To conclude the installation, configure systemd-boot.

Updating the UEFI boot manager

Whenever there is a new version of systemd-boot, the UEFI boot manager can be optionally reinstalled by the user. This can be done manually or automatically; the two approaches are described thereafter.

Note: The UEFI boot manager is a standalone EFI executable and any version can be used to boot the system (partial updates do not apply, since pacman only installs the systemd-boot installer, not systemd-boot itself.) However, new versions may add new features or fix bugs, so it is probably a good idea to update systemd-boot.

Manual update

Use bootctl to update systemd-boot: 

# bootctl update
Note: As with bootctl install, systemd-boot will try to locate the ESP at /efi, /boot, and /boot/efi. Setting esp to a different location requires passing the --esp-path=esp option.

Automatic update

To update systemd-boot automatically, either use a systemd service or a pacman hook. The two methods are described below.

systemd service

As of version 250, systemd ships with systemd-boot-update.service. Enabling this service will update the bootloader upon the next boot.

Warning: If you have Secure Boot enabled, you need to sign your bootloader after updating. See #Signing for Secure Boot below for an example of how to do so.
Tip: If /usr/lib/systemd/boot/efi/systemd-bootarch.efi.signed exists, it will be used in place of /usr/lib/systemd/boot/efi/systemd-bootarch.efi when installing or updating the boot manager. See bootctl(1) § SIGNED .EFI FILES for details.
pacman hook

The package systemd-boot-pacman-hookAUR adds a pacman hook which is executed every time systemd is upgraded.

Rather than installing systemd-boot-pacman-hook, you may prefer to manually place the following file in /etc/pacman.d/hooks/: 

/etc/pacman.d/hooks/95-systemd-boot.hook
[Trigger]
Type = Package
Operation = Upgrade
Target = systemd

[Action]
Description = Gracefully upgrading systemd-boot...
When = PostTransaction
Exec = /usr/bin/systemctl restart systemd-boot-update.service
Signing for Secure Boot

If you have Secure Boot enabled, you may want to add a pacman hook to automatically sign the boot manager upon every upgrade of the package: 

/etc/pacman.d/hooks/80-secureboot.hook
[Trigger]
Operation = Install
Operation = Upgrade
Type = Path
Target = usr/lib/systemd/boot/efi/systemd-boot*.efi

[Action]
Description = Signing systemd-boot EFI binary for Secure Boot
When = PostTransaction
Exec = /bin/sh -c 'while read -r i; do sbsign --key /path/to/keyfile.key --cert /path/to/certificate.crt "$i"; done;'
Depends = sh
Depends = sbsigntools
NeedsTargets

Replace /path/to/keyfile.key and /path/to/certificate.crt with your signing key and certificate respectively. For better understanding of this hook, consult sbsign(1).

Tip: If you are using sbctl then resigning of the files enrolled in its database is automatically done through the hook provided at /usr/share/libalpm/hooks/zz-sbctl.hook. Remember to enroll the files necessary to your bootchain first.

Configuration

Loader configuration

The loader configuration is stored in the file esp/loader/loader.conf. See loader.conf(5) § OPTIONS for details.

A loader configuration example is provided below: 

esp/loader/loader.conf
default  arch.conf
timeout  4
console-mode max
editor   no
Tip:
  • systemd-boot does not accept tabs for indentation, use spaces instead.
  • default and timeout can be changed in the boot menu itself and changes will be stored as UEFI variables LoaderEntryDefault and LoaderConfigTimeout, overriding these options.
  • bootctl set-default "" and bootctl set-timeout "" can be used to clear the UEFI variables overriding the default and timeout options, respectively.
  • If you have set timeout 0, the boot menu can be accessed by pressing Space.
  • A basic loader configuration file is located at /usr/share/systemd/bootctl/loader.conf.
  • If the bootloader (during the entry selection) appears distorted/uses the wrong resolution you can try to set the console-mode to auto (uses heuristics to select the best resolution), keep (keeps the firmware provided resolution) or 2 (tries to select the first non-UEFI-standard resolution).

Remember last entry

As of systemd version 251 or later default can be changed to @saved in order to remember the last picked entry on startup. This is useful for when dual booting Windows and the surprise windows auto update pushes you into Linux. 

esp/loader/loader.conf
default @saved
...

Consult loader.conf(5) for more details.

Adding loaders

systemd-boot will search for boot menu items in esp/loader/entries/*.conf and additionally in boot/loader/entries/*.conf if using XBOOTLDR. Note that entries in esp can only use files (e.g. kernels, initramfs, images, etc.) in esp. Similarly, entries in boot can only use files in boot.

Note: When Secure Boot is active, unified kernel images with an embedded .cmdline ignore all command line options passed to them (either using a boot entry with options or interactively). When Secure Boot is not active, the options passed via the command line override the embedded .cmdline.

An example of loader files launching Arch from a volume using its UUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is: 

esp/loader/entries/arch.conf
title   Arch Linux
linux   /vmlinuz-linux
initrd  /initramfs-linux.img
options root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw
esp/loader/entries/arch-fallback.conf
title   Arch Linux (fallback initramfs)
linux   /vmlinuz-linux
initrd  /initramfs-linux-fallback.img
options root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw

See the Boot Loader Specification for details on all configuration options.

systemd-boot will automatically check at boot time for Windows Boot Manager at the location /EFI/Microsoft/Boot/Bootmgfw.efi, UEFI shell /shellx64.efi and EFI Default Loader /EFI/BOOT/bootx64.efi, as well as specially prepared kernel files found in /EFI/Linux/. When detected, corresponding entries with titles auto-windows, auto-efi-shell and auto-efi-default, respectively, will be generated. These entries do not require manual loader configuration. However, it does not auto-detect other EFI applications (unlike rEFInd), so for booting the Linux kernel, manual configuration entries must be created.

Tip:
  • The available boot entries which have been configured can be listed with the command bootctl list.
  • An example entry file is located at /usr/share/systemd/bootctl/arch.conf.
  • The kernel parameters for scenarios such as LVM, LUKS, dm-crypt or Btrfs can be found on the relevant pages.
Note: If external microcode initramfs images are used (e.g. when using Booster as the initramfs generator), /boot/amd-ucode.img or /boot/intel-ucode.img must be specified in a separate initrd and always be placed first, before the main initramfs image.

UEFI Shells or other EFI applications

In case you installed a UEFI shell with the package edk2-shell, systemd-boot will auto-detect and create a new entry if the EFI file is placed in esp/shellx64.efi. To perform this and example command after installing the package would be: 

# cp /usr/share/edk2-shell/x64/Shell.efi /boot/shellx64.efi

Otherwise in case you installed other EFI applications into the ESP, you can use the following snippets.

Note: The file path parameter for the efi line is relative to the root of your EFI system partition. If your EFI system partition is mounted at /boot and your EFI binaries reside at /boot/EFI/xx.efi and /boot/yy.efi, then you would specify the parameters as efi /EFI/xx.efi and efi /yy.efi respectively.
esp/loader/entries/fwupd.conf
title  Firmware updater
efi     /EFI/tools/fwupdx64.efi

esp/loader/entries/gdisk.conf
title  GPT fdisk (gdisk)
efi     /EFI/tools/gdisk_x64.efi
Memtest86+

You need to install memtest86+-efi for this to work. Also sign the EFI binary when using Secure Boot. 

esp/loader/entries/memtest.conf
title Memtest86+
efi /memtest86+/memtest.efi
Netboot

systemd-boot can chainload Netboot. Download the ipxe-arch.efi EFI binary and signature, verify it and place it as proposed in esp/EFI/arch_netboot/arch_netboot.efi. 

esp/loader/entries/arch_netboot.conf
title Arch Linux Netboot
efi /EFI/arch_netboot/arch_netboot.efi
GRUB

systemd-boot can chainload GRUB. The location of the grubx64.efi binary matches the used --bootloader-id= when GRUB was installed to the ESP. 

esp/loader/entries/grub.conf
title GRUB
efi /EFI/GRUB/grubx64.efi

Boot from another disk

systemd-boot cannot launch binaries from partitions other than the ESP or the XBOOTLDR partition, but it can run an external script to do so.

First we need to install edk2-shell (will be the interpreter to be used). We also need the PARTUUID of the partition where the destination EFI file is located which can be obtained by using the blkid command. Using the UEFI shell (as explained above) we can use the map command to take notes of the FS alias (ex: HD0a66666a2) and the full path of the destination EFI file (ex: EFI\Microsoft\Boot\Bootmgfw.efi). The FS alias corresponds to the PARTUUID of the partition where the destination EFI file is located.

Then using the exit command we can boot back into Linux where we can create the new entry. To do so we need to first create in the root of the esp mount point a .nsh filename with the FS alias, a colon and the EFI path, here an example: 

esp/windows.nsh
HD0a66666a2:EFI\Microsoft\Boot\Bootmgfw.efi

Once we created this file we can proceed to create the loader entry to run the script: 

esp/loader/entries/windows.conf
title  Windows
efi     /shellx64.efi
options -nointerrupt -noconsolein -noconsoleout windows.nsh
Tip: To use Windows with Bitlocker and a PIN, remove -noconsolein.

Its important that the efi path matches where the edk2-shell has been copied in the esp partition, and the last argument of options matches the .nsh filename in the root of the esp partition. Also note that the edk2-shell EFI file can be moved to avoid the entry auto-creation of systemd-boot.

Booting into UEFI firmware setup

systemd-boot will automatically add an entry to boot into UEFI firmware setup if your device's firmware supports rebooting into setup from the OS.

Support hibernation

See Suspend and hibernate.

Kernel parameters editor with password protection

Alternatively you can install systemd-boot-passwordAUR which supports password basic configuration option. Use sbpctl generate to generate a value for this option.

Install systemd-boot-password with the following command: 

# sbpctl install esp

With enabled editor you will be prompted for your password before you can edit kernel parameters.

Tips and tricks

Keys inside the boot menu

You can use t and T while in the menu to adjust the menu timeout and e to edit the kernel parameters for this boot. Press h to see a short list of useful hotkeys. See systemd-boot(7) § KEY BINDINGS for the full list of available key bindings inside the boot menu.

Choosing next boot

The boot manager is integrated with the systemctl command, allowing you to choose what option you want to boot after a reboot. For example, suppose you have built a custom kernel and created an entry file esp/loader/entries/arch-custom.conf to boot into it, you can just launch 

$ systemctl reboot --boot-loader-entry=arch-custom.conf

and your system will reboot into that entry maintaining the default option intact for subsequent boots. To see a list of possible entries pass the --boot-loader-entry=help option.

If you want to boot into the firmware of your motherboard directly, then you can use this command: 

$ systemctl reboot --firmware-setup

Unified kernel images

Unified kernel images in esp/EFI/Linux/ are automatically sourced by systemd-boot, and do not need an entry in esp/loader/entries. (Note that unified kernel images must have a .efi extension to be identified by systemd-boot.)

Tip: Files in esp/loader/entries/ will be booted first if no default is set in esp/loader/loader.conf. Remove those entries, or set the default with the full file name, i.e. default arch-linux.efi

Grml on ESP

Note: The following instructions are not exclusive to Grml. With slight adjustments, installing other software (e.g., SystemRescueCD) is possible.
Tip: A PKGBUILD is available: grml-systemd-bootAUR.

Grml is a small live system with a collection of software for system administration and rescue.

In order to install Grml on the ESP, we only need to copy the kernel vmlinuz, the initramfs initrd.img, and the squashed image grml64-small.squashfs from the iso file to the ESP. To do so, first download grml64-small.iso and mount the file (the mountpoint is henceforth denoted mnt); the kernel and initramfs are located in mnt/boot/grml64small/, and the squashed image resides in mnt/live/grml64-small/.

Next, create a directory for Grml in your ESP, 

# mkdir -p esp/grml

and copy the above-mentioned files in there: 

# cp mnt/boot/grml64small/vmlinuz esp/grml
# cp mnt/boot/grml64small/initrd.img esp/grml
# cp mnt/live/grml64-small/grml64-small.squashfs esp/grml

In the last step, create an entry for the systemd-boot loader: In esp/loader/entries create a grml.conf file with the following content: 

esp/loader/entries/grml.conf
title   Grml Live Linux
linux   /grml/vmlinuz
initrd  /grml/initrd.img
options apm=power-off boot=live live-media-path=/grml/ nomce net.ifnames=0

For an overview of the available boot options, consult the cheatcode for Grml.

systemd-boot on BIOS systems

If you need a bootloader for BIOS systems that follows The Boot Loader Specification, then systemd-boot can be pressed into service on BIOS systems. The Clover boot loader supports booting from BIOS systems and provides a emulated UEFI environment.

Troubleshooting

Installing after booting in BIOS mode

Note: This is not recommended.

If booted in BIOS mode, you can still install systemd-boot, however this process requires you to tell firmware to launch systemd-boot's EFI file at boot:

  • you have a working UEFI Shell somewhere else.
  • your firmware interface provides a way of properly setting the EFI file that needs to be loaded at boot time.
  • some firmware may use the default esp/EFI/BOOT/BOOTX64.EFI if there is no other entry set in the UEFI.

If you can do it, the installation is easier: go into your UEFI Shell or your firmware configuration interface and change your machine's default EFI file to esp/EFI/systemd/systemd-bootx64.efi.

Note: The firmware interface of Dell Latitude series provides everything you need to setup UEFI boot but the UEFI Shell will not be able to write to the computer's ROM.

Manual entry using efibootmgr

If the bootctl install command failed, you can create a UEFI boot entry manually using efibootmgr: 

# efibootmgr --create --disk /dev/sdX --part Y --loader '\EFI\systemd\systemd-bootx64.efi' --label "Linux Boot Manager" --unicode

where /dev/sdXY is the EFI system partition.

Note: The path to the EFI binary must use the backslash (\) as the separator

Manual entry using bcdedit from Windows

If for any reason you need to create an UEFI boot entry from Windows, you can use the following commands from an Administrator prompt: 

> bcdedit /copy {bootmgr} /d "Linux Boot Manager"
> bcdedit /set {guid} path \EFI\systemd\systemd-bootx64.efi

Replace guid with the id returned by the first command. You can also set it as the default entry using 

> bcdedit /default {guid}

Menu does not appear after Windows upgrade

See UEFI#Windows changes boot order.

Add support for Windows BitLocker TPM unlocking

To stop BitLocker from requesting the recovery key, add the following to loader.conf: 

esp/loader/loader.conf
reboot-for-bitlocker yes

This will set the BootNext UEFI variable, whereby Windows Boot Manager is loaded without BitLocker requiring the recovery key. This is a one-time change, and systemd-boot remains the default bootloader. There is no need to specify Windows as an entry if it was autodetected.

This is an experimental feature, so make sure to consult loader.conf(5).

See also

Retrieved from "https://wiki.archlinux.org/index.php?title=Systemd-boot&oldid=805680"