Skip to contentSkip to conversation

add a note on -shim to direct kernel boot docs

PATCH In review Gerd Hoffmann 3 participants 5 messages Jun 12 – Jun 17

lore
Share & tools
lore
#0 lore raw

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

---
 docs/system/linuxboot.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
docs/system/linuxboot.rst +17 -0
index f7573ab80a..c787481ccc 100644
@@ -17,6 +17,23 @@ 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 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.
+
+When this option is specified, the guest UEFI firmware will first
+load, verify and run the shim binary, which is typically signed by
+Microsoft so the firmware accepts it.  The shim binary in turn will
+load and verify the Linux kernel.  The kernel is typically signed by
+the distro and the certificates needed to verify them are compiled
+into the shim binary, so shim + kernel must come from the same Linux
+distribution.
+
+Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
+distro install media.  You might find a second shim copy in the
+``EFI/$distro/`` directory.
+
 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
Reviewed-by on v2 1/1
#1 lore raw
Quoted 23 lines · Gerd Hoffmann
---
 docs/system/linuxboot.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
docs/system/linuxboot.rst +10 -0
index f7573ab80a..c787481ccc 100644
@@ -17,6 +17,23 @@ 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 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.
+
+When this option is specified, the guest UEFI firmware will first
+load, verify and run the shim binary, which is typically signed by
+Microsoft so the firmware accepts it.  The shim binary in turn will
+load and verify the Linux kernel.  The kernel is typically signed by
+the distro and the certificates needed to verify them are compiled

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

Quoted 10 lines
docs/system/linuxboot.rst +7 -0
+into the shim binary, so shim + kernel must come from the same Linux
+distribution.
+
+Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
+distro install media.  You might find a second shim copy in the
+``EFI/$distro/`` directory.
+
 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:

Good for me, I'll wait for additional reviews to pull it directly.

Regards,
Pierrick

Reviewed-by on v2 1/1
#2 lore raw
In reply to Gerd Hoffmann
Quoted 15 lines · Gerd Hoffmann
---
 docs/system/linuxboot.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
docs/system/linuxboot.rst +1 -0
index f7573ab80a..c787481ccc 100644
@@ -17,6 +17,23 @@ 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

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

Quoted 10 lines
docs/system/linuxboot.rst +10 -0
+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.
+
+When this option is specified, the guest UEFI firmware will first
+load, verify and run the shim binary, which is typically signed by
+Microsoft so the firmware accepts it.  The shim binary in turn will
+load and verify the Linux kernel.  The kernel is typically signed by
+the distro and the certificates needed to verify them are compiled
+into the shim binary, so shim + kernel must come from the same Linux

extremely minor nit, I think I would say "and" rather than "+" here.

Anyway

thanks
-- PMM

#3 lore raw
Quoted 29 lines · Peter Maydell
Quoted 15 lines · Gerd Hoffmann
---
 docs/system/linuxboot.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
docs/system/linuxboot.rst +1 -0
index f7573ab80a..c787481ccc 100644
@@ -17,6 +17,23 @@ 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

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

Quoted 10 lines
docs/system/linuxboot.rst +10 -0
+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.
+
+When this option is specified, the guest UEFI firmware will first
+load, verify and run the shim binary, which is typically signed by
+Microsoft so the firmware accepts it.  The shim binary in turn will
+load and verify the Linux kernel.  The kernel is typically signed by
+the distro and the certificates needed to verify them are compiled
+into the shim binary, so shim + kernel must come from the same Linux

extremely minor nit, I think I would say "and" rather than "+" here.

Quoted 6 lines

Anyway

thanks
-- PMM

Thanks Peter, I'll pull this and add the change you suggested.

Regards,
Pierrick