attrs: update cephdocs template to quincy

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

diff --git a/system-booting.adoc b/system-booting.adoc
index 2b96409bffe57b8485522b9feae91c2c79f94735..30621a6a7bfccaf8bb2c04bc43a01c64739994d0 100644 (file)
--- 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,61 @@ 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]]
+Override the Kernel-Version for next Boot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To select a kernel that is not currently the default kernel, you can either:
+
+* use the boot loader menu that is displayed at the beginning of the boot
+  process
+* use the `proxmox-boot-tool` to `pin` the system to a kernel version either
+  once or permanently (until pin is reset).
+
+This should help you work around incompatibilities between a newer kernel
+version and the hardware.
+
+NOTE: Such a pin should be removed as soon as possible so that all current
+security patches of the latest kernel are also applied to the system.
+
+For example: To permanently select the version `5.15.30-1-pve` for booting you
+would run:
+
+----
+# proxmox-boot-tool kernel pin 5.15.30-1-pve
+----
+
+TIP: 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.
+
+You can also set a kernel version to be booted on the next system boot only.
+This is for example useful 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.30-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`. As that happens already automatically on boot,
+invonking it manually 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.
+
+TIP: You will be prompted to automatically do for  `proxmox-boot-tool` managed
+systems if you call the tool interactively.
+
+----
+# proxmox-boot-tool refresh
+----