[pve-devel] [PATCH docs] sys: boot/zfs: adapt docs to proxmox-boot-tool update
Stoiko Ivanov
s.ivanov at proxmox.com
Mon Apr 26 17:46:55 CEST 2021
mostly by copying the existing documentation in a section about
`proxmox-boot-tool` and adapting to the fact that p-b-t also boots
ZFS with grub (on legacy systems)
Signed-off-by: Stoiko Ivanov <s.ivanov at proxmox.com>
---
local-zfs.adoc | 22 ++--
system-booting.adoc | 278 ++++++++++++++++++++++++--------------------
2 files changed, 168 insertions(+), 132 deletions(-)
diff --git a/local-zfs.adoc b/local-zfs.adoc
index 0b1ee37..f024889 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -247,8 +247,8 @@ RAIDZ performance characteristics are acceptable.
Bootloader
~~~~~~~~~~
-Depending on whether the system is booted in EFI or legacy BIOS mode the
-{pve} installer sets up either `grub` or `systemd-boot` as main bootloader.
+{pve} uses xref:sysboot_proxmox_boot_tool[`proxmox-boot-tool`] to manage the
+bootloader configuration.
See the chapter on xref:sysboot[{pve} host bootladers] for details.
@@ -387,8 +387,14 @@ Changing a failed device
.Changing a failed bootable device
-Depending on how {pve} was installed it is either using `grub` or `systemd-boot`
-as bootloader (see xref:sysboot[Host Bootloader]).
+Depending on how {pve} was installed it is either using `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:
+
+----
+# proxmox-boot-tool status
+----
The first steps of copying the partition table, reissuing GUIDs and replacing
the ZFS partition are the same. To make the system bootable from the new disk,
@@ -403,16 +409,16 @@ different steps are needed which depend on the bootloader in use.
NOTE: Use the `zpool status -v` command to monitor how far the resilvering
process of the new disk has progressed.
-.With `systemd-boot`:
+.With `proxmox-boot-tool`:
----
-# pve-efiboot-tool format <new disk's ESP>
-# pve-efiboot-tool init <new disk's ESP>
+# proxmox-boot-tool format <new disk's ESP>
+# proxmox-boot-tool init <new disk's ESP>
----
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_systemd_boot_setup[Setting up a new partition for use as synced ESP].
+xref:sysboot_proxmox_boot_setup[Setting up a new partition for use as synced ESP].
.With `grub`:
diff --git a/system-booting.adoc b/system-booting.adoc
index 24ceb7e..2b96409 100644
--- a/system-booting.adoc
+++ b/system-booting.adoc
@@ -17,15 +17,8 @@ also applies to systems which are installed on top of Debian).
Partitioning Scheme Used by the Installer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The {pve} installer creates 3 partitions on the bootable disks selected for
-installation. The bootable disks are:
-
-* For Installations with `ext4` or `xfs` the selected disk
-
-* For ZFS installations all disks belonging to the first `vdev`:
-** The first disk for RAID0
-** All disks for RAID1, RAIDZ1, RAIDZ2, RAIDZ3
-** The first two disks for RAID10
+The {pve} installer creates 3 partitions on all disks selected for
+installation.
The created partitions are:
@@ -36,8 +29,140 @@ The created partitions are:
* a third partition spanning the set `hdsize` parameter or the remaining space
used for the chosen storage type
+Systems using ZFS as root filesystem are booted with a kernel and initrd image
+stored on the 512 MB EFI System Partition. For legacy BIOS systems, `grub` is
+used, for EFI systems `systemd-boot` is used. Both are installed and configured
+to point to the ESPs.
+
`grub` in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot
-Partition of all bootable disks for supporting older systems.
+Partition of all selected disks on all systems booted with `grub`
+footnote:[These are all installs with root on `ext4` or `xfs` and installs
+with root on ZFS on non-EFI systems].
+
+
+[[sysboot_proxmox_boot_tool]]
+Synchronizing the content of the ESP with `proxmox-boot-tool`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`proxmox-boot-tool` is a utility used to keep the contents of the EFI System
+Partitions properly configured and synchronized. It copies certain kernel
+versions to all ESPs and configures the respective bootloader to boot from
+the `vfat` formatted ESPs. In the context of ZFS as root filesystem this means
+that you can use all optional features on your root pool instead of the subset
+which is also present in the ZFS implementation in `grub` or having to create a
+separate small boot-pool footnote:[Booting ZFS on root with grub
+https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS].
+
+In setups with redundancy all disks are partitioned with an ESP, by the
+installer. This ensures the system boots even if the first boot device fails
+or if the BIOS can only boot from a particular disk.
+
+The ESPs are not kept mounted during regular operation. This helps to prevent
+filesystem corruption to the `vfat` formatted ESPs in case of a system crash,
+and removes the need to manually adapt `/etc/fstab` in case the primary boot
+device fails.
+
+`proxmox-boot-tool` handles the following tasks:
+
+* formatting and setting up a new partition
+* 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
+
+
+You can view the currently configured ESPs and their state by running:
+
+----
+# proxmox-boot-tool status
+----
+
+[[sysboot_proxmox_boot_setup]]
+.Setting up a new partition for use as synced ESP
+
+To format and initialize a partition as synced ESP, e.g., after replacing a
+failed vdev in an rpool, or when converting an existing system that pre-dates
+the sync mechanism, `proxmox-boot-tool` from `pve-kernel-helpers` can be used.
+
+WARNING: the `format` command will format the `<partition>`, make sure to pass
+in the right device/partition!
+
+For example, to format an empty partition `/dev/sda2` as ESP, run the following:
+
+----
+# proxmox-boot-tool format /dev/sda2
+----
+
+To setup an existing, unmounted ESP located on `/dev/sda2` for inclusion in
+{pve}'s kernel update synchronization mechanism, use the following:
+
+----
+# proxmox-boot-tool init /dev/sda2
+----
+
+Afterwards `/etc/kernel/proxmox-boot-uuids` should contain a new line with the
+UUID of the newly added partition. The `init` command will also automatically
+trigger a refresh of all configured ESPs.
+
+[[sysboot_proxmox_boot_refresh]]
+.Updating the configuration on all ESPs
+
+To copy and configure all bootable kernels and keep all ESPs listed in
+`/etc/kernel/proxmox-boot-uuids` in sync you just need to run:
+
+----
+# proxmox-boot-tool refresh
+----
+(The equivalent to running `update-grub` systems with `ext4` or `xfs` on root).
+
+This is necessary should you make changes to the kernel commandline, or want to
+sync all kernels and initrds.
+
+NOTE: Both `update-initramfs` and `apt` (when necessary) will automatically
+trigger a refresh.
+
+.Kernel Versions considered by `proxmox-boot-tool`
+The following kernel versions are configured by default:
+
+* the currently running kernel
+* the version being newly installed on package updates
+* the two latest already installed kernels
+* the latest version of the second-to-last kernel series (e.g. 5.0, 5.3), if applicable
+* any manually selected kernels
+
+.Manually keeping a kernel bootable
+
+Should you wish to add a certain kernel and initrd image to the list of
+bootable kernels use `proxmox-boot-tool kernel add`.
+
+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:
+
+----
+# proxmox-boot-tool kernel add 5.0.15-1-pve
+----
+
+`proxmox-boot-tool kernel list` will list all kernel versions currently selected
+for booting:
+
+----
+# proxmox-boot-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 `proxmox-boot-tool kernel remove` to remove a kernel from the list of
+manually selected kernels, for example:
+
+----
+# proxmox-boot-tool kernel remove 5.0.15-1-pve
+----
+
+NOTE: It's required to run `proxmox-boot-tool refresh` to update all EFI System
+Partitions (ESPs) after a manual kernel addition or removal from above.
[[sysboot_determine_bootloader_used]]
@@ -72,12 +197,21 @@ used in UEFI mode.
Boot0005* proxmox [...] File(\EFI\proxmox\grubx64.efi)
----
-If the output contains a line similar to the following, `systemd-bood` is used.
+If the output contains a line similar to the following, `systemd-boot` is used.
----
Boot0006* Linux Boot Manager [...] File(\EFI\systemd\systemd-bootx64.efi)
----
+By running:
+
+----
+# proxmox-boot-tool status
+----
+
+you can find out if `proxmox-boot-tool` is configured, which is a good
+indication of how the system is booted.
+
[[sysboot_grub]]
Grub
@@ -87,19 +221,19 @@ Grub
and is quite well documented
footnote:[Grub Manual https://www.gnu.org/software/grub/manual/grub/grub.html].
-The kernel and initrd images are taken from `/boot` and its configuration file
-`/boot/grub/grub.cfg` gets updated by the kernel installation process.
-
Configuration
^^^^^^^^^^^^^
Changes to the `grub` configuration are done via the defaults file
`/etc/default/grub` or config snippets in `/etc/default/grub.d`. To regenerate
-the `/boot/grub/grub.cfg` after a change to the configuration run:
+the configuration file after a change to the configuration run:
+footnote:[Systems using `proxmox-boot-tool` will call `proxmox-boot-tool
+refresh` upon `update-grub`.]
----
-`update-grub`.
+# update-grub
----
+
[[sysboot_systemd_boot]]
Systemd-boot
~~~~~~~~~~~~
@@ -107,33 +241,9 @@ Systemd-boot
`systemd-boot` is a lightweight EFI bootloader. It reads the kernel and initrd
images directly from the EFI Service Partition (ESP) where it is installed.
The main advantage of directly loading the kernel from the ESP is that it does
-not need to reimplement the drivers for accessing the storage. In the context
-of ZFS as root filesystem this means that you can use all optional features on
-your root pool instead of the subset which is also present in the ZFS
-implementation in `grub` or having to create a separate small boot-pool
-footnote:[Booting ZFS on root with grub https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS].
-
-In setups with redundancy (RAID1, RAID10, RAIDZ*) all bootable disks (those
-being part of the first `vdev`) are partitioned with an ESP. This ensures the
-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`. 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 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
-corruption to the `vfat` formatted ESPs in case of a system crash, and removes
-the need to manually adapt `/etc/fstab` in case the primary boot device fails.
+not need to reimplement the drivers for accessing the storage. In {pve}
+xref:sysboot_proxmox_boot_tool[`proxmox-boot-tool`] is used to keep the
+configuration on the ESPs synchronized.
[[sysboot_systemd_boot_config]]
Configuration
@@ -157,86 +267,6 @@ 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 use `pve-efiboot-tool kernel add`.
-
-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:
-
-----
-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
-----
-
-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
-
-To format and initialize a partition as synced ESP, e.g., after replacing a
-failed vdev in an rpool, or when converting an existing system that pre-dates
-the sync mechanism, `pve-efiboot-tool` from `pve-kernel-helpers` can be used.
-
-WARNING: the `format` command will format the `<partition>`, make sure to pass
-in the right device/partition!
-
-For example, to format an empty partition `/dev/sda2` as ESP, run the following:
-
-----
-pve-efiboot-tool format /dev/sda2
-----
-
-To setup an existing, unmounted ESP located on `/dev/sda2` for inclusion in
-{pve}'s kernel update synchronization mechanism, use the following:
-
-----
-pve-efiboot-tool init /dev/sda2
-----
-
-Afterwards `/etc/kernel/pve-efiboot-uuids` should contain a new line with the
-UUID of the newly added partition. The `init` command will also automatically
-trigger a refresh of all configured ESPs.
-
-[[sysboot_systemd_boot_refresh]]
-.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`).
-
-This is necessary should you make changes to the kernel commandline, or want to
-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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -254,5 +284,5 @@ The kernel commandline needs to be placed in the variable
.Systemd-boot
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
+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`.
--
2.20.1
More information about the pve-devel
mailing list