[pbs-devel] [PATCH proxmox-backup 2/5] docs: add system-booting from pve-docs

[Stoiko Ivanov <s.ivanov@proxmox.com>]

and transform to reST.

semantic changes to the content are:
* s/{pve}/`Proxmox Backup`_/g
* changing footnotes to parenthesized notes (did not see footnote use in
  the current docs)
* removed the comment about systems setup before the introduction of
  p-b-t (which was introduced before pbs)

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 docs/conf.py            |   1 +
 docs/sysadmin.rst       |   2 +
 docs/system-booting.rst | 370 ++++++++++++++++++++++++++++++++++++++++
 www/OnlineHelpInfo.js   |  44 +++++
 4 files changed, 417 insertions(+)
 create mode 100644 docs/system-booting.rst

diff --git a/docs/conf.py b/docs/conf.py
index dcc44988..2a189ba6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -113,6 +113,7 @@ exclude_patterns = [
     'pbs-copyright.rst',
     'local-zfs.rst'
     'package-repositories.rst',
+    'system-booting.rst'
 ]
 
 # The reST default role (used for this markup: `text`) to use for all
diff --git a/docs/sysadmin.rst b/docs/sysadmin.rst
index 7e843111..b156acc9 100644
--- a/docs/sysadmin.rst
+++ b/docs/sysadmin.rst
@@ -26,4 +26,6 @@ please refer to the standard Debian documentation.
 
 .. include:: local-zfs.rst
 
+.. include:: system-booting.rst
+
 .. include:: services.rst
diff --git a/docs/system-booting.rst b/docs/system-booting.rst
new file mode 100644
index 00000000..6d6ebaab
--- /dev/null
+++ b/docs/system-booting.rst
@@ -0,0 +1,370 @@
+
+.. _chapter-systembooting:
+
+Host Bootloader
+---------------
+
+`Proxmox Backup`_ currently uses one of two bootloaders depending on the disk setup
+selected in the installer.
+
+For EFI Systems installed with ZFS as the root filesystem ``systemd-boot`` is
+used. All other deployments use the standard ``grub`` bootloader (this usually
+also applies to systems which are installed on top of Debian).
+
+
+.. _systembooting-installer-part-scheme:
+
+Partitioning Scheme Used by the Installer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `Proxmox Backup`_ installer creates 3 partitions on all disks selected for
+installation.
+
+The created partitions are:
+
+* a 1 MB BIOS Boot Partition (gdisk type EF02)
+
+* a 512 MB EFI System Partition (ESP, gdisk type EF00)
+
+* 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 selected disks on all systems booted with ``grub`` (These are
+all installs with root on ``ext4`` or ``xfs`` and installs with root on ZFS on
+non-EFI systems).
+
+
+.. _systembooting-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 (see: `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
+* configuring the boot-loader to boot a particular kernel version (pinning)
+
+
+You can view the currently configured ESPs and their state by running:
+
+.. code-block:: console
+
+  # proxmox-boot-tool status
+
+.. _systembooting-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, ``proxmox-boot-tool`` from ``pve-kernel-helper`` 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:
+
+.. code-block:: console
+
+  # proxmox-boot-tool format /dev/sda2
+
+To setup an existing, unmounted ESP located on ``/dev/sda2`` for inclusion in
+`Proxmox Backup`_'s kernel update synchronization mechanism, use the following:
+
+.. code-block:: console
+
+  # 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.
+
+.. _systembooting-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:
+
+.. code-block:: console
+
+  # 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:
+
+.. code-block:: console
+
+  # proxmox-boot-tool kernel add 5.0.15-1-pve
+
+
+``proxmox-boot-tool kernel list`` will list all kernel versions currently selected
+for booting:
+
+.. code-block:: console
+
+  # 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:
+
+.. code-block:: console
+
+  # 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.
+
+
+.. _systembooting-determine-bootloader:
+
+Determine which Bootloader is Used
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+The simplest and most reliable way to determine which bootloader is used, is to
+watch the boot process of the `Proxmox Backup`_ node.
+
+You will either see the blue box of ``grub`` or the simple black on white
+``systemd-boot``.
+
+
+Determining the bootloader from a running system might not be 100% accurate. The
+safest way is to run the following command:
+
+
+.. code-block:: console
+
+  # efibootmgr -v
+
+
+If it returns a message that EFI variables are not supported, ``grub`` is used in
+BIOS/Legacy mode.
+
+If the output contains a line that looks similar to the following, ``grub`` is
+used in UEFI mode.
+
+.. code-block:: console
+
+  Boot0005* proxmox	[...] File(\EFI\proxmox\grubx64.efi)
+
+
+If the output contains a line similar to the following, ``systemd-boot`` is used.
+
+.. code-block:: console
+
+  Boot0006* Linux Boot Manager	[...] File(\EFI\systemd\systemd-bootx64.efi)
+
+
+By running:
+
+.. code-block:: console
+
+  # 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.
+
+
+.. _systembooting-grub:
+
+Grub
+~~~~
+
+``grub`` has been the de-facto standard for booting Linux systems for many years
+and is quite well documented
+(see the `Grub Manual
+<https://www.gnu.org/software/grub/manual/grub/grub.html>`_).
+
+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 configuration file after a change to the configuration run:
+
+.. code-block:: console
+
+  # update-grub
+
+.. NOTE:: Systems using ``proxmox-boot-tool`` will call
+  ``proxmox-boot-tool refresh`` upon ``update-grub``
+
+.. _systembooting-systemdboot:
+
+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 `Proxmox
+Backup`_ :ref:`proxmox-boot-tool <systembooting-proxmox-boot-tool>` is used to
+keep the configuration on the ESPs synchronized.
+
+.. _systembooting-systemd-boot-config:
+
+Configuration
+^^^^^^^^^^^^^
+
+``systemd-boot`` is configured via the file ``loader/loader.conf`` in the root
+directory of an EFI System Partition (ESP). See the ``loader.conf(5)`` manpage
+for details.
+
+Each bootloader entry is placed in a file of its own in the directory
+``loader/entries/``
+
+An example entry.conf looks like this (``/`` refers to the root of the ESP):
+
+.. code-block:: console
+
+  title    Proxmox
+  version  5.0.15-1-pve
+  options   root=ZFS=rpool/ROOT/pve-1 boot=zfs
+  linux    /EFI/proxmox/5.0.15-1-pve/vmlinuz-5.0.15-1-pve
+  initrd   /EFI/proxmox/5.0.15-1-pve/initrd.img-5.0.15-1-pve
+
+
+.. _systembooting-edit-kernel-cmdline:
+
+Editing the Kernel Commandline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can modify the kernel commandline in the following places, depending on the
+bootloader used:
+
+Grub
+^^^^
+
+The kernel commandline needs to be placed in the variable
+``GRUB_CMDLINE_LINUX_DEFAULT`` in the file ``/etc/default/grub``. Running
+``update-grub`` appends its content to all ``linux`` entries in
+``/boot/grub/grub.cfg``.
+
+Systemd-boot
+^^^^^^^^^^^^
+
+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``.
+
+
+.. _systembooting-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:
+
+.. code-block:: console
+
+  # proxmox-boot-tool kernel pin 5.15.30-1-pve
+
+
+.. TIP:: The pinning functionality works for all `Proxmox Backup`_ 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:
+
+.. code-block:: console
+
+  # proxmox-boot-tool kernel pin 5.15.30-1-pve --next-boot
+
+
+To remove any pinned version configuration use the ``unpin`` subcommand:
+
+.. code-block:: console
+
+  # 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.
+
+.. code-block:: console
+
+  # proxmox-boot-tool refresh
diff --git a/www/OnlineHelpInfo.js b/www/OnlineHelpInfo.js
index 0510df21..c982e7dd 100644
--- a/www/OnlineHelpInfo.js
+++ b/www/OnlineHelpInfo.js
@@ -147,6 +147,50 @@ const proxmoxOnlineHelpInfo = {
     "link": "/docs/sysadmin.html#sysadmin-host-administration",
     "title": "Host System Administration"
   },
+  "chapter-systembooting": {
+    "link": "/docs/sysadmin.html#chapter-systembooting",
+    "title": "Host Bootloader"
+  },
+  "systembooting-installer-part-scheme": {
+    "link": "/docs/sysadmin.html#systembooting-installer-part-scheme",
+    "title": "Partitioning Scheme Used by the Installer"
+  },
+  "systembooting-proxmox-boot-tool": {
+    "link": "/docs/sysadmin.html#systembooting-proxmox-boot-tool",
+    "title": "Synchronizing the content of the ESP with ``proxmox-boot-tool``"
+  },
+  "systembooting-proxmox-boot-setup": {
+    "link": "/docs/sysadmin.html#systembooting-proxmox-boot-setup",
+    "title": "Setting up a new partition for use as synced ESP"
+  },
+  "systembooting-proxmox-boot-refresh": {
+    "link": "/docs/sysadmin.html#systembooting-proxmox-boot-refresh",
+    "title": "Updating the configuration on all ESPs"
+  },
+  "systembooting-determine-bootloader": {
+    "link": "/docs/sysadmin.html#systembooting-determine-bootloader",
+    "title": "Determine which Bootloader is Used"
+  },
+  "systembooting-grub": {
+    "link": "/docs/sysadmin.html#systembooting-grub",
+    "title": "Grub"
+  },
+  "systembooting-systemdboot": {
+    "link": "/docs/sysadmin.html#systembooting-systemdboot",
+    "title": "Systemd-boot"
+  },
+  "systembooting-systemd-boot-config": {
+    "link": "/docs/sysadmin.html#systembooting-systemd-boot-config",
+    "title": "Configuration"
+  },
+  "systembooting-edit-kernel-cmdline": {
+    "link": "/docs/sysadmin.html#systembooting-edit-kernel-cmdline",
+    "title": "Editing the Kernel Commandline"
+  },
+  "systembooting-kernel-pin": {
+    "link": "/docs/sysadmin.html#systembooting-kernel-pin",
+    "title": "Override the Kernel-Version for next Boot"
+  },
   "tape-backup": {
     "link": "/docs/tape-backup.html#tape-backup",
     "title": "Tape Backup"
-- 
2.30.2