From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 4BE2B9E6CA for ; Mon, 27 Nov 2023 19:23:12 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 2E8DAC8D2 for ; Mon, 27 Nov 2023 19:23:12 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS for ; Mon, 27 Nov 2023 19:23:11 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 0A88C44CF2 for ; Mon, 27 Nov 2023 19:23:11 +0100 (CET) From: Alexander Zeidler To: pbs-devel@lists.proxmox.com Date: Mon, 27 Nov 2023 19:23:01 +0100 Message-Id: <20231127182301.168253-2-a.zeidler@proxmox.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20231127182301.168253-1-a.zeidler@proxmox.com> References: <20231127182301.168253-1-a.zeidler@proxmox.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL 0.066 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record T_SCC_BODY_TEXT_LINE -0.01 - URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [proxmox.com, mok.pub] WEIRD_QUOTING 0.001 Weird repeated double-quotation marks Subject: [pbs-devel] [PATCH proxmox-backup 2/2] docs: sysadmin: add section about Secure Boot X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 27 Nov 2023 18:23:12 -0000 port from pve-docs (mention PBS instead of PVE, fix typos & style) Signed-off-by: Alexander Zeidler --- docs/system-booting.rst | 185 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) diff --git a/docs/system-booting.rst b/docs/system-booting.rst index 6a8443cb..2803212e 100644 --- a/docs/system-booting.rst +++ b/docs/system-booting.rst @@ -381,3 +381,188 @@ content and configuration on the ESPs by running the ``refresh`` subcommand. .. code-block:: console # proxmox-boot-tool refresh + + + +.. _systembooting-secure-boot: + +Secure Boot +~~~~~~~~~~~ + +Since Proxmox Backup 3.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 Proxmox Backup +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 `our wiki `_. + + +.. _systembooting-secure-boot-existing-installation: + +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 Proxmox Backup host!** + +An existing UEFI installation can be switched over to Secure Boot if desired, +without having to reinstall Proxmox Backup 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. + +.. _systembooting-secure-boot-existing-systemd-boot: + +**systemd-boot** +"""""""""""""""" + +If ``systemd-boot`` is used as a bootloader (see +:ref:`Determine which Bootloader is used `), +some additional setup is needed. This is only the case if Proxmox Backup was +installed with ZFS-on-root. + +To check the latter, run: + +.. code-block:: console + + # findmnt / + + +If the host is indeed using ZFS as root filesystem, the ``FSTYPE`` column should +contain ``zfs``: + +.. code-block:: console + + TARGET SOURCE FSTYPE OPTIONS + / rpool/ROOT/pbs-1 zfs rw,relatime,xattr,noacl + +Next, a suitable potential ESP (EFI system partition) must be found. This can be +done using the ``lsblk`` command as following: + +.. code-block:: console + + # lsblk -o +FSTYPE + +The output should look something like this: + +.. code-block:: console + + 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: + +.. code-block:: console + + # proxmox-boot-tool init /dev/sda2 grub + +Afterwards, you can sanity-check the setup by running the following command: + +.. code-block:: console + + # efibootmgr -v + +This list should contain an entry looking similar to this: + +.. code-block:: console + + [..] + 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 is 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 `Secure Boot wiki page + `_. + + +.. _systembooting-secure-boot-other-modules: + +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 + +.. code-block:: console + + # openssl x509 -in /var/lib/dkms/mok.pub -noout -text + +and enroll it on your system using the following command: + +.. code-block:: console + + # 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. -- 2.39.2