mirror of
https://git.proxmox.com/git/proxmox-backup
synced 2025-08-15 14:04:37 +00:00
docs: language fixup
This fixup covers every doc patch since my previous language fixup patch. Note: not much attention was paid to certificate-management, as it's derived from pmg, which I had touched up not so long ago. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
This commit is contained in:
parent
7c1029d760
commit
6481fd2498
@ -153,7 +153,7 @@ you want to back up two disks mounted at ``/mnt/disk1`` and ``/mnt/disk2``:
|
||||
|
||||
This creates a backup of both disks.
|
||||
|
||||
If you want to use a namespace for the backup target you can add the `--ns`
|
||||
If you want to use a namespace for the backup target, you can add the `--ns`
|
||||
parameter:
|
||||
|
||||
.. code-block:: console
|
||||
@ -696,17 +696,17 @@ It is also possible to protect single snapshots from being pruned or deleted:
|
||||
# proxmox-backup-client snapshot protected update <snapshot> true
|
||||
|
||||
This will set the protected flag on the snapshot and prevent pruning or manual
|
||||
deletion of this snapshot untilt he flag is removed again with:
|
||||
deletion of this snapshot until the flag is removed again with:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# proxmox-backup-client snapshot protected update <snapshot> false
|
||||
|
||||
When a group is with a protected snapshot is deleted, only the non-protected
|
||||
ones are removed and the group will remain.
|
||||
When a group with a protected snapshot is deleted, only the non-protected
|
||||
ones are removed, and the rest will remain.
|
||||
|
||||
.. note:: This flag will not be synced when using pull or sync jobs. If you
|
||||
want to protect a synced snapshot, you have to manually to this again on
|
||||
want to protect a synced snapshot, you have to do this again manually on
|
||||
the target backup server.
|
||||
|
||||
.. _client_garbage-collection:
|
||||
|
@ -18,7 +18,7 @@ configuration, or by using certificates, signed by a trusted certificate authori
|
||||
Certificates for the API and SMTP
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`Proxmox Backup`_ stores it certificate and key in:
|
||||
`Proxmox Backup`_ stores its certificate and key in:
|
||||
|
||||
- ``/etc/proxmox-backup/proxy.pem``
|
||||
|
||||
|
@ -74,7 +74,7 @@ project = 'Proxmox Backup'
|
||||
copyright = '2019-2022, Proxmox Server Solutions GmbH'
|
||||
author = 'Proxmox Support Team'
|
||||
|
||||
# The version info for the project you're documenting, acts as a replacement for
|
||||
# The version info for the project you're documenting acts as a replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
|
@ -211,13 +211,13 @@ Usually `grub.cfg` is located in `/boot/grub/grub.cfg`
|
||||
Activate e-mail notification
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ZFS comes with an event daemon ``ZED``, which monitors events generated by the
|
||||
ZFS kernel module. The daemon can also send emails on ZFS events like pool
|
||||
ZFS comes with an event daemon, ``ZED``, which monitors events generated by the
|
||||
ZFS kernel module. The daemon can also send emails upon ZFS events, such as pool
|
||||
errors. Newer ZFS packages ship the daemon in a separate package ``zfs-zed``,
|
||||
which should already be installed by default in `Proxmox Backup`_.
|
||||
|
||||
You can configure the daemon via the file ``/etc/zfs/zed.d/zed.rc`` with your
|
||||
favorite editor. The required setting for email notification is
|
||||
You can configure the daemon via the file ``/etc/zfs/zed.d/zed.rc``, using your
|
||||
preferred editor. The required setting for email notfication is
|
||||
``ZED_EMAIL_ADDR``, which is set to ``root`` by default.
|
||||
|
||||
.. code-block:: console
|
||||
|
@ -192,8 +192,8 @@ following options are available:
|
||||
Maintenance Mode
|
||||
----------------
|
||||
|
||||
Proxmox Backup Server implements setting the `read-only` and `offline`
|
||||
maintenance modes for a datastore.
|
||||
Proxmox Backup Server supports setting `read-only` and `offline`
|
||||
maintenance modes on a datastore.
|
||||
|
||||
Once enabled, depending on the mode, new reads and/or writes to the datastore
|
||||
are blocked, allowing an administrator to safely execute maintenance tasks, for
|
||||
|
@ -98,19 +98,20 @@ the local datastore as well. If the ``owner`` option is not set (defaulting to
|
||||
If the ``group-filter`` option is set, only backup groups matching at least one
|
||||
of the specified criteria are synced. The available criteria are:
|
||||
|
||||
* backup type, for example to only sync groups of the `ct` (Container) type:
|
||||
* Backup type, for example, to only sync groups of the `ct` (Container) type:
|
||||
.. code-block:: console
|
||||
|
||||
# proxmox-backup-manager sync-job update ID --group-filter type:ct
|
||||
* full group identifier
|
||||
* Full group identifier, to sync a specific backup group:
|
||||
.. code-block:: console
|
||||
|
||||
# proxmox-backup-manager sync-job update ID --group-filter group:vm/100
|
||||
* regular expression matched against the full group identifier
|
||||
* Regular expression, matched against the full group identifier
|
||||
.. code-block:: console
|
||||
|
||||
.. todo:: add example for regex
|
||||
# proxmox-backup-manager sync-job update ID --group-filter regex:'^vm/1\d{2,3}$'
|
||||
|
||||
The same filter is applied to local groups for handling of the
|
||||
The same filter is applied to local groups, for handling of the
|
||||
``remove-vanished`` option.
|
||||
|
||||
.. note:: The ``protected`` flag of remote backup snapshots will not be synced.
|
||||
@ -118,9 +119,9 @@ The same filter is applied to local groups for handling of the
|
||||
Namespace Support
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sync jobs can be configured to not only sync datastores, but also sub-sets of
|
||||
Sync jobs can be configured to not only sync datastores, but also subsets of
|
||||
datastores in the form of namespaces or namespace sub-trees. The following
|
||||
parameters influence how namespaces are treated as part of a sync job
|
||||
parameters influence how namespaces are treated as part of a sync job's
|
||||
execution:
|
||||
|
||||
- ``remote-ns``: the remote namespace anchor (default: the root namespace)
|
||||
@ -199,10 +200,10 @@ sync job scope but only exist locally are treated as vanished and removed
|
||||
Bandwidth Limit
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Syncing a datastore to an archive can produce lots of traffic and impact other
|
||||
users of the network. So, to avoid network or storage congestion you can limit
|
||||
the bandwidth of the sync job by setting the ``rate-in`` option either in the
|
||||
web interface or using the ``proxmox-backup-manager`` command-line tool:
|
||||
Syncing a datastore to an archive can produce a lot of traffic and impact other
|
||||
users of the network. In order to avoid network or storage congestion, you can
|
||||
limit the bandwidth of the sync job by setting the ``rate-in`` option either in
|
||||
the web interface or using the ``proxmox-backup-manager`` command-line tool:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
@ -10,18 +10,18 @@ Markdown Primer
|
||||
-- John Gruber, https://daringfireball.net/projects/markdown/
|
||||
|
||||
|
||||
The Proxmox Backup Server (PBS) web-interface has support for using Markdown to
|
||||
rendering rich text formatting in node and virtual guest notes.
|
||||
The "Notes" panel of the Proxmox Backup Server web-interface supports
|
||||
rendering Markdown text.
|
||||
|
||||
PBS supports CommonMark with most extensions of GFM (GitHub Flavoured Markdown),
|
||||
like tables or task-lists.
|
||||
Proxmox Backup Server supports CommonMark with most extensions of GFM (GitHub
|
||||
Flavoured Markdown), like tables or task-lists.
|
||||
|
||||
.. _markdown_basics:
|
||||
|
||||
Markdown Basics
|
||||
---------------
|
||||
|
||||
Note that we only describe the basics here, please search the web for more
|
||||
Note that we only describe the basics here. Please search the web for more
|
||||
extensive resources, for example on https://www.markdownguide.org/
|
||||
|
||||
Headings
|
||||
@ -51,7 +51,7 @@ Combinations are also possible, for example:
|
||||
Links
|
||||
~~~~~
|
||||
|
||||
You can use automatic detection of links, for example,
|
||||
You can use automatic detection of links. For example,
|
||||
``https://forum.proxmox.com/`` would transform it into a clickable link.
|
||||
|
||||
You can also control the link text, for example:
|
||||
@ -76,7 +76,7 @@ Use ``*`` or ``-`` for unordered lists, for example:
|
||||
* Item 2b
|
||||
|
||||
|
||||
Adding an indentation can be used to created nested lists.
|
||||
You can create nested lists by adding indentation.
|
||||
|
||||
Ordered Lists
|
||||
^^^^^^^^^^^^^
|
||||
@ -94,7 +94,7 @@ NOTE: The integer of ordered lists does not need to be correct, they will be num
|
||||
Task Lists
|
||||
^^^^^^^^^^
|
||||
|
||||
Task list use a empty box ``[ ]`` for unfinished tasks and a box with an `X` for finished tasks.
|
||||
Task lists use a empty box ``[ ]`` for unfinished tasks and a box with an `X` for finished tasks.
|
||||
|
||||
For example:
|
||||
|
||||
@ -110,7 +110,7 @@ Tables
|
||||
~~~~~~
|
||||
|
||||
Tables use the pipe symbol ``|`` to separate columns, and ``-`` to separate the
|
||||
table header from the table body, in that separation one can also set the text
|
||||
table header from the table body. In that separation, you can also set the text
|
||||
alignment, making one column left-, center-, or right-aligned.
|
||||
|
||||
|
||||
@ -143,23 +143,24 @@ You can enter block quotes by prefixing a line with ``>``, similar as in plain-t
|
||||
Code and Snippets
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can use backticks to avoid processing for a few word or paragraphs. That is useful for
|
||||
avoiding that a code or configuration hunk gets mistakenly interpreted as markdown.
|
||||
You can use backticks to avoid processing a group of words or paragraphs. This
|
||||
is useful for preventing a code or configuration hunk from being mistakenly
|
||||
interpreted as markdown.
|
||||
|
||||
Inline code
|
||||
Inline Code
|
||||
^^^^^^^^^^^
|
||||
|
||||
Surrounding part of a line with single backticks allows to write code inline,
|
||||
for examples:
|
||||
Surrounding part of a line with single backticks allows you to write code
|
||||
inline, for examples:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
This hosts IP address is `10.0.0.1`.
|
||||
|
||||
Whole blocks of code
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
Entire Blocks of Code
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For code blocks spanning several lines you can use triple-backticks to start
|
||||
For code blocks spanning several lines, you can use triple-backticks to start
|
||||
and end such a block, for example:
|
||||
|
||||
.. code-block:: md
|
||||
|
@ -261,44 +261,44 @@ categorized by checksum, after a backup operation has been executed.
|
||||
276490 drwxr-x--- 1 backup backup 1.1M Jul 8 12:35 .
|
||||
|
||||
|
||||
Once you uploaded some backups, or created namespaces, you may see the Backup
|
||||
Type (`ct`, `vm`, `host`) and the start of the namespace hierarchy (`ns`).
|
||||
Once you've uploaded some backups or created namespaces, you may see the backup
|
||||
type (`ct`, `vm`, `host`) and the start of the namespace hierachy (`ns`).
|
||||
|
||||
.. _storage_namespaces:
|
||||
|
||||
Backup Namespaces
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
A datastore can host many backups as long as the underlying storage is big
|
||||
enough and provides the performance required for one's use case.
|
||||
But, without any hierarchy or separation its easy to run into naming conflicts,
|
||||
A datastore can host many backups, as long as the underlying storage is large
|
||||
enough and provides the performance required for a user's use case.
|
||||
However, without any hierarchy or separation, it's easy to run into naming conflicts,
|
||||
especially when using the same datastore for multiple Proxmox VE instances or
|
||||
multiple users.
|
||||
|
||||
The backup namespace hierarchy allows you to clearly separate different users
|
||||
or backup sources in general, avoiding naming conflicts and providing
|
||||
or backup sources in general, avoiding naming conflicts and providing a
|
||||
well-organized backup content view.
|
||||
|
||||
Each namespace level can host any backup type, CT, VM or Host but also other
|
||||
namespaces, up to a depth of 8 level, where the root namespace is the first
|
||||
Each namespace level can host any backup type, CT, VM or Host, but also other
|
||||
namespaces, up to a depth of 8 levels, where the root namespace is the first
|
||||
level.
|
||||
|
||||
|
||||
Namespace Permissions
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can make the permission configuration of a datastore more fine-grained by
|
||||
setting permissions only on a specific namespace.
|
||||
|
||||
To see a datastore you need permission that has at least one of `AUDIT`,
|
||||
To view a datastore, you need a permission that has at least an `AUDIT`,
|
||||
`MODIFY`, `READ` or `BACKUP` privilege on any namespace it contains.
|
||||
|
||||
To create or delete a namespace you require the modify privilege on the parent
|
||||
namespace. So, to initially create namespaces you need to have a permission
|
||||
with a access role that includes the `MODIFY` privilege on the datastore itself.
|
||||
To create or delete a namespace, you require the modify privilege on the parent
|
||||
namespace. Thus, to initially create namespaces, you need to have a permission
|
||||
with an access role that includes the `MODIFY` privilege on the datastore itself.
|
||||
|
||||
For backup groups the existing privilege rules still apply, you either need a
|
||||
powerful permission or be the owner of the backup group, nothing changed here.
|
||||
For backup groups, the existing privilege rules still apply. You either need a
|
||||
privileged enough permission or to be the owner of the backup group; nothing
|
||||
changed here.
|
||||
|
||||
.. todo:: continue
|
||||
|
||||
|
@ -16,7 +16,7 @@ repository to roll out all Proxmox related packages. This includes
|
||||
updates to some Debian packages when necessary.
|
||||
|
||||
We also deliver a specially optimized Linux kernel, based on the Ubuntu
|
||||
kernel. That kernel includes drivers for ZFS_.
|
||||
kernel. This kernel includes drivers for ZFS_.
|
||||
|
||||
The following sections will concentrate on backup related topics. They
|
||||
will explain things which are different on `Proxmox Backup`_, or
|
||||
|
@ -4,7 +4,7 @@
|
||||
Host Bootloader
|
||||
---------------
|
||||
|
||||
`Proxmox Backup`_ currently uses one of two bootloaders depending on the disk setup
|
||||
`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
|
||||
@ -22,54 +22,54 @@ installation.
|
||||
|
||||
The created partitions are:
|
||||
|
||||
* a 1 MB BIOS Boot Partition (gdisk type EF02)
|
||||
* A 1 MB BIOS Boot Partition (gdisk type EF02)
|
||||
|
||||
* a 512 MB EFI System Partition (ESP, gdisk type EF00)
|
||||
* 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
|
||||
* A third partition spanning the configured ``hdsize`` parameter or the
|
||||
remaining space available for the chosen storage type
|
||||
|
||||
Systems using ZFS as root filesystem are booted with a kernel and initrd image
|
||||
Systems using ZFS as a 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
|
||||
Partition of all selected disks on all systems booted with ``grub`` (that is,
|
||||
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``
|
||||
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
|
||||
the ``vfat`` formatted ESPs. In the context of ZFS as root filesystem, this means
|
||||
that you can use all the 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
|
||||
small, separate 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
|
||||
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,
|
||||
filesystem corruption in 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)
|
||||
* 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:
|
||||
@ -80,13 +80,13 @@ You can view the currently configured ESPs and their state by running:
|
||||
|
||||
.. _systembooting-proxmox-boot-setup:
|
||||
|
||||
Setting up a new partition for use as synced ESP
|
||||
Setting up a New Partition for use as Synced ESP
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To format and initialize a partition as synced ESP, e.g., after replacing a
|
||||
To format and initialize a partition as synced ESP, for example, 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
|
||||
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:
|
||||
@ -102,48 +102,48 @@ To setup an existing, unmounted ESP located on ``/dev/sda2`` for inclusion in
|
||||
|
||||
# proxmox-boot-tool init /dev/sda2
|
||||
|
||||
Afterwards `/etc/kernel/proxmox-boot-uuids`` should contain a new line with the
|
||||
Following this, `/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
|
||||
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:
|
||||
``/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).
|
||||
(Equivalent to running ``update-grub`` on 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.
|
||||
This is necessary after making changes to the kernel commandline, or if you 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``
|
||||
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
|
||||
* 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
|
||||
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``.
|
||||
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``
|
||||
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
|
||||
@ -199,7 +199,7 @@ You will either see the blue box of ``grub`` or the simple black on white
|
||||
:alt: systemd-boot screen
|
||||
|
||||
Determining the bootloader from a running system might not be 100% accurate. The
|
||||
safest way is to run the following command:
|
||||
most reliable way is to run the following command:
|
||||
|
||||
|
||||
.. code-block:: console
|
||||
@ -225,32 +225,30 @@ 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:
|
||||
By running the following command, you can find out if ``proxmox-boot-tool`` is
|
||||
configured, which is a good indication of how the system is booted:
|
||||
|
||||
.. 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
|
||||
``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:
|
||||
``/etc/default/grub`` or via config snippets in ``/etc/default/grub.d``. To
|
||||
regenerate the configuration file after a change to the configuration, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -268,7 +266,7 @@ Systemd-boot
|
||||
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
|
||||
Backup`_, :ref:`proxmox-boot-tool <systembooting-proxmox-boot-tool>` is used to
|
||||
keep the configuration on the ESPs synchronized.
|
||||
|
||||
.. _systembooting-systemd-boot-config:
|
||||
@ -280,7 +278,7 @@ Configuration
|
||||
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
|
||||
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):
|
||||
@ -310,7 +308,7 @@ The kernel commandline needs to be placed in the variable
|
||||
``update-grub`` appends its content to all ``linux`` entries in
|
||||
``/boot/grub/grub.cfg``.
|
||||
|
||||
Systemd-boot
|
||||
systemd-boot
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The kernel commandline needs to be placed as one line in ``/etc/kernel/cmdline``.
|
||||
@ -325,18 +323,18 @@ 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
|
||||
* 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
|
||||
* 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.
|
||||
.. NOTE:: Such a pin should be removed as soon as possible, so that all recent
|
||||
security patches from the latest kernel are also applied to the system.
|
||||
|
||||
For example: To permanently select the version ``5.15.30-1-pve`` for booting you
|
||||
For example, to permanently select the version ``5.15.30-1-pve`` for booting, you
|
||||
would run:
|
||||
|
||||
.. code-block:: console
|
||||
@ -346,11 +344,11 @@ would run:
|
||||
|
||||
.. 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
|
||||
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,
|
||||
This is useful, for example, to test if an updated kernel has resolved an issue,
|
||||
which caused you to ``pin`` a version in the first place:
|
||||
|
||||
.. code-block:: console
|
||||
@ -358,7 +356,7 @@ which caused you to ``pin`` a version in the first place:
|
||||
# proxmox-boot-tool kernel pin 5.15.30-1-pve --next-boot
|
||||
|
||||
|
||||
To remove any pinned version configuration use the ``unpin`` subcommand:
|
||||
To remove any pinned version configuration, use the ``unpin`` subcommand:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -366,9 +364,9 @@ To remove any pinned version configuration use the ``unpin`` subcommand:
|
||||
|
||||
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.
|
||||
invoking it manually is of little use.
|
||||
|
||||
After setting, or clearing pinned versions you also need to synchronize the
|
||||
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
|
||||
|
@ -521,7 +521,7 @@ a single media pool, so a job only uses tapes from that pool.
|
||||
|
||||
.. NOTE:: Retention period starts on the creation time of the next
|
||||
media-set or, if that does not exist, when the calendar event
|
||||
triggers the next time after the current media-set start time.
|
||||
next triggers after the current media-set start time.
|
||||
|
||||
Additionally, the following events may allocate a new media set:
|
||||
|
||||
@ -809,13 +809,13 @@ The following options are available:
|
||||
|
||||
--ns The namespace to backup.
|
||||
|
||||
If you only want to backup a specific namespace. If omitted, the root
|
||||
namespaces is assumed.
|
||||
Used if you only want to backup a specific namespace. If omitted, the root
|
||||
namespace is assumed.
|
||||
|
||||
--max-depth The depth to recurse namespaces.
|
||||
|
||||
``0`` means no recursion at all (only the given namespace). If omitted,
|
||||
all namespaces are recursed (below the the given one).
|
||||
all namespaces are recursed (below the given one).
|
||||
|
||||
|
||||
Restore from Tape
|
||||
@ -854,7 +854,7 @@ data disk (datastore):
|
||||
Single Snapshot Restore
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes it is not necessary to restore a whole media-set, but only some
|
||||
Sometimes it is not necessary to restore an entire media-set, but only some
|
||||
specific snapshots from the tape. This can be achieved with the ``snapshots``
|
||||
parameter:
|
||||
|
||||
@ -868,7 +868,7 @@ parameter:
|
||||
This first restores the snapshot to a temporary location, then restores the relevant
|
||||
chunk archives, and finally restores the snapshot data to the target datastore.
|
||||
|
||||
The ``snapshot`` parameter can be given multiple times, so one can restore
|
||||
The ``snapshot`` parameter can be passed multiple times, in order to restore
|
||||
multiple snapshots with one restore action.
|
||||
|
||||
.. NOTE:: When using the single snapshot restore, the tape must be traversed
|
||||
@ -880,7 +880,7 @@ Namespaces
|
||||
|
||||
It is also possible to select and map specific namespaces from a media-set
|
||||
during a restore. This is possible with the ``namespaces`` parameter.
|
||||
The format of the parameter is
|
||||
The format for the parameter is:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -1043,7 +1043,7 @@ This command does the following:
|
||||
Example Setups
|
||||
--------------
|
||||
|
||||
Here are a few example setups for how to manage media pools and schedules.
|
||||
Here are a few example setups for managing media pools and schedules.
|
||||
This is not an exhaustive list, and there are many more possible combinations
|
||||
of useful settings.
|
||||
|
||||
@ -1058,14 +1058,14 @@ Allocation policy:
|
||||
Retention policy:
|
||||
keep
|
||||
|
||||
This setup has the advantage of being easy to manage and is re-using the benefits
|
||||
from deduplication as much as possible. But, it's also prone to a failure of
|
||||
any single tape, which would render all backups referring to chunks from that
|
||||
tape unusable.
|
||||
This setup has the advantage of being easy to manage and reuses the benefits
|
||||
from deduplication as much as possible. But, it also provides no redundancy,
|
||||
meaning a failure of any single tape would render all backups referring to
|
||||
chunks from that tape unusable.
|
||||
|
||||
If you want to start a new media-set manually, you can set the currently
|
||||
writable media of the set either to 'full', or set the location to an
|
||||
offsite vault.
|
||||
off-site vault.
|
||||
|
||||
Weekday Scheme
|
||||
~~~~~~~~~~~~~~
|
||||
@ -1081,14 +1081,14 @@ Allocation policy:
|
||||
Retention policy:
|
||||
overwrite
|
||||
|
||||
There should be a (or more) tape-backup jobs for each pool on the corresponding
|
||||
There should be one or more tape-backup jobs for each pool on the corresponding
|
||||
weekday. This scheme is still very manageable with one media set per weekday,
|
||||
and could be easily moved off-site.
|
||||
and could be moved off-site easily.
|
||||
|
||||
Multiple Pools with Different Policies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Complex setups are also possible with multiple media pools configured with
|
||||
Complex setups are also possible, with multiple media pools configured with
|
||||
different allocation and retention policies.
|
||||
|
||||
An example would be to have two media pools. The first configured with weekly
|
||||
@ -1100,7 +1100,7 @@ Allocation policy:
|
||||
Retention policy:
|
||||
3 weeks
|
||||
|
||||
The second pool configured yearly allocation that does not expire:
|
||||
The second pool configured with yearly allocation that does not expire:
|
||||
|
||||
Allocation policy:
|
||||
yearly
|
||||
@ -1108,7 +1108,7 @@ Allocation policy:
|
||||
Retention policy:
|
||||
keep
|
||||
|
||||
In combination with suited prune settings and tape backup schedules, this
|
||||
achieves long-term storage of some backups, while keeping the current
|
||||
backups on smaller media sets that get expired every three plus the current
|
||||
week (~ 4 weeks).
|
||||
In combination with fitting prune settings and tape backup schedules, this
|
||||
achieves long-term storage of some backups, while keeping the recent
|
||||
backups on smaller media sets that expire roughly every 4 weeks (that is, three
|
||||
plus the current week).
|
||||
|
@ -65,11 +65,11 @@ Backup Namespace
|
||||
----------------
|
||||
|
||||
Namespaces allow for the reuse of a single chunk store deduplication domain for
|
||||
multiple sources, while avoiding naming conflicts and getting more fine-grained
|
||||
multiple sources, while avoiding naming conflicts and enabling more fine-grained
|
||||
access control.
|
||||
|
||||
Essentially they're implemented as simple directory structure and need no
|
||||
separate configuration.
|
||||
Essentially, they're implemented as a simple directory structure and don't
|
||||
require separate configuration.
|
||||
|
||||
Backup Type
|
||||
-----------
|
||||
|
@ -7,21 +7,21 @@ Traffic Control
|
||||
:align: right
|
||||
:alt: Add a traffic control limit
|
||||
|
||||
Creating and restoring backups can produce lots of traffic and impact other
|
||||
users of the network or shared storages.
|
||||
Creating and restoring backups can produce a lot of traffic, can impact shared
|
||||
storage and other users on the network.
|
||||
|
||||
Proxmox Backup Server allows to limit network traffic for clients within
|
||||
With Proxmox Backup Server, you can constrain network traffic for clients within
|
||||
specified networks using a token bucket filter (TBF).
|
||||
|
||||
This allows you to avoid network congestion or to prioritize traffic from
|
||||
This allows you to avoid network congestion and prioritize traffic from
|
||||
certain hosts.
|
||||
|
||||
You can manage the traffic controls either over the web-interface or using the
|
||||
``traffic-control`` commandos of the ``proxmox-backup-manager`` command-line
|
||||
You can manage the traffic controls either via the web-interface or using the
|
||||
``traffic-control`` commands of the ``proxmox-backup-manager`` command-line
|
||||
tool.
|
||||
|
||||
.. note:: Sync jobs on the server are not affected by its rate-in limits. If
|
||||
you want to limit the incoming traffic that a pull-based sync job
|
||||
.. note:: Sync jobs on the server are not affected by the configured rate-in limits.
|
||||
If you want to limit the incoming traffic that a pull-based sync job
|
||||
generates, you need to setup a job-specific rate-in limit. See
|
||||
:ref:`syncjobs`.
|
||||
|
||||
@ -34,11 +34,11 @@ The following command adds a traffic control rule to limit all IPv4 clients
|
||||
--rate-in 100MB --rate-out 100MB \
|
||||
--comment "Default rate limit (100MB/s) for all clients"
|
||||
|
||||
.. note:: To limit both IPv4 and IPv6 network spaces you need to pass two
|
||||
.. note:: To limit both IPv4 and IPv6 network spaces, you need to pass two
|
||||
network parameters ``::/0`` and ``0.0.0.0/0``.
|
||||
|
||||
It is possible to restrict rules to certain time frames, for example the
|
||||
company office hours:
|
||||
company's office hours:
|
||||
|
||||
.. tip:: You can use SI (base 10: KB, MB, ...) or IEC (base 2: KiB, MiB, ...)
|
||||
units.
|
||||
@ -49,9 +49,9 @@ company office hours:
|
||||
--timeframe "mon..fri 8-12" \
|
||||
--timeframe "mon..fri 14:30-18"
|
||||
|
||||
If there are more rules, the server uses the rule with the smaller network. For
|
||||
example, we can overwrite the setting for our private network (and the server
|
||||
itself) with:
|
||||
If there are multiple rules, the server chooses the one with the smaller
|
||||
network. For example, we can overwrite the setting for our private network (and
|
||||
the server itself) with:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -63,11 +63,11 @@ itself) with:
|
||||
|
||||
.. note:: The behavior is undefined if there are several rules for the same network.
|
||||
|
||||
If there are multiple rules that match the same network all of them will be
|
||||
If there are multiple rules which match a specific network, they will all be
|
||||
applied, which means that the smallest one wins, as it's bucket fills up the
|
||||
fastest.
|
||||
|
||||
To list the current rules use:
|
||||
To list the current rules, use:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
@ -159,7 +159,7 @@ Access Control
|
||||
By default, new users and API tokens do not have any permissions. Instead you
|
||||
need to specify what is allowed and what is not.
|
||||
|
||||
Proxmox Backup Server uses a role and path based permission management system.
|
||||
Proxmox Backup Server uses a role- and path-based permission management system.
|
||||
An entry in the permissions table allows a user, group or token to take on a
|
||||
specific role when accessing an 'object' or 'path'. This means that such an
|
||||
access rule can be represented as a triple of '(path, user, role)', '(path,
|
||||
@ -169,92 +169,92 @@ allowed actions, and the path representing the target of these actions.
|
||||
Privileges
|
||||
~~~~~~~~~~
|
||||
|
||||
Privileges are the atoms that access roles are made off. They are internally
|
||||
Privileges are the building blocks of access roles. They are internally
|
||||
used to enforce the actual permission checks in the API.
|
||||
|
||||
We currently support the following privileges:
|
||||
|
||||
**Sys.Audit**
|
||||
Sys.Audit allows one to know about the system and its status.
|
||||
Sys.Audit allows a user to know about the system and its status.
|
||||
|
||||
**Sys.Modify**
|
||||
Sys.Modify allows one to modify system-level configuration and apply updates.
|
||||
Sys.Modify allows a user to modify system-level configuration and apply updates.
|
||||
|
||||
**Sys.PowerManagement**
|
||||
Sys.Modify allows one to to poweroff or reboot the system.
|
||||
Sys.Modify allows a user to power-off and reboot the system.
|
||||
|
||||
**Datastore.Audit**
|
||||
Datastore.Audit allows one to know about a datastore, including reading the
|
||||
Datastore.Audit allows a user to know about a datastore, including reading the
|
||||
configuration entry and listing its contents.
|
||||
|
||||
**Datastore.Allocate**
|
||||
Datastore.Allocate allows one to create or deleting datastores.
|
||||
Datastore.Allocate allows a user to create or delete datastores.
|
||||
|
||||
**Datastore.Modify**
|
||||
Datastore.Modify allows one to modify a datastore and its contents, and to
|
||||
Datastore.Modify allows a user to modify a datastore and its contents, and to
|
||||
create or delete namespaces inside a datastore.
|
||||
|
||||
**Datastore.Read**
|
||||
Datastore.Read allows one to read arbitrary backup contents, independent of
|
||||
Datastore.Read allows a user to read arbitrary backup contents, independent of
|
||||
the backup group owner.
|
||||
|
||||
**Datastore.Verify**
|
||||
Allows verifying the backup snapshots in a datastore.
|
||||
|
||||
**Datastore.Backup**
|
||||
Datastore.Backup allows one create new backup snapshot and gives one also the
|
||||
Datastore.Backup allows a user create new backup snapshots and also provides the
|
||||
privileges of Datastore.Read and Datastore.Verify, but only if the backup
|
||||
group is owned by the user or one of its tokens.
|
||||
|
||||
**Datastore.Prune**
|
||||
Datastore.Prune allows one to delete snapshots, but additionally requires
|
||||
backup ownership
|
||||
Datastore.Prune allows a user to delete snapshots, but additionally requires
|
||||
backup ownership.
|
||||
|
||||
**Permissions.Modify**
|
||||
Permissions.Modify allows one to modifying ACLs
|
||||
Permissions.Modify allows a user to modify ACLs.
|
||||
|
||||
.. note:: One can always configure privileges for their own API tokens, as
|
||||
they will clamped by the users privileges anyway.
|
||||
.. note:: A user can always configure privileges for their own API tokens, as
|
||||
they will be limited by the users privileges anyway.
|
||||
|
||||
**Remote.Audit**
|
||||
Remote.Audit allows one to read the remote and the sync configuration entries
|
||||
Remote.Audit allows a user to read the remote and the sync configuration entries.
|
||||
|
||||
**Remote.Modify**
|
||||
Remote.Modify allows one to modify the remote configuration
|
||||
Remote.Modify allows a user to modify the remote configuration.
|
||||
|
||||
**Remote.Read**
|
||||
Remote.Read allows one to read data from a configured `Remote`
|
||||
Remote.Read allows a user to read data from a configured `Remote`.
|
||||
|
||||
**Sys.Console**
|
||||
Sys.Console allows one to access to the system's console, note that for all
|
||||
Sys.Console allows a user to access the system's console, note that for all
|
||||
but `root@pam` a valid system login is still required.
|
||||
|
||||
**Tape.Audit**
|
||||
Tape.Audit allows one to read the configuration and status of tape drives,
|
||||
changers and backups
|
||||
Tape.Audit allows a user to read the configuration and status of tape drives,
|
||||
changers and backups.
|
||||
|
||||
**Tape.Modify**
|
||||
Tape.Modify allows one to modify the configuration of tape drives, changers
|
||||
and backups
|
||||
Tape.Modify allows a user to modify the configuration of tape drives, changers
|
||||
and backups.
|
||||
|
||||
**Tape.Write**
|
||||
Tape.Write allows one to write to a tape media
|
||||
Tape.Write allows a user to write to a tape media.
|
||||
|
||||
**Tape.Read**
|
||||
Tape.Read allows one to read tape backup configuration and contents from a
|
||||
tape media
|
||||
Tape.Read allows a user to read tape backup configuration and contents from a
|
||||
tape media.
|
||||
|
||||
**Realm.Allocate**
|
||||
Realm.Allocate allows one to view, create, modify and delete authentication
|
||||
realms for users
|
||||
Realm.Allocate allows a user to view, create, modify and delete authentication
|
||||
realms for users.
|
||||
|
||||
Access Roles
|
||||
~~~~~~~~~~~~
|
||||
|
||||
An access role combines one or more privileges into something that can be
|
||||
assigned to an user or API token on an object path.
|
||||
assigned to a user or API token on an object path.
|
||||
|
||||
Currently there are only built-in roles, that means, you cannot create your
|
||||
Currently, there are only built-in roles, meaning you cannot create your
|
||||
own, custom role.
|
||||
|
||||
The following roles exist:
|
||||
@ -277,7 +277,7 @@ The following roles exist:
|
||||
read the actual data.
|
||||
|
||||
**DatastoreReader**
|
||||
Can inspect a datastore's or namespaces content and do restores.
|
||||
Can inspect a datastore's or namespace's content and do restores.
|
||||
|
||||
**DatastoreBackup**
|
||||
Can backup and restore owned backups.
|
||||
@ -295,31 +295,31 @@ The following roles exist:
|
||||
Is allowed to read data from a remote.
|
||||
|
||||
**TapeAdmin**
|
||||
Can do anything related to tape backup
|
||||
Can do anything related to tape backup.
|
||||
|
||||
**TapeAudit**
|
||||
Can view tape related metrics, configuration and status
|
||||
Can view tape-related metrics, configuration and status.
|
||||
|
||||
**TapeOperator**
|
||||
Can do tape backup and restore, but cannot change any configuration
|
||||
Can do tape backup and restore, but cannot change any configuration.
|
||||
|
||||
**TapeReader**
|
||||
Can read and inspect tape configuration and media content
|
||||
Can read and inspect tape configuration and media content.
|
||||
|
||||
Objects and Paths
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Access permissions are assigned to objects, such as a datastore, a namespace or
|
||||
Access permissions are assigned to objects, such as a datastore, namespace or
|
||||
some system resources.
|
||||
|
||||
We use file system like paths to address these objects. These paths form a
|
||||
We use filesystem-like paths to address these objects. These paths form a
|
||||
natural tree, and permissions of higher levels (shorter paths) can optionally
|
||||
be propagated down within this hierarchy.
|
||||
|
||||
Paths can be templated, that means they can refer to the actual id of an
|
||||
Paths can be templated, meaning they can refer to the actual id of a
|
||||
configuration entry. When an API call requires permissions on a templated
|
||||
path, the path may contain references to parameters of the API call. These
|
||||
references are specified in curly braces.
|
||||
references are specified in curly brackets.
|
||||
|
||||
Some examples are:
|
||||
|
||||
@ -329,7 +329,7 @@ Some examples are:
|
||||
* `/datastore/{store}/{ns}`: Access to a specific namespace on a specific
|
||||
datastore
|
||||
* `/remote`: Access to all remote entries
|
||||
* `/system/network`: Access to configuring the host network
|
||||
* `/system/network`: Access to configure the host network
|
||||
* `/tape/`: Access to tape devices, pools and jobs
|
||||
* `/access/users`: User administration
|
||||
* `/access/openid/{id}`: Administrative access to a specific OpenID Connect realm
|
||||
@ -341,7 +341,7 @@ As mentioned earlier, object paths form a file system like tree, and
|
||||
permissions can be inherited by objects down that tree through the propagate
|
||||
flag, which is set by default. We use the following inheritance rules:
|
||||
|
||||
* Permissions for API tokens are always clamped to the one of the user.
|
||||
* Permissions for API tokens are always limited to those of the user.
|
||||
* Permissions on deeper, more specific levels replace those inherited from an
|
||||
upper level.
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user