Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 docs/system/linuxboot.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
index f7573ab80aa2..72af18ce1b5e 100644
--- a/docs/system/linuxboot.rst
+++ b/docs/system/linuxboot.rst
@@ -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:
-- 
2.54.0

On Thu, 4 Jun 2026 at 14:45, Gerd Hoffmann <kraxel@redhat.com> wrote:
>
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  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.

> diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
> index f7573ab80aa2..72af18ce1b5e 100644
> --- a/docs/system/linuxboot.rst
> +++ b/docs/system/linuxboot.rst
> @@ -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).

>  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?)

> +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


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

"Linux" (here and below)

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

"Microsoft"

> +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.

> +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

  Hi,

> > +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.

> > +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.

> 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

On June 8, 2026 4:19 pm, Peter Maydell wrote:
> On Thu, 4 Jun 2026 at 14:45, Gerd Hoffmann <kraxel@redhat.com> wrote:

> [..]
> 
>> +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.

> 
> 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..

> 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 ;)

On Mon, 8 Jun 2026 at 15:19, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Thu, 4 Jun 2026 at 14:45, Gerd Hoffmann <kraxel@redhat.com> wrote:
> >
> > Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> > ---
> >  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.
>
> > diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
> > index f7573ab80aa2..72af18ce1b5e 100644
> > --- a/docs/system/linuxboot.rst
> > +++ b/docs/system/linuxboot.rst
> > @@ -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).
>
> >  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?)
>
> > +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

Hi Gerd,

On 6/4/2026 6:44 AM, Gerd Hoffmann wrote:
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  docs/system/linuxboot.rst | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
> index f7573ab80aa2..72af18ce1b5e 100644
> --- a/docs/system/linuxboot.rst
> +++ b/docs/system/linuxboot.rst
> @@ -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:

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

Regards,
Pierrick