X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=system-booting.adoc;h=fefc9636f7613d2cce853ce2fd3a623afa4f07a7;hp=4fad0444b739a2f93fdfb28c38635ce1f1577ab5;hb=7cbed89a6301e81181bd94a11290b2178ab31adc;hpb=69055103c00285d279d17e9f54ddc8d1e7854ca4 diff --git a/system-booting.adoc b/system-booting.adoc index 4fad044..fefc963 100644 --- a/system-booting.adoc +++ b/system-booting.adoc @@ -79,14 +79,16 @@ system boots even if the first boot device fails. The ESPs are kept in sync by a kernel postinstall hook script `/etc/kernel/postinst.d/zz-pve-efiboot`. The script copies certain kernel versions and the initrd images to `EFI/proxmox/` on the root of each ESP and creates the appropriate config files in -`loader/entries/proxmox-*.conf`. +`loader/entries/proxmox-*.conf`. The `pve-efiboot-tool` script assists in +managing both the synced ESPs themselves and their contents. The following kernel versions are configured by default: * the currently running kernel * the version being newly installed on package updates -* the two latest kernels -* the latest version of each kernel series (e.g. 4.15, 5.0). +* the two latest already installed kernels +* the latest version of the second-to-last kernel series (e.g. 4.15, 5.0), if applicable +* any manually selected kernels (see below) The ESPs are not kept mounted during regular operation, in contrast to `grub`, which keeps an ESP mounted on `/boot/efi`. This helps to prevent filesystem @@ -118,40 +120,78 @@ initrd /EFI/proxmox/5.0.15-1-pve/initrd.img-5.0.15-1-pve .Manually keeping a kernel bootable Should you wish to add a certain kernel and initrd image to the list of -bootable kernels you need to: +bootable kernel use `pve-efiboot-tool kernel add`. -* create a directory on the ESP (e.g. `/EFI/personalkernel`) -* copy the kernel and initrd image to that directory -* create a entry for this kernel in `/loader/entries/*.conf` +For example run the following to add the kernel with ABI version `5.0.15-1-pve` +to the list of kernels to keep installed and synced to all ESPs: -NOTE: do not use `/EFI/proxmox` as directory since all entries there can be -removed by `/etc/kernel/postinst.d/zz-pve-efiboot` +---- +pve-efiboot-tool kernel add 5.0.15-1-pve +---- + +`pve-efiboot-tool kernel list` will list all kernel versions currently selected +for booting: + +---- +# pve-efiboot-tool kernel list +Manually selected kernels: +5.0.15-1-pve + +Automatically selected kernels: +5.0.12-1-pve +4.15.18-18-pve +---- + +Run `pve-efiboot-tool remove` to remove a kernel from the list of manually +selected kernels, for example: + +---- +pve-efiboot-tool kernel remove 5.0.15-1-pve +---- -Example (keeping kernel 5.0.15-1-pve and copying to an ESP mounted on -`/mnt/esp`): +NOTE: It's required to run `pve-efiboot-tool refresh` to update all EFI System +Partitions (ESPs) after a manual kernel addition or removal from above. + +[[sysboot_systemd_boot_setup]] +.Setting up a new partition for use as synced ESP + +To format and initialize a partition as synced ESP, e.g., after replacing a +failed vdev in an rpool, or when converting an existing system that pre-dates +the sync mechanism, `pve-efiboot-tool` from `pve-kernel-helpers` can be used. + +WARNING: the `format` command will format the ``, make sure to pass +in the right device/partition! + +For example, to format an empty partition `/dev/sda2` as ESP, run the following: ---- -mkdir /mnt/esp/EFI/preferred-kernel -cp /boot/initrd.img-5.0.15-1-pve /boot/vmlinuz-5.0.15-1-pve /mnt/esp/EFI/preferred-kernel -echo -n "title Preferred Kernel -version 5.0.15-1-pve -linux /mnt/esp/EFI/preferred-kernel/vmlinuz-5.0.15-1-pve -initrd /mnt/esp/EFI/preferred-kernel/initrd.img-5.0.15-1-pve -options " > /mnt/esp/loader/entries/preferred.conf -cat /etc/kernel/cmdline >> /mnt/esp/loader/entries/preferred.conf +pve-efiboot-tool format /dev/sda2 ---- +To setup an existing, unmounted ESP located on `/dev/sda2` for inclusion in +{pve}'s kernel update synchronization mechanism, use the following: + +---- +pve-efiboot-tool init /dev/sda2 +---- + +Afterwards `/etc/kernel/pve-efiboot-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. [[sysboot_systemd_boot_refresh]] .Updating the configuration on all ESPs -To copy and configure all bootable kernels and keep all ESPs in sync you just -need to run the kernel hook script `/etc/kernel/postinst.d/zz-pve-efiboot`. +To copy and configure all bootable kernels and keep all ESPs listed in +`/etc/kernel/pve-efiboot-uuids` in sync you just need to run: + +---- + pve-efiboot-tool refresh +---- (The equivalent to running `update-grub` on Systems being booted with `grub`). -This is necessary should you make changes to the kernel commandline, or if you -want to add another ESP (e.g. when replacing a failed disk in a redundant ZFS -pool). +This is necessary should you make changes to the kernel commandline, or want to +sync all kernels and initrds after regenerating the latter. [[sysboot_edit_kernel_cmdline]] Editing the kernel commandline