add a note on -shim to direct kernel boot docs
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
@@ -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
Hi Gerd,
Quoted 15 lines · Gerd Hoffmann
Signed-off-by Gerd Hoffmann <[email protected]>--- docs/system/linuxboot.rst | 9 +++++++++ 1 file changed, 9 insertions(+)docs/system/linuxboot.rst +2
-0@@ -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
Quoted 5 lines · Gerd Hoffmann
Signed-off-by Gerd Hoffmann <[email protected]>--- 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@@ -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
-0This 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
Quoted 33 lines · Peter Maydell
Quoted 5 lines · Gerd Hoffmann
Signed-off-by Gerd Hoffmann <[email protected]>--- 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@@ -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
-0This 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
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 ;)
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