html: avoid horizontal overflows, break-word and limit image width

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

diff --git a/system-booting.adoc b/system-booting.adoc
index 61b74df1232182d4d743f3a05149deb2fcd4de70..fcfe6c4dcb205f56ddaab563cb200644aa3d5cb4 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
 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 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
 
 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
 .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 kernels 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
+----

 
 

-Example (keeping kernel 5.0.15-1-pve and copying to an ESP mounted on
-`/mnt/esp`):
+Run `pve-efiboot-tool remove` to remove a kernel from the list of manually
+selected kernels, for example:

 
 ----
 
 ----

-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 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
 
 [[sysboot_systemd_boot_setup]]
 .Setting up a new partition for use as synced ESP
 


@@ -172,19 +183,25 @@ 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
 .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`.
-(The equivalent to running `update-grub` on Systems being booted with `grub`).
+`/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
 
 This is necessary should you make changes to the kernel commandline, or want to

-sync all kernels and initrds after regenerating the latter.
+sync all kernels and initrds.
+
+NOTE: Both `update-initramfs` and `apt` (when necessary) will automatically
+trigger a refresh.

 
 [[sysboot_edit_kernel_cmdline]]
 Editing the kernel commandline
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can modify the kernel commandline in the following places, depending on the
 
 [[sysboot_edit_kernel_cmdline]]
 Editing the kernel commandline
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can modify the kernel commandline in the following places, depending on the

-bootloarder used:
+bootloader used:

 
 .Grub
 
 
 .Grub
 


@@ -195,6 +212,6 @@ The kernel commandline needs to be placed in the variable
 
 .Systemd-boot
 
 
 .Systemd-boot
 

-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`.
+The kernel commandline needs to be placed as one line in `/etc/kernel/cmdline`.
+To apply your changes, run `pve-efiboot-tool refresh`, which sets it as the
+`option` line for all config files in `loader/entries/proxmox-*.conf`.