-[[system_booting]]
-Bootloaders
------------
+[[sysboot]]
+Host Bootloader
+---------------
ifdef::wiki[]
:pve-toplevel:
endif::wiki[]
-{pve} uses one of two bootloaders depending on the disk setup selected in the
-installer.
+{pve} currently uses one of two bootloaders depending on the disk setup
+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).
-[[installer_partitioning_scheme]]
+[[sysboot_installer_part_scheme]]
Partitioning scheme used by the installer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Partition of all bootable disks for supporting older systems.
+[[sysboot_grub]]
Grub
~~~~
`update-grub`.
----
+[[sysboot_systemd_boot]]
Systemd-boot
~~~~~~~~~~~~
corruption to the `vfat` formatted ESPs in case of a system crash, and removes
the need to manually adapt `/etc/fstab` in case the primary boot device fails.
-[[systemd_boot_config]]
+[[sysboot_systemd_boot_config]]
Configuration
^^^^^^^^^^^^^
.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:
-Example (keeping kernel 5.0.15-1-pve and copying to an ESP mounted on
-`/mnt/esp`):
+----
+# 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
----
-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
+
+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
+----
+
+
+[[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 `<partition>`, make sure to pass
+in the right device/partition!
+For example, to format an empty partition `/dev/sda2` as ESP, run the following:
-[[systemd-boot-refresh]]
+----
+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.
-[[edit_kernel_cmdline]]
+[[sysboot_edit_kernel_cmdline]]
Editing the kernel commandline
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The kernel commandline needs to be placed as line in `/etc/kernel/cmdline`
Running `/etc/kernel/postinst.d/zz-pve-efiboot` sets it as `option` line for
all config files in `loader/entries/proxmox-*.conf`.
-
-