[pve-devel] [PATCH docs 0/2] update proxmox-boot-tool docs

[pve-devel] [PATCH docs 0/2] update proxmox-boot-tool docs

[Stoiko Ivanov]

the 2 patches are independent of each other (I had overlooked 3479 for a while)

Stoiko Ivanov (2):
  zfs: fix #3479 rephrase boot-loader description.
  sys: boot: minimally document kernel version pinning

 local-zfs.adoc      |  8 ++++++--
 system-booting.adoc | 48 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 2 deletions(-)

-- 
2.30.2

[pve-devel] [PATCH docs 1/2] zfs: fix #3479 rephrase boot-loader description.

[Stoiko Ivanov]

since using proxmox-boot-tool also for legacy systems the distinction
of p-b-t vs grub is not accurate anymore.

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 local-zfs.adoc | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/local-zfs.adoc b/local-zfs.adoc
index e77595f..ab0f6ad 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -387,7 +387,8 @@ Changing a failed device
 
 .Changing a failed bootable device
 
-Depending on how {pve} was installed it is either using `proxmox-boot-tool`
+Depending on how {pve} was installed it is either using `systemd-boot` or `grub`
+through `proxmox-boot-tool`
 footnote:[Systems installed with {pve} 6.4 or later, EFI systems installed with
 {pve} 5.4 or later] or plain `grub` as bootloader (see
 xref:sysboot[Host Bootloader]). You can check by running:
@@ -420,11 +421,14 @@ NOTE: `ESP` stands for EFI System Partition, which is setup as partition #2 on
 bootable disks setup by the {pve} installer since version 5.4. For details, see
 xref:sysboot_proxmox_boot_setup[Setting up a new partition for use as synced ESP].
 
-.With `grub`:
+.With plain `grub`:
 
 ----
 # grub-install <new disk>
 ----
+NOTE: plain `grub` is only used on systems installed with {pve} 6.3 or earlier,
+which have not been manually migrated to using `proxmox-boot-tool` yet.
+
 
 Configure E-Mail Notification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.30.2

[pve-devel] [PATCH docs 2/2] sys: boot: minimally document kernel version pinning

[Stoiko Ivanov]

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 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.30.2

[pve-devel] applied-series: [PATCH docs 0/2] update proxmox-boot-tool docs

[Thomas Lamprecht]

On 12.04.22 11:46, Stoiko Ivanov wrote:
> the 2 patches are independent of each other (I had overlooked 3479 for a while)
> 
> Stoiko Ivanov (2):
>   zfs: fix #3479 rephrase boot-loader description.
>   sys: boot: minimally document kernel version pinning
> 
>  local-zfs.adoc      |  8 ++++++--
>  system-booting.adoc | 48 +++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 54 insertions(+), 2 deletions(-)
> 



applied, thanks!