From a9a2cdbef1c21fd77930132b3633e1d08b821aca Mon Sep 17 00:00:00 2001 From: Stoiko Ivanov Date: Tue, 12 Apr 2022 11:46:14 +0200 Subject: [PATCH] sys: boot: minimally document kernel version pinning Signed-off-by: Stoiko Ivanov --- system-booting.adoc | 48 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/system-booting.adoc b/system-booting.adoc index 2b96409..7d8ff47 100644 --- a/system-booting.adoc +++ b/system-booting.adoc @@ -68,6 +68,7 @@ device fails. * copying and configuring new kernel images and initrd images to all listed ESPs * synchronizing the configuration on kernel upgrades and other maintenance tasks * managing the list of kernel versions which are synchronized +* configuring the boot-loader to boot a particular kernel version (pinning) You can view the currently configured ESPs and their state by running: @@ -286,3 +287,50 @@ The kernel commandline needs to be placed in the variable The kernel commandline needs to be placed as one line in `/etc/kernel/cmdline`. To apply your changes, run `proxmox-boot-tool refresh`, which sets it as the `option` line for all config files in `loader/entries/proxmox-*.conf`. + + +[[sysboot_kernel_pin]] +Selecting the kernel-version for booting +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to actively watching the boot process to select an older kernel +version to boot into, you can also use `proxmox-boot-tool` to `pin` the kernel +version the system should use. This should help you to work around +incompatibilities between a newer kernel version and the hardware. Such a +`pin` should be removed as soon as possible in order to have all the latest +security patches in place. + +NOTE: The pinning functionality works for all {pve} systems, not only those +using `proxmox-boot-tool` to synchronize the contents of the ESPs, if your +system does not use `proxmox-boot-tool` for synchronizing you can also skip the +`proxmox-boot-tool refresh` call in the end. + +To permanently select the version `5.15.30-1-pve` for booting run: + +---- +# proxmox-boot-tool kernel pin 5.15.30-1-pve +---- + +You can also set a kernel version to be booted on the next system boot only +(e.g. to test if an updated kernel has resolved an issue, which caused you +to `pin` a version in the first place): + +---- +# proxmox-boot-tool kernel pin 5.15.31-1-pve --next-boot +---- + +To remove any pinned version configuration use the `unpin` subcommand: + +---- +# proxmox-boot-tool kernel unpin +---- + +While `unpin` has a `--next-boot` option as well, it is used to clear a pinned +version set with `--next-boot` and manually invoking is of little use. + +After setting or clearing pinned versions you also need to synchronize the +content and configuration on the ESPs by running the `refresh` subcommand: + +---- +# proxmox-boot-tool refresh +---- -- 2.39.2