Translation(s): none
Since Wheezy, Debian kernels on platforms with UEFI (e.g. x86, ARM, RISC-V) contain their own BootLoader called EFI stub. Therefore it is possible to load the kernel directly, without any additional bootloader (like grub-efi). With the help of systemd-stub, it's also possible to create a Unified Kernel Image, combining the kernel, cmdline, initrd, and an optional splash screen into one single EFI binary, convenient for SecureBoot signing.
Contents
Manually setting up EFIStub
To set up EFIStub, you need to first copy the kernel and initrd into the EFI system partition, then set up an EFI boot entry for it.
Copy the files
The UEFI firmware is only able to load files from the EFI partition (usually FAT). If you use a standard UEFI installation of Debian, you should copy the kernel and the initrd to /boot/efi. The best way to keep it up to date is to place a script in /etc/kernel/postinst.d/zz-update-efistub:
Make it executable and create the destination folder:
chmod +x /etc/kernel/postinst.d/zz-update-efistub mkdir -p /boot/efi/EFI/Debian
Repeat for the initrd update hook in /etc/initramfs/post-update.d/zz-update-efistub:
Make it executable:
chmod +x /etc/initramfs/post-update.d/zz-update-efistub
To copy the kernel and initrd while also testing the hooks work correctly run:
dpkg-reconfigure linux-image-$(uname -r)
Add the boot entry
Replace /dev/sda3 with the device of your / partition. The --disk and --part options specify your EFI partition (here /dev/sdb1). Paths are relative to the root of the EFI partition (with optional leading / or \). efibootmgr will translate forward slashes to backslashes for the --loader option, but the initrd= option must use backslashes because it is interpreted in the EFI environment.
export UUID=$(blkid -s UUID -o value /dev/sda3) efibootmgr --create --disk /dev/sdb --part 1 --label "Debian" --loader EFI/Debian/vmlinuz --unicode "root=UUID=$UUID ro initrd=EFI\\Debian\\initrd.img"
You can check your new boot entry. Since EFI uses UCS2, it should look like this:
#efibootmgr -v ... .i.n.i.t.r.d.=.\.E.F.I.\.d.e.b.i.a.n.\.i.n.i.t.r.d.
The kernel and initramfs hooks above will be run on every kernel or initrd update. Depending on the order of operations it is possible to end up with the wrong kernel and/or initramfs copied. Running update-initramfs -u -k all in particular will update initramfs' in reverse order of kernel versions (the last initramfs updated -- and copied -- will be the one for the oldest kernel installed). If the kernel and initramfs are mismatched the system will very likely fail to boot. Always keep another boot manager like grub-efi or refind installed as backup.
Setting up EFIStub with a script
There are many automated solutions available for EFIStub. Here's an example from TriMoon:
Create the script below with it's contents. (Tip: Highlight and copy with linenumbers hidden)
- Edit the parts to accommodate your needs.
See the bash, findmnt and efibootmgr manpages of the utilities used in this script.
- Make it executable.
chmod a+x /sbin/create_EFI_Boot_Entry.sh
Execute the script as root.
sudo create_EFI_Boot_Entry.sh
Here are some line numbers with usage explanation:
#13 The label you will see in the EFI boot menu.
#14 The kernel image to use by the UEFI-BIOS. (must be inside the EFI partition)
#15 The initrd image to use by the UEFI-BIOS. (must be inside the EFI partition)
#17-20 Compose default kernel parameters.
#18 Sets the file system partition for '/' to use by the kernel. (Automatically found from running system)
#19 Sets the file system type of '/' for use by the kernel. (Automatically found from running system)
#20 Sets the initrd image for use by the kernel. (from value at #15)
#24 Grabs the default kernel parameters in use inside Grub2's config file. (Automatically found from running system)
#27-38 Combine default and extra kernel parameters.
#28-30 Used when Grub2 config is detected (Combines values from #18-20 with #24)
#32-37 Used when there is NO Grub2 config detected. (Combines values from #18-20 with Manual extra kernel parameters)
#34-37 Manual extra kernel parameters that you can set that will be appended to the defaults from #18-20.
1 #!/usr/bin/env bash
2 # /sbin/create_EFI_Boot_Entry.sh v0.2
3 # Automatically create an EFI Boot entry.
4 #
5 # (C) 2018+ ©TriMoon™ <https://github.com/TriMoon>
6 # ------------------------------------------------
7 # License: BY-SA 4.0
8 # This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
9 # https://creativecommons.org/licenses/by-sa/4.0/
10 #
11
12 # First compose the variables used as arguments:
13 label='Debian (EFI stub)'
14 loader='\EFI\debian\vmlinuz' # Use single \'s !
15 initrd='\EFI\debian\initrd.img' # Use single \'s !
16 # Compose default kernel arguments for an EFI-boot
17 printf -v largs "%s " \
18 "root=UUID=$(findmnt -kno UUID /) ro" \
19 "rootfstype=$(findmnt -kno FSTYPE /)" \
20 "initrd=${initrd}"
21 # Grab extra kernel arguments from grub2 config.
22 grub_cmdline=''
23 if test -f /etc/default/grub; then
24 grub_cmdline="$(sed -nE '/^GRUB_CMDLINE_LINUX_DEFAULT=\"/ {s#GRUB_CMDLINE_LINUX_DEFAULT=\"##; s#\"$##; p}' </etc/default/grub)"
25 fi
26 # Append extra kernel arguments
27 if test -n "${grub_cmdline}"; then
28 printf -v largs "%s " \
29 "${largs%* }" \
30 "${grub_cmdline}"
31 else
32 printf -v largs "%s " \
33 "${largs%* }" \
34 "quiet splash" \
35 "add_efi_memmap" \
36 "intel_iommu=on" \
37 "nvidia-drm.modeset=1"
38 fi
39 # echo "${largs%* }"; exit
40 # Then create the EFI entry:
41 efibootmgr -c -L "${label}" -l "${loader}" -u "${largs%* }"
On my system this EFI-entry was created using the script above:
Boot0000* Debian (EFI stub) HD(1,GPT,1e4d16a9-ba85-4a29-9fd1-277c77f4e461,0x800,0x100000)/File(\EFI\DEBIAN\VMLINUZ)r.o.o.t.=.U.U.I.D.=.7.9.2.0.e.1.9.8.-.5.0.5.6.-.4.e.b.4.-.b.3.7.c.-.1.a.b.f.8.1.c.5.a.e.8.d. .r.o. .r.o.o.t.f.s.t.y.p.e.=.e.x.t.4. .i.n.i.t.r.d.=.\.E.F.I.\.d.e.b.i.a.n.\.i.n.i.t.r.d...i.m.g. .q.u.i.e.t. .s.p.l.a.s.h. .i.n.t.e.l._.i.o.m.m.u.=.o.n. .n.v.i.d.i.a.-.d.r.m...m.o.d.e.s.e.t.=.1. .h.u.g.e.p.a.g.e.s.z.=.1.G.B. .h.u.g.e.p.a.g.e.s.=.4.
If you were installing Debian from UEFI medium, efibootmgr should be installed by default. However, sometimes it can report that EFI variables are not supported. If you are sure that you have EFI partition, probably you need to download efivar package and modprobe efivars module.
Secure Boot
Debian kernels are already signed with Debian's key, and DKMS modules provided by Debian should be signed by the DKMS signing key.
Since the kernel image is booted directly by the UEFI the Debian UEFI CA cert (and the DKMS signing key if applicable) must be added to the UEFI.
How exactly this is done varies by manufacturer and motherboard model, but it generally implies copying the keys to some storage accessible by the UEFI, usually a USB stick formated as FAT (but it could also be a FAT partition on an internal drive), and importing them via the key management interface in the UEFI setup, typically as a Database Key (db), though it might be called something else by each UEFI.
![/!\](/htdocs/debwiki/img/alert.png "/!\"){kind=small}
Disregard all information on adding a Machine Owner Key (MOK) since that implies using shim.
Setting up a Unified Kernel Image
To build a unified kernel image, you will need the systemd-boot-efi and binutils packages installed, as well as sbsigntool if you want to sign the image. You will also need to place your kernel cmdline into a file to be read by the tool used.
Manually
Some math is used to calculate the offsets that each part of the image are placed in, then objcopy is used to create the image:
1 align="$(objdump -p /usr/lib/systemd/boot/efi/linuxx64.efi.stub | awk '{ if ($1 == "SectionAlignment"){print $2} }')"
2 align=$((16#$align))
3 osrel_offs="$(objdump -h "/usr/lib/systemd/boot/efi/linuxx64.efi.stub" | awk 'NF==7 {size=strtonum("0x"$3); offset=strtonum("0x"$4)} END {print size + offset}')"
4 osrel_offs=$((osrel_offs + "$align" - osrel_offs % "$align"))
5 cmdline_offs=$((osrel_offs + $(stat -Lc%s "/usr/lib/os-release")))
6 cmdline_offs=$((cmdline_offs + "$align" - cmdline_offs % "$align"))
7 splash_offs=$((cmdline_offs + $(stat -Lc%s "/path/to/cmdline")))
8 splash_offs=$((splash_offs + "$align" - splash_offs % "$align"))
9 initrd_offs=$((splash_offs + $(stat -Lc%s "/path/to/splash.bmp")))
10 initrd_offs=$((initrd_offs + "$align" - initrd_offs % "$align"))
11 linux_offs=$((initrd_offs + $(stat -Lc%s "/path/to/initrd.img")))
12 linux_offs=$((linux_offs + "$align" - linux_offs % "$align"))
13
14 objcopy \
15 --add-section .osrel="/usr/lib/os-release" --change-section-vma .osrel=$(printf 0x%x $osrel_offs) \
16 --add-section .cmdline="/path/to/cmdline" --change-section-vma .cmdline=$(printf 0x%x $cmdline_offs) \
17 --add-section .splash="/path/to/splash.bmp" --change-section-vma .splash=$(printf 0x%x $splash_offs) \
18 --add-section .initrd="/path/to/initrd.img" --change-section-vma .initrd=$(printf 0x%x $initrd_offs) \
19 --add-section .linux="/path/to/vmlinuz" --change-section-vma .linux=$(printf 0x%x $linux_offs) \
20 "/usr/lib/systemd/boot/efi/linuxx64.efi.stub" "/boot/efi/EFI/Linux/debian.efi"
Replace example paths with the actual paths to kernel, cmdline, initrd, and the splash image (/dev/null can be used to disable the splash screen). Optionally sign the image for SecureBoot:
sbsign --key /path/to/db.key --cert /path/to/db.crt --output /boot/efi/EFI/Linux/debian.efi /boot/efi/EFI/Linux/debian.efi
This will need to be done every time the kernel is updated, initrd is regenerated, or the cmdline is changed. There are apt hooks like this available that automatically manage this.
With systemd-ukify
systemd's ukify provides an easy way to generate unified kernel images. To run it automatically with every kernel upgrade and initrd generation, create these two scripts:
/etc/kernel/postinst.d/zz-ukify:
1 #!/bin/bash
2 set -e
3
4 /usr/lib/systemd/ukify build \
5 --linux="$2" \
6 --initrd="/boot/initrd.img-$1" \
7 --cmdline="replace with your cmdline" \
8 --splash="/path/to/splash.bmp" \ # Remove this line if you don't want one
9 --output="/boot/efi/EFI/Linux/debian.efi"
10
11 # Add this line if you want to sign the image for secure boot
12 sbsign --key /path/to/db.key --cert /path/to/db.crt --output /boot/efi/EFI/Linux/debian.efi /boot/efi/EFI/Linux/debian.efi
/etc/initramfs/post-update.d/zz-ukify:
1 #!/bin/bash
2 set -e
3
4 /usr/lib/systemd/ukify build \
5 --linux="/boot/vmlinuz-$1" \
6 --initrd="$2" \
7 --cmdline="replace with your cmdline" \
8 --splash="/path/to/splash.bmp" \ # Remove this line if you don't want one
9 --output="/boot/efi/EFI/Linux/debian.efi"
10
11 # Add this line if you want to sign the image for secure boot
12 sbsign --key /path/to/db.key --cert /path/to/db.crt --output /boot/efi/EFI/Linux/debian.efi /boot/efi/EFI/Linux/debian.efi
Make them executable, create the destination folder, and update the initrd to create the first image:
chmod +x /etc/kernel/postinst.d/zz-ukify chmod +x /etc/initramfs/post-update.d/zz-ukify mkdir -p /boot/efi/EFI/Linux update-initramfs -u
With mkosi-initrd
A UKI can provide many more features than what can be obtained by assembling it manually from Debian's initramfs-tools initrd. Using mkosi it is possible to set up local builds of UKIs that assemble the initrd using standard Debian packages, instead of the initramfs-tools or dracut local scripts. Among other things, this also sets up the UKI with a corresponding signed TPM2 policy, so that secrets (e.g.: full disk encryption with systemd-cryptenroll) can be sealed against the public key signing the image, rather than raw values that change on every build.
Install the required packages:
apt install mkosi systemd-boot-efi
Set up the kernel-install configuration to make it use mkosi-initrd:
1 mkdir -p /etc/kernel/
2 cat <<EOF >/etc/kernel/install.conf
3 initrd_generator=mkosi-initrd
4 uki_generator=mkosi
5 layout=uki
6 EOF
7
8 This is enough to get an initrd with the default configuration, that will match the content of the local host in terms of kernel modules being loaded. A kernel command line can be added via /etc/kernel/cmdline, for example to configure a rootfs on a BTRFS subvolume and plymouth:
9 {{{#!highlight bash
10 mkdir -p /etc/kernel/
11 cat <<EOF >/etc/kernel/cmdline
12 rootflags=subvol=@rootfs quiet splash
13 EOF
In case additional packages are required, for example any firmware package, a mkosi-initrd configuration can be also added. This can be extended at will, including any desired extra packages, a root password for emergency shell, etc.
For example, to add plymouth, firmware for Atheros wifi cards and the kernel module for erofs:
A /etc/mkosi-initrd/mkosi.extra/ directory can also be created, and any file/directory under it will be added to the root of the generated initrd.
To sign the UKI and its PCR policies the means to access a signing key must be given, for a plaintext key (not recommended):
It is better for security to store the secret key on a hardware token, but be aware that this means interactive builds are required, so automated generation of the UKI will need to be disabled (along with unattended-upgrades). For example, if the key can be used via PKCS11:
1 mkdir -p /etc/mkosi-initrd/
2 cat <<EOF >>/etc/mkosi-initrd/mkosi.conf
3 [Validation]
4 SecureBoot=yes
5 SecureBootKeySource=provider:pkcs11
6 SecureBootCertificateSource=provider:pkcs11
7 SecureBootKey=pkcs11:<PKCS%%URI>
8 SecureBootCertificate=pkcs11:<PKCS%%URI>
9 SignExpectedPcrKeySource=provider:pkcs11
10 SignExpectedPcrCertificateSource=provider:pkcs11
11 SignExpectedPcrKey=pkcs11:<PKCS%%URI>
12 SignExpectedPcrCertificate=pkcs11:<PKCS%%URI>
13 EOF
For SecureBoot, the public key needs to be enrolled in MOK, following the same steps detailed elsewhere on this page.
Finally, when the configuration is in the desired state, build UKIs for all available kernels:
kernel-install add-all
With a pre-built UKI
The upstream systemd project has started offering pre-built UKIs for some combinations of distributions and architectures, built and signed on the SUSE Open Build Service. These are NOT official Debian images. They also use bleeding-edge systemd inside the initrd, built from git main. Debian testing amd64 and arm64 are offered.
These are NOT OFFICIAL Debian images, and are experimental and bleeding edge, use at own risk
1 mkdir -p /etc/sysupdate.d/
2 cat <<EOF >>/etc/sysupdate.d/70-upstream-UKI.transfer
3 [Source]
4 Type=url-file
5 Path=https://download.opensuse.org/repositories/system:/systemd/Debian_Testing_images/
6 MatchPattern=debian-trixie_@v_%a.efi
7
8 [Target]
9 Type=regular-file
10 Path=/EFI/Linux
11 PathRelativeTo=boot
12 MatchPattern=debian-trixie_@v_%a+@l-@d.efi \
13 debian-trixie_@v_%a+@l.efi \
14 debian-trixie_@v_%a.efi
15 Mode=0644
16 TriesLeft=3
17 TriesDone=0
18 InstancesMax=2
19 EOF
The key that signs the shasum needs to be added to the importd keyring:
1 wget https://build.opensuse.org/projects/system:systemd/signing_keys/download?kind=gpg -O- | gpg --dearmor > /etc/systemd/import-pubring.gpg
If SecureBoot is enabled (recommended!) the signing key needs to be imported in DB or MOK:
After these setup steps are completed, systemd-sysupdate can be ran and it will fetch and install the UKI, and keep it up to date when configured to run on a timer:
1 systemctl enable --now systemd-sysupdate.timer
GNOME 49 will also include automated support for sd-sysupdate via the GNOME Software program.
If customizations to the kernel command line and/or initrd are necessary, it is recommended to build local addons with mkosi-addon and place them under the global addon directory in the ESP: /boot/efi/loader/addons/ If SecureBoot is used, self-signing can be done, and remember to enroll the key in MOK.
The build process for these UKIs happens on OBS: https://build.opensuse.org/package/show/system:systemd/particleos-debian Users familiar with OBS can branch that package and customize the build for their own needs, and adjust the systemd-sysupdate configuration, URLs, keys, etc accordingly.
Add the boot entry
Assuming your EFI partition in on /dev/sdb1:
efibootmgr --create --disk /dev/sdb --part 1 --label "Debian" --loader '\EFI\Linux\debian.efi'
Automatic initrd generation can be disabled by setting INITRD=no in /etc/initramfs-tools/initramfs.conf