X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=system-booting.adoc;h=2b96409bffe57b8485522b9feae91c2c79f94735;hp=0b3281062c659c29cb85100a5ad287c7af650263;hb=HEAD;hpb=c9f91b12bb4359a99376b2caed935e2e49013cdc diff --git a/system-booting.adoc b/system-booting.adoc index 0b32810..85247d8 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,12 +31,13 @@ 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` +GRUB in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot +Partition of all selected disks on all systems booted with GRUB footnote:[These are all installs with root on `ext4` or `xfs` and installs with root on ZFS on non-EFI systems]. @@ -49,8 +51,8 @@ Partitions properly configured and synchronized. It copies certain kernel versions to all ESPs and configures the respective bootloader to boot from the `vfat` formatted ESPs. In the context of ZFS as root filesystem this means that you can use all optional features on your root pool instead of the subset -which is also present in the ZFS implementation in `grub` or having to create a -separate small boot-pool footnote:[Booting ZFS on root with grub +which is also present in the ZFS implementation in GRUB or having to create a +separate small boot-pool footnote:[Booting ZFS on root with GRUB https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS]. In setups with redundancy all disks are partitioned with an ESP, by the @@ -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. @@ -175,7 +186,7 @@ Determine which Bootloader is Used The simplest and most reliable way to determine which bootloader is used, is to watch the boot process of the {pve} node. -You will either see the blue box of `grub` or the simple black on white +You will either see the blue box of GRUB or the simple black on white `systemd-boot`. [thumbnail="screenshot/boot-systemdboot.png"] @@ -188,10 +199,10 @@ safest way is to run the following command: # efibootmgr -v ---- -If it returns a message that EFI variables are not supported, `grub` is used in +If it returns a message that EFI variables are not supported, GRUB is used in BIOS/Legacy mode. -If the output contains a line that looks similar to the following, `grub` is +If the output contains a line that looks similar to the following, GRUB is used in UEFI mode. ---- @@ -215,16 +226,16 @@ indication of how the system is booted. [[sysboot_grub]] -Grub +GRUB ~~~~ -`grub` has been the de-facto standard for booting Linux systems for many years +GRUB has been the de-facto standard for booting Linux systems for many years and is quite well documented -footnote:[Grub Manual https://www.gnu.org/software/grub/manual/grub/grub.html]. +footnote:[GRUB Manual https://www.gnu.org/software/grub/manual/grub/grub.html]. Configuration ^^^^^^^^^^^^^ -Changes to the `grub` configuration are done via the defaults file +Changes to the GRUB configuration are done via the defaults file `/etc/default/grub` or config snippets in `/etc/default/grub.d`. To regenerate the configuration file after a change to the configuration run: footnote:[Systems using `proxmox-boot-tool` will call `proxmox-boot-tool @@ -275,7 +286,7 @@ Editing the Kernel Commandline You can modify the kernel commandline in the following places, depending on the bootloader used: -.Grub +.GRUB The kernel commandline needs to be placed in the variable `GRUB_CMDLINE_LINUX_DEFAULT` in the file `/etc/default/grub`. Running @@ -359,3 +370,173 @@ 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 are required for secure boot to work. You can +install them all at once by using the `proxmox-secure-boot-support' +meta-package. + +- `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 is supported as bootloader out of the box, since other bootloader are +currently not eligible for secure boot code-signing. + +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]. + +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 +`proxmox-secure-boot-support`. 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 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 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 +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.