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 +`_). + +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 ````, 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 +`_). + +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 ` 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"