docs: add system-booting from pve-docs
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>
This commit is contained in:
Stoiko Ivanov
Thomas Lamprecht
parent
6e3391c85b
commit
9eb804006c
|
|
@ -113,6 +113,7 @@ exclude_patterns = [
|
||||||
'pbs-copyright.rst',
|
'pbs-copyright.rst',
|
||||||
'local-zfs.rst'
|
'local-zfs.rst'
|
||||||
'package-repositories.rst',
|
'package-repositories.rst',
|
||||||
|
'system-booting.rst'
|
||||||
]
|
]
|
||||||
|
|
||||||
# The reST default role (used for this markup: `text`) to use for all
|
# The reST default role (used for this markup: `text`) to use for all
|
||||||
|
|
|
||||||
|
|
@ -26,4 +26,6 @@ please refer to the standard Debian documentation.
|
||||||
|
|
||||||
.. include:: local-zfs.rst
|
.. include:: local-zfs.rst
|
||||||
|
|
||||||
|
.. include:: system-booting.rst
|
||||||
|
|
||||||
.. include:: services.rst
|
.. include:: services.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
|
||||||
|
|
@ -147,6 +147,50 @@ const proxmoxOnlineHelpInfo = {
|
||||||
"link": "/docs/sysadmin.html#sysadmin-host-administration",
|
"link": "/docs/sysadmin.html#sysadmin-host-administration",
|
||||||
"title": "Host System 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": {
|
"tape-backup": {
|
||||||
"link": "/docs/tape-backup.html#tape-backup",
|
"link": "/docs/tape-backup.html#tape-backup",
|
||||||
"title": "Tape Backup"
|
"title": "Tape Backup"
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue