From Gentoo Wiki
Jump to:navigation Jump to:search

systemd-boot, formerly called gummiboot, is a minimal UEFI boot manager which loads EFI executables.


  • No extra package installation (with systemd profile).
  • Integration with systemd with the bootctl command.
  • Ability to select next boot.
  • Easy and simple configuration files which can be generated automatically.
  • Auto add Windows and BIOS setup entries.
  • Change timeout, default entry, edit command line options on the fly from boot menu.

Kernel Configuration

Because systemd-boot can only load EFI executables, the desired kernel must support EFI stub (CONFIG_EFI_STUB=y):

KERNEL Enable EFI stub support
Processor type and features  --->
    [*] EFI runtime service support 
    [*]   EFI stub support
    [ ]     EFI mixed-mode support


Since systemd 220 systemd-boot is included in sys-apps/systemd package.


Install the sys-boot/systemd-boot package:

root #mkdir -p /etc/portage/package.accept_keywords
root #echo "sys-boot/systemd-boot" >> /etc/portage/package.accept_keywords/systemd-boot
root #emerge --ask sys-boot/systemd-boot


(Re)emerge sys-apps/systemd with USE=gnuefi:

root #mkdir -p /etc/portage/package.use
root #echo "sys-apps/systemd gnuefi" >> /etc/portage/package.use/systemd
root #emerge --ask --verbose sys-apps/systemd

Installation to ESP (EFI system partition)

First make sure the system booted in UEFI mode. If following command gives error, then reboot in UEFI mode.

root #ls /sys/firmware/efi/efivars

To dual boot with Windows, make sure to use same ESP for both Windows & Linux.

root #sfdisk --list /dev/sdX | grep EFI
/dev/sdX1      2048   1261567   1259520  615M EFI System
/dev/sdX5 487587840 488112127    524288  256M EFI System

In this case there are two ESPs, administrator knows sdX1 is Windows' and sdX5 is Linux's ESP. To dual-boot, install systemd-boot to Windows' ESP.

root #mkdir -p /boot/efi
root #umount /boot/efi
root #mount <The ESP here i.e. /dev/sdX1> /boot/efi
root #bootctl --esp-path=/boot/efi install

Last command will install necessary files into ESP and move systemd-boot to top in boot order.



  • Main configuration for systemd-boot is done in ESP/loader/loader.conf
  • Boot menu entries are generated for each file ending with .conf located in ESP/loader/entries/
  • EFI executable files (Kernel) and initramfs files can be placed anywhere in ESP.


File is located in ESP/loader/loader.conf. Although it is well documented in loader.conf, here is the example:

FILE /boot/efi/loader/loader.conf
default gentoo-sources-kernel
timeout 3
# editor no

The name of the default entry is the file name of the menu entry file, as created in the next section, without the .conf suffix.

Menu entry files

These files needs to be located in ESP/loader/entries/ with .conf extension. Boot menu will show entry for each .conf file.

Following is an example menu entry file named "gentoo-sources-kernel" where the kernel and initramfs are at /boot/efi/vmlinuz and /boot/efi/initramfs respectively:

FILE /boot/efi/loader/entries/gentoo-sources-kernel.confMenu entry file
title Gentoo Linux
linux /vmlinuz
initrd /initramfs
options root=/dev/sda3 quiet

For more options please refer Bootloader Specification

Automatically generate entries

Manually writing menu entry files every time the kernel is updated can be quite troublesome. There's a way to automatically generate menu entry files just after installing a kernel. For that, first install sys-kernel/installkernel-systemd-boot. Now, when installing a kernel it'll generate menu entry .conf file.

As this package uses kernel-install command in backend, refer to kernel-install for further customize this automation.

Configuration in boot menu

The default entry, increase/decrease timeout, edit command line options, and change resolution are accessible right from boot menu. Refer to systemd-boot’s KEY-BINDINGS section for keyboard shortcuts.

Setting a password

A project called systemd-boot-password exists in order to set a password on the systemd-boot menu. This is to prevent unauthorized changes to the kernel command-line and/or other boot parameters, which could compromise controls around system security. As of 2022-12-13, systemd-boot-password is not available in the ::gentoo ebuild repository, and must be manually installed.

Other secondary bootloaders such as GRUB have password protection features as well.

Updating process

Even though package is handled by Portage, necessary files in ESP should be updated every time package is updated. To set this up easily with Portage, create following file:

FILE /etc/portage/env/sys-apps/systemdsystemd-boot update hook
if [ "${EBUILD_PHASE}" == "postinst" ];
	bootctl --no-variables --graceful update


Solve low space with extended boot

Placing multiple kernel, initramfs files alongside with Windows files on same partition (if dual-booting) can cause lack of space and result in errors while installing kernel.

Solution is to separate "Extended Boot Loader Partition" (XBOOTLDR) from ESP. So XBOOTLDR will have relatively big kernel and initramfs along with menu entry files, while loader.conf and small necessary files for systemd-boot will be on ESP.

XBOOTLDR partition is same as ESP (with FAT filesystem), just a different partition GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 needs to be used.

root #mkdir -p /efi
root #mkdir -p /boot
root #umount -R /boot
root #umount /efi
root #mount <The ESP here> /efi
root #mount <The XBOOTLDR here> /boot
root #bootctl --esp-path=/efi --boot-path=/boot install

External resources

See also

  • Systemd — a modern SysV-style init and rc replacement for Linux systems.