run make update

[pve-docs.git] / system-booting.adoc

diff --git a/system-booting.adoc b/system-booting.adoc
index 28507a2d4c1587e61e6b88e5b118c2e82425a3e0..fefc9636f7613d2cce853ce2fd3a623afa4f07a7 100644 (file)
--- 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,29 +120,38 @@ 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
+----
 
-Example (keeping kernel 5.0.15-1-pve and copying to an ESP mounted on
-`/mnt/esp`):
+`pve-efiboot-tool kernel list` will list all kernel versions currently selected
+for booting:
 
 ----
-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 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
+----
+
+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
 
@@ -158,7 +169,7 @@ pve-efiboot-tool format /dev/sda2
 ----
 
 To setup an existing, unmounted ESP located on `/dev/sda2` for inclusion in
-{pve}'s synchronization mechanism, use the following:
+{pve}'s kernel update synchronization mechanism, use the following:
 
 ----
 pve-efiboot-tool init /dev/sda2
@@ -172,8 +183,11 @@ trigger a refresh of all configured ESPs.
 .Updating the configuration on all ESPs
 
 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`.
+`/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 want to