Skip to contentSkip to conversation

add a note on -shim to direct kernel boot docs

PATCH Superseded Gerd Hoffmann 4 participants 6 messages Jun 4 – Jun 9

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 add a note on -shim to direct kernel boot docs

---
 docs/system/linuxboot.rst | 9 +++++++++
 1 file changed, 9 insertions(+)
docs/system/linuxboot.rst +9 -0
index f7573ab80aa2..72af18ce1b5e 100644
@@ -17,6 +17,15 @@ Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
 give the kernel command line arguments. The ``-initrd`` option can be
 used to provide an INITRD image.
 
+The ``-shim`` option specifies the shim.efi binary.  This is needed
+when using direct kernel boot with UEFI secure boot enabled.  The
+verification chain used by linux distros requires shim.efi.  Typically
+shim.efi is signed by micsosoft and verified by the firmware.  The
+linux kernel is signed by the distro and is verified by shim.efi.  So
+without shim.efi in the loop secure boot verification will not work.
+Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
+distro install media.
+
 If you do not need graphical output, you can disable it and redirect the
 virtual serial port and the QEMU monitor to the console with the
 ``-nographic`` option. The typical command line is:
Signature · 1 line
2.54.0
#1 lore raw

Hi Gerd,

Quoted 15 lines · Gerd Hoffmann
---
 docs/system/linuxboot.rst | 9 +++++++++
 1 file changed, 9 insertions(+)
docs/system/linuxboot.rst +2 -0
index f7573ab80aa2..72af18ce1b5e 100644
@@ -17,6 +17,15 @@ Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
 give the kernel command line arguments. The ``-initrd`` option can be
 used to provide an INITRD image.
 
+The ``-shim`` option specifies the shim.efi binary.  This is needed
+when using direct kernel boot with UEFI secure boot enabled.  The

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 31

Quoted 10 lines
docs/system/linuxboot.rst +7 -0
+verification chain used by linux distros requires shim.efi.  Typically
+shim.efi is signed by micsosoft and verified by the firmware.  The
+linux kernel is signed by the distro and is verified by shim.efi.  So
+without shim.efi in the loop secure boot verification will not work.
+Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
+distro install media.
+
 If you do not need graphical output, you can disable it and redirect the
 virtual serial port and the QEMU monitor to the console with the
 ``-nographic`` option. The typical command line is:

Are the double space before sentences expected, or just a broken formatting? Also, s/micsosoft/microsoft.

Regards,
Pierrick

#2 lore raw
In reply to Gerd Hoffmann
Quoted 5 lines · Gerd Hoffmann
---
 docs/system/linuxboot.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

Thanks for this patch; I've tried to expand it to make it more comprehensible to people (like me ;-)) who aren't very familiar with UEFI, but I may have made some errors in the process.

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 20

Quoted 9 lines
docs/system/linuxboot.rst +1 -0
index f7573ab80aa2..72af18ce1b5e 100644
@@ -17,6 +17,15 @@ Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
 give the kernel command line arguments. The ``-initrd`` option can be
 used to provide an INITRD image.
 
+The ``-shim`` option specifies the shim.efi binary.

``...`` around shim.efi (here and below).

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 21

Quoted 1 line
docs/system/linuxboot.rst +0 -0
 This is needed

"when you are booting UEFI firmware and using the ``-kernel`` option to tell UEFI to boot a specific kernel image, and the UEFI firmware you are booting has UEFI secure boot enabled."

(Or is it when the kernel has UEFI secure boot enabled? Or both?)

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 22

Quoted 1 line
docs/system/linuxboot.rst +1 -0
+when using direct kernel boot with UEFI secure boot enabled.

I think we could add here:

"When this option is specified, the guest UEFI firmware will first load and run the shim binary, and then the shim binary will run

Quoted 2 lines

The
+verification chain used by linux distros requires shim.efi. Typically

"Linux" (here and below)

Quoted 1 line

+shim.efi is signed by micsosoft and verified by the firmware. The

"Microsoft"

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 25

Quoted 2 lines
docs/system/linuxboot.rst +2 -0
+linux kernel is signed by the distro and is verified by shim.efi.  So
+without shim.efi in the loop secure boot verification will not work.

What are the symptoms? Does the firmware refuse to start the kernel, or does the kernel produce an error? If we can be specific about the problem that adding a '-shim' argument is fixing, then users may have some chance of finding out about the option when they run into the error and are searching for the solution.

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 27

Quoted 2 lines
docs/system/linuxboot.rst +2 -0
+Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
+distro install media.

I think the BOOT* names are a RedHat-ism -- my local Ubuntu box has "shimx64.efi".

I think we could reasonably expand this to
"in the ``EFI/BOOT/`` directory on distro install media. It might be named something like ``BOOTX64.EFI``, ``BOOTAA64.EFI``, ``shimx64.efi`` or `shimaa64.efi``, depending on your distro and guest architecture."

Do we need to warn the user to make sure they use e.g. a matched shim binary for the guest kernel they're trying to boot, or can anybody's shim binary boot anybody's guest kernel ?

thanks
-- PMM

#3 lore raw
Quoted 33 lines · Peter Maydell
Quoted 5 lines · Gerd Hoffmann
---
 docs/system/linuxboot.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

Thanks for this patch; I've tried to expand it to make it more comprehensible to people (like me ;-)) who aren't very familiar with UEFI, but I may have made some errors in the process.

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 20

Quoted 9 lines
docs/system/linuxboot.rst +1 -0
index f7573ab80aa2..72af18ce1b5e 100644
@@ -17,6 +17,15 @@ Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
 give the kernel command line arguments. The ``-initrd`` option can be
 used to provide an INITRD image.
 
+The ``-shim`` option specifies the shim.efi binary.

``...`` around shim.efi (here and below).

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 21

Quoted 1 line
docs/system/linuxboot.rst +0 -0
 This is needed

"when you are booting UEFI firmware and using the ``-kernel`` option to tell UEFI to boot a specific kernel image, and the UEFI firmware you are booting has UEFI secure boot enabled."

(Or is it when the kernel has UEFI secure boot enabled? Or both?)

Quoted 7 lines

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 22

Quoted 1 line
docs/system/linuxboot.rst +1 -0
+when using direct kernel boot with UEFI secure boot enabled.

I think we could add here:

"When this option is specified, the guest UEFI firmware will first load and run the shim binary, and then the shim binary will run

Oops, tail end of this sentence got lost in the editing process:

...will run the guest kernel.

-- PMM

#4 lore raw
In reply to Peter Maydell
Quoted 9 lines · Peter Maydell

On Thu, 4 Jun 2026 at 14:45, Gerd Hoffmann <[email protected]> wrote:

[..]

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 27

Quoted 2 lines
docs/system/linuxboot.rst +2 -0
+Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
+distro install media.

I think the BOOT* names are a RedHat-ism -- my local Ubuntu box has "shimx64.efi".

Often, you'll have two copies:

$ESP/EFI/BOOT/BOOT*.efi

this is the "UEFI fallback boot mode" compatible copy, which the firmware will use if you just select "boot from this disk/medium". Grub calls this "removable".

$ESP/EFI/$VENDOR/shim*.efi

this is the regular copy that your distro will register with the firmware via a boot entry, usually with the name (and maybe version) of the distro as label.

Quoted 6 lines

I think we could reasonably expand this to
"in the ``EFI/BOOT/`` directory on distro install media. It might be named something like ``BOOTX64.EFI``, ``BOOTAA64.EFI``, ``shimx64.efi`` or `shimaa64.efi``, depending on your distro and guest architecture."

asking "efibootmgr -v" might also work. all of these only work if the host system is set up to use secure boot via shim and..

Quoted 3 lines

Do we need to warn the user to make sure they use e.g. a matched shim binary for the guest kernel they're trying to boot, or can anybody's shim binary boot anybody's guest kernel ?

the vendor cert(s) embedded in the shim need to match what was used to sign the booted bootloader and kernel, and the/a signature on the shim binary must in turn be trusted by the firmware. you cannot mix and match, as that would defeat the purpose of those signatures ;)

#5 lore raw
In reply to Peter Maydell

Hi,

Quoted 4 lines

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 25

Quoted 2 lines
docs/system/linuxboot.rst +2 -0
+linux kernel is signed by the distro and is verified by shim.efi.  So
+without shim.efi in the loop secure boot verification will not work.

What are the symptoms? Does the firmware refuse to start the kernel,

Yes, the firmware refuses to load the kernel with an "Access Denied" error. Newer edk2 versions additionally print a hint that secure boot is most likely the reason for that, so it should be obvious enough.

Quoted 5 lines

docs/system/linuxboot.rst Use ``-kernel`` to provide the Linux kernel image and ``-append`` to · line 27

Quoted 2 lines
docs/system/linuxboot.rst +2 -0
+Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
+distro install media.

I think the BOOT* names are a RedHat-ism -- my local Ubuntu box has "shimx64.efi".

No. The BOOT* names are the ones in the UEFI spec and should work everywhere. Typically there is an additional copy in EFI/$distro/shim*.efi.

Quoted 3 lines

Do we need to warn the user to make sure they use e.g. a matched shim binary for the guest kernel they're trying to boot, or can anybody's shim binary boot anybody's guest kernel ?

Both shim + kernel should come from the same distro. There is no strict version dependency though, usually the fedora shim binary can boot all fedora kernels, except in case some signing key gets rotated or must be revoked.

With additional configuration steps it is also possible to have ubuntu shim boot fedora kernels and visa versa, but that is clearly way beyond the scope of this patch.

The tl;dr version is: take shim + kernel + initrd all from the same install media and things will just work.

take care,
Gerd