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 an 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.
+
+NOTE: Some UEFI firmwares are known to drop the `proxmox` boot option on reboot.
+This can happen if the `proxmox` boot entry is pointing to a Grub installation
+on a disk, where the disk itself not a boot option. If possible, try adding the
+disk as a boot option in the UEFI firmware setup utility and run
+`proxmox-boot-tool` again.
+
+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].
+
+Using DKMS/third party modules with Secure Boot
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On systems with Secure Boot enabled, the kernel will refuse to load modules
+which are not signed by a trusted key. The default set of modules shipped with
+the kernel packages is signed with an ephemeral key embedded in the kernel
+image which is trusted by that specific version of the kernel image.
+
+In order to load other modules, such as those built with DKMS or manually, they
+need to be signed with a key trusted by the Secure Boot stack. The easiest way
+to achieve this is to enroll them as Machine Owner Key (`MOK`) with `mokutil`.
+
+The `dkms` tool will automatically generate a keypair and certificate in
+`/var/lib/dkms/mok.key` and `/var/lib/dkms/mok.pub` and use it for signing
+the kernel modules it builds and installs.
+
+You can view the certificate contents with
+
+----
+# openssl x509 -in /var/lib/dkms/mok.pub -noout -text
+----
+
+and enroll it on your system using the following command:
+
+----
+# mokutil --import /var/lib/dkms/mok.pub
+input password:
+input password again:
+----
+
+The `mokutil` command will ask for a (temporary) password twice, this password
+needs to be entered one more time in the next step of the process! Rebooting
+the system should automatically boot into the `MOKManager` EFI binary, which
+allows you to verify the key/certificate and confirm the enrollment using the
+password selected when starting the enrollment using `mokutil`. Afterwards, the
+kernel should allow loading modules built with DKMS (which are signed with the
+enrolled `MOK`). The `MOK` can also be used to sign custom EFI binaries and
+kernel images if desired.
+
+The same procedure can also be used for custom/third-party modules not managed
+with DKMS, but the key/certificate generation and signing steps need to be done
+manually in that case.
projects / pve-docs.git / blobdiff