[pve-devel] [PATCH docs] boot: add Secure Boot information

[Fabian Grünbichler]

and refer to the (updated) wiki article for more in-depth explanations.

Signed-off-by: Fabian Grünbichler <f.gruenbichler at proxmox.com>
---
 local-zfs.adoc      |  6 +++++-
 system-booting.adoc | 42 +++++++++++++++++++++++++++++++++++++-----
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/local-zfs.adoc b/local-zfs.adoc
index b711f72..63de884 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -524,13 +524,17 @@ process of the new disk has progressed.
 
 ----
 # proxmox-boot-tool format <new disk's ESP>
-# proxmox-boot-tool init <new disk's ESP>
+# proxmox-boot-tool init <new disk's ESP> [grub]
 ----
 
 NOTE: `ESP` stands for EFI System Partition, which is setup as partition #2 on
 bootable disks setup by the {pve} installer since version 5.4. For details, see
 xref:sysboot_proxmox_boot_setup[Setting up a new partition for use as synced ESP].
 
+NOTE: make sure to pass 'grub' as mode to `proxmox-boot-tool init` if
+`proxmox-boot-tool status` indicates your current disks are using Grub,
+especially if Secure Boot is enabled!
+
 .With plain `grub`:
 
 ----
diff --git a/system-booting.adoc b/system-booting.adoc
index 0b32810..7c2b026 100644
--- a/system-booting.adoc
+++ b/system-booting.adoc
@@ -9,8 +9,9 @@ endif::wiki[]
 selected in the installer.
 
 For EFI Systems installed with ZFS as the root filesystem `systemd-boot` is
-used. All other deployments use the standard `grub` bootloader (this usually
-also applies to systems which are installed on top of Debian).
+used, unless Secure Boot is enabled. All other deployments use the standard
+`grub` bootloader (this usually also applies to systems which are installed on
+top of Debian).
 
 
 [[sysboot_installer_part_scheme]]
@@ -30,9 +31,10 @@ The created partitions are:
     used for the chosen storage type
 
 Systems using ZFS as root filesystem are booted with a kernel and initrd image
-stored on the 512 MB EFI System Partition. For legacy BIOS systems, `grub` is
-used, for EFI systems `systemd-boot` is used. Both are installed and configured
-to point to the ESPs.
+stored on the 512 MB EFI System Partition. For legacy BIOS systems, and EFI
+systems with Secure Boot enabled, `grub` is used, for EFI systems without
+Secure Boot, `systemd-boot` is used. Both are installed and configured to point
+to the ESPs.
 
 `grub` in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot
 Partition of all selected disks on all systems booted with `grub`
@@ -100,6 +102,15 @@ To setup an existing, unmounted ESP located on `/dev/sda2` for inclusion in
 # proxmox-boot-tool init /dev/sda2
 ----
 
+or
+
+----
+# proxmox-boot-tool init /dev/sda2 grub
+----
+
+to force initialization with Grub instead of systemd-boot, for example for
+Secure Boot support.
+
 Afterwards `/etc/kernel/proxmox-boot-uuids` should contain a new line with the
 UUID of the newly added partition. The `init` command will also automatically
 trigger a refresh of all configured ESPs.
@@ -359,3 +370,24 @@ systems if you call the tool interactively.
 ----
 # proxmox-boot-tool refresh
 ----
+
+[[sysboot_secure_boot]]
+Secure Boot
+~~~~~~~~~~~
+
+Since {pve} 8.1, Secure Boot is supported out of the box via signed packages
+and integration in `proxmox-boot-tool`.
+
+The following packages need to be installed for Secure Boot to be enabled:
+
+- shim-signed (shim bootloader signed by Microsoft)
+- shim-helpers-amd64-signed (fallback bootloader and MOKManager, signed by Proxmox)
+- grub-efi-amd64-signed (Grub EFI bootloader, signed by Proxmox)
+- proxmox-kernel-6.X.Y-Z-pve-signed (Kernel image, signed by Proxmox)
+
+Only Grub as bootloader is supported out of the box, since there are no other
+pre-signed bootloader packages available. Any new installation of {pve} will
+automatically have all of the above packages included.
+
+More details about how Secure Boot works, and how to customize the setup, are
+available in https://pve.proxmox.com/wiki/Secure_Boot_Setup[our wiki].
-- 
2.39.2