[pve-devel] [PATCH docs] system-booting: add instructions to switch install to secure boot

[Christoph Heiss <c.heiss@proxmox.com>]

As this procedure could *potentially* lead to data loss (however
unlikely if followed correctly), put a big warning on top, for safety.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
Tested both (GRUB on ext4, system-boot with ZFS-on-root) scenarios by
installing a clean PVE 8.0, upgrading, rebooting and then following the
instructions.

I will add an additional subsection about removing systemd-boot from the
system in the future. It is not something immediately needed, as it does
not have any impact on booting through Grub - it even acts as a nice
fallback. So it would really be just for "cleanliness" reasons.

 system-booting.adoc | 95 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/system-booting.adoc b/system-booting.adoc
index 7c2b026..41f4a8d 100644
--- a/system-booting.adoc
+++ b/system-booting.adoc
@@ -391,3 +391,98 @@ 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].
+
+Switching an existing installation to Secure Boot
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+WARNING: This can lead to unbootable installation in some cases if not done
+correctly. Reinstalling the host will setup Secure Boot automatically if
+available, without any extra interactions. **Make sure you have a working and
+well-tested backup of your {pve} host!**
+
+An existing UEFI installation can be switched over to Secure Boot if desired,
+without having to reinstall {pve} from scratch.
+
+First, ensure all your system is up-to-date. Next, install all the required
+pre-signed packages as listed above. Grub automatically creates the needed EFI
+boot entry for booting via the default shim.
+
+.systemd-boot
+
+If `systemd-boot` is used as a bootloader (see
+xref:sysboot_determine_bootloader_used[Determine which Bootloader is used]),
+some additional setup is needed. This is only the case if {pve} was installed
+with ZFS-on-root.
+
+To check the latter, run:
+----
+# findmnt /
+----
+
+If the host is indeed running using ZFS as root filesystem, the `FSTYPE` column
+should contain `zfs`:
+----
+TARGET SOURCE           FSTYPE OPTIONS
+/      rpool/ROOT/pve-1 zfs    rw,relatime,xattr,noacl,casesensitive
+----
+
+Next, a suitable potential ESP (EFI system partition) must be found. This can be
+done using the `lsblk` command as following:
+----
+# lsblk -o +FSTYPE
+----
+
+The output should look something like this:
+----
+NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS FSTYPE
+sda      8:0    0   32G  0 disk
+├─sda1   8:1    0 1007K  0 part
+├─sda2   8:2    0  512M  0 part             vfat
+└─sda3   8:3    0 31.5G  0 part             zfs_member
+sdb      8:16   0   32G  0 disk
+├─sdb1   8:17   0 1007K  0 part
+├─sdb2   8:18   0  512M  0 part             vfat
+└─sdb3   8:19   0 31.5G  0 part             zfs_member
+----
+
+In this case, the partitions `sda2` and `sdb2` are the targets. They can be
+identified by the their size of 512M and their `FSTYPE` being `vfat`, in this
+case on a ZFS RAID-1 installation.
+
+These partitions must be properly set up for booting through Grub using
+`proxmox-boot-tool`. This command (using `sda2` as an example) must be run
+separately for each individual ESP:
+----
+# proxmox-boot-tool init /dev/sda2 grub
+----
+
+Afterwards, you can sanity-check the setup by running the following command:
+----
+# efibootmgr -v
+----
+
+This list should contain an entry looking similar to this:
+----
+[..]
+Boot0009* proxmox       HD(2,GPT,..,0x800,0x100000)/File(\EFI\proxmox\shimx64.efi)
+[..]
+----
+
+NOTE: The old `systemd-boot` bootloader will be kept, but Grub will be
+preferred. This way, if booting using Grub in Secure Boot mode does not work for
+any reason, the system can still be booted using `systemd-boot` with Secure Boot
+turned off.
+
+Now the host can be rebooted and Secure Boot enabled in the UEFI firmware setup
+utility.
+
+On reboot, a new entry named `proxmox` should be selectable in the UEFI firmware
+boot menu, which boots using the pre-signed EFI shim.
+
+If, for any reason, no `proxmox` entry can be found in the UEFI boot menu, you
+can try adding it manually (if supported by the firmware), by adding the file
+`\EFI\proxmox\shimx64.efi` as a custom boot entry.
+
+TIP: To enroll custom keys, see the accompanying
+https://pve.proxmox.com/wiki/Secure_Boot_Setup#Setup_instructions_for_db_key_variant[Secure
+Boot wiki page].
--
2.42.0