docs: language and formatting fixup
Some minor changes to the sections: Introduction, Installation, Terminology, GUI, Storage, and User Management Mention tape backup in main features Update epilog.rst with link for 'LXC'. Remove FIXME from epilog.rst (I believe this was a note to repair the not-yet-created pbs wiki link). Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
This commit is contained in:
parent
75442e813e
commit
717ce40612
|
@ -13,7 +13,6 @@
|
||||||
.. _Proxmox: https://www.proxmox.com
|
.. _Proxmox: https://www.proxmox.com
|
||||||
.. _Proxmox Community Forum: https://forum.proxmox.com
|
.. _Proxmox Community Forum: https://forum.proxmox.com
|
||||||
.. _Proxmox Virtual Environment: https://www.proxmox.com/proxmox-ve
|
.. _Proxmox Virtual Environment: https://www.proxmox.com/proxmox-ve
|
||||||
.. FIXME
|
|
||||||
.. _Proxmox Backup: https://pbs.proxmox.com/wiki/index.php/Main_Page
|
.. _Proxmox Backup: https://pbs.proxmox.com/wiki/index.php/Main_Page
|
||||||
.. _PBS Development List: https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel
|
.. _PBS Development List: https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel
|
||||||
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
|
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
|
||||||
|
@ -23,6 +22,7 @@
|
||||||
.. _Virtual machine: https://en.wikipedia.org/wiki/Virtual_machine
|
.. _Virtual machine: https://en.wikipedia.org/wiki/Virtual_machine
|
||||||
.. _APT: http://en.wikipedia.org/wiki/Advanced_Packaging_Tool
|
.. _APT: http://en.wikipedia.org/wiki/Advanced_Packaging_Tool
|
||||||
.. _QEMU: https://www.qemu.org/
|
.. _QEMU: https://www.qemu.org/
|
||||||
|
.. _LXC: https://linuxcontainers.org/lxc/introduction/
|
||||||
|
|
||||||
.. _Client-server model: https://en.wikipedia.org/wiki/Client-server_model
|
.. _Client-server model: https://en.wikipedia.org/wiki/Client-server_model
|
||||||
.. _AE: https://en.wikipedia.org/wiki/Authenticated_encryption
|
.. _AE: https://en.wikipedia.org/wiki/Authenticated_encryption
|
||||||
|
|
11
docs/gui.rst
11
docs/gui.rst
|
@ -8,8 +8,9 @@ tools. The web interface also provides a built-in console, so if you prefer the
|
||||||
command line or need some extra control, you have this option.
|
command line or need some extra control, you have this option.
|
||||||
|
|
||||||
The web interface can be accessed via https://youripaddress:8007. The default
|
The web interface can be accessed via https://youripaddress:8007. The default
|
||||||
login is `root`, and the password is the one specified during the installation
|
login is `root`, and the password is either the one specified during the
|
||||||
process.
|
installation process or the password of the root user, in case of installation
|
||||||
|
on top of Debian.
|
||||||
|
|
||||||
|
|
||||||
Features
|
Features
|
||||||
|
@ -133,9 +134,9 @@ Datastore
|
||||||
:alt: Datastore Configuration
|
:alt: Datastore Configuration
|
||||||
|
|
||||||
The Datastore section contains interfaces for creating and managing
|
The Datastore section contains interfaces for creating and managing
|
||||||
datastores. It contains a button to create a new datastore on the server, as
|
datastores. It also contains a button for creating a new datastore on the
|
||||||
well as a subsection for each datastore on the system, in which you can use the
|
server, as well as a subsection for each datastore on the system, in which you
|
||||||
top panel to view:
|
can use the top panel to view:
|
||||||
|
|
||||||
* **Summary**: Access a range of datastore usage statistics
|
* **Summary**: Access a range of datastore usage statistics
|
||||||
* **Content**: Information on the datastore's backup groups and their respective
|
* **Content**: Information on the datastore's backup groups and their respective
|
||||||
|
|
|
@ -19,24 +19,24 @@ for various management tasks such as disk management.
|
||||||
`Proxmox Backup`_ without the server part.
|
`Proxmox Backup`_ without the server part.
|
||||||
|
|
||||||
The disk image (ISO file) provided by Proxmox includes a complete Debian system
|
The disk image (ISO file) provided by Proxmox includes a complete Debian system
|
||||||
as well as all necessary packages for the `Proxmox Backup`_ server.
|
as well as all necessary packages for the `Proxmox Backup`_ Server.
|
||||||
|
|
||||||
The installer will guide you through the setup process and allow
|
The installer will guide you through the setup process and allow
|
||||||
you to partition the local disk(s), apply basic system configurations
|
you to partition the local disk(s), apply basic system configuration
|
||||||
(e.g. timezone, language, network), and install all required packages.
|
(for example timezone, language, network), and install all required packages.
|
||||||
The provided ISO will get you started in just a few minutes, and is the
|
The provided ISO will get you started in just a few minutes, and is the
|
||||||
recommended method for new and existing users.
|
recommended method for new and existing users.
|
||||||
|
|
||||||
Alternatively, `Proxmox Backup`_ server can be installed on top of an
|
Alternatively, `Proxmox Backup`_ Server can be installed on top of an
|
||||||
existing Debian system.
|
existing Debian system.
|
||||||
|
|
||||||
Install `Proxmox Backup`_ with the Installer
|
Install `Proxmox Backup`_ Server using the Installer
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Download the ISO from |DOWNLOADS|.
|
Download the ISO from |DOWNLOADS|.
|
||||||
It includes the following:
|
It includes the following:
|
||||||
|
|
||||||
* The `Proxmox Backup`_ server installer, which partitions the local
|
* The `Proxmox Backup`_ Server installer, which partitions the local
|
||||||
disk(s) with ext4, xfs or ZFS, and installs the operating system
|
disk(s) with ext4, xfs or ZFS, and installs the operating system
|
||||||
|
|
||||||
* Complete operating system (Debian Linux, 64-bit)
|
* Complete operating system (Debian Linux, 64-bit)
|
||||||
|
@ -63,7 +63,7 @@ standard Debian installation. After configuring the
|
||||||
# apt-get update
|
# apt-get update
|
||||||
# apt-get install proxmox-backup-server
|
# apt-get install proxmox-backup-server
|
||||||
|
|
||||||
The commands above keep the current (Debian) kernel and install a minimal
|
The above commands keep the current (Debian) kernel and install a minimal
|
||||||
set of required packages.
|
set of required packages.
|
||||||
|
|
||||||
If you want to install the same set of packages as the installer
|
If you want to install the same set of packages as the installer
|
||||||
|
|
|
@ -4,15 +4,15 @@ Introduction
|
||||||
What is Proxmox Backup Server?
|
What is Proxmox Backup Server?
|
||||||
------------------------------
|
------------------------------
|
||||||
|
|
||||||
Proxmox Backup Server is an enterprise-class, client-server backup software
|
Proxmox Backup Server is an enterprise-class, client-server backup solution that
|
||||||
package that backs up :term:`virtual machine`\ s, :term:`container`\ s, and
|
is capable of backing up :term:`virtual machine`\ s, :term:`container`\ s, and
|
||||||
physical hosts. It is specially optimized for the `Proxmox Virtual Environment`_
|
physical hosts. It is specially optimized for the `Proxmox Virtual Environment`_
|
||||||
platform and allows you to back up your data securely, even between remote
|
platform and allows you to back up your data securely, even between remote
|
||||||
sites, providing easy management with a web-based user interface.
|
sites, providing easy management through a web-based user interface.
|
||||||
|
|
||||||
It supports deduplication, compression, and authenticated
|
It supports deduplication, compression, and authenticated
|
||||||
encryption (AE_). Using :term:`Rust` as the implementation language guarantees high
|
encryption (AE_). Using :term:`Rust` as the implementation language guarantees
|
||||||
performance, low resource usage, and a safe, high-quality codebase.
|
high performance, low resource usage, and a safe, high-quality codebase.
|
||||||
|
|
||||||
Proxmox Backup uses state of the art cryptography for both client-server
|
Proxmox Backup uses state of the art cryptography for both client-server
|
||||||
communication and backup content :ref:`encryption <client_encryption>`. All
|
communication and backup content :ref:`encryption <client_encryption>`. All
|
||||||
|
@ -28,22 +28,23 @@ Proxmox Backup Server uses a `client-server model`_. The server stores the
|
||||||
backup data and provides an API to create and manage datastores. With the
|
backup data and provides an API to create and manage datastores. With the
|
||||||
API, it's also possible to manage disks and other server-side resources.
|
API, it's also possible to manage disks and other server-side resources.
|
||||||
|
|
||||||
The backup client uses this API to access the backed up data. With the command
|
The backup client uses this API to access the backed up data. You can use the
|
||||||
line tool ``proxmox-backup-client`` you can create backups and restore data.
|
``proxmox-backup-client`` command line tool to create and restore file backups.
|
||||||
For QEMU_ with `Proxmox Virtual Environment`_ we deliver an integrated client.
|
For QEMU_ and LXC_ within `Proxmox Virtual Environment`_, we deliver an
|
||||||
|
integrated client.
|
||||||
|
|
||||||
A single backup is allowed to contain several archives. For example, when you
|
A single backup is allowed to contain several archives. For example, when you
|
||||||
backup a :term:`virtual machine`, each disk is stored as a separate archive
|
backup a :term:`virtual machine`, each disk is stored as a separate archive
|
||||||
inside that backup. The VM configuration itself is stored as an extra file.
|
inside that backup. The VM configuration itself is stored as an extra file.
|
||||||
This way, it's easy to access and restore only important parts of the backup,
|
This way, it's easy to access and restore only the important parts of the
|
||||||
without the need to scan the whole backup.
|
backup, without the need to scan the whole backup.
|
||||||
|
|
||||||
|
|
||||||
Main Features
|
Main Features
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
:Support for Proxmox VE: The `Proxmox Virtual Environment`_ is fully
|
:Support for Proxmox VE: The `Proxmox Virtual Environment`_ is fully
|
||||||
supported and you can easily backup :term:`virtual machine`\ s and
|
supported, and you can easily backup :term:`virtual machine`\ s and
|
||||||
:term:`container`\ s.
|
:term:`container`\ s.
|
||||||
|
|
||||||
:Performance: The whole software stack is written in :term:`Rust`,
|
:Performance: The whole software stack is written in :term:`Rust`,
|
||||||
|
@ -70,6 +71,10 @@ Main Features
|
||||||
modern hardware. In addition to client-side encryption, all data is
|
modern hardware. In addition to client-side encryption, all data is
|
||||||
transferred via a secure TLS connection.
|
transferred via a secure TLS connection.
|
||||||
|
|
||||||
|
:Tape backup: For long-term archiving of data, Proxmox Backup Server also
|
||||||
|
provides extensive support for backing up to tape and managing tape
|
||||||
|
libraries.
|
||||||
|
|
||||||
:Web interface: Manage the Proxmox Backup Server with the integrated, web-based
|
:Web interface: Manage the Proxmox Backup Server with the integrated, web-based
|
||||||
user interface.
|
user interface.
|
||||||
|
|
||||||
|
@ -80,7 +85,7 @@ Main Features
|
||||||
backup-clients.
|
backup-clients.
|
||||||
|
|
||||||
:Enterprise Support: Proxmox Server Solutions GmbH offers enterprise support in
|
:Enterprise Support: Proxmox Server Solutions GmbH offers enterprise support in
|
||||||
form of `Proxmox Backup Server Subscription Plans
|
the form of `Proxmox Backup Server Subscription Plans
|
||||||
<https://www.proxmox.com/en/proxmox-backup-server/pricing>`_. Users at every
|
<https://www.proxmox.com/en/proxmox-backup-server/pricing>`_. Users at every
|
||||||
subscription level get access to the Proxmox Backup :ref:`Enterprise
|
subscription level get access to the Proxmox Backup :ref:`Enterprise
|
||||||
Repository <sysadmin_package_repos_enterprise>`. In addition, with a Basic,
|
Repository <sysadmin_package_repos_enterprise>`. In addition, with a Basic,
|
||||||
|
@ -173,7 +178,7 @@ Bug Tracker
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
Proxmox runs a public bug tracker at `<https://bugzilla.proxmox.com>`_. If an
|
Proxmox runs a public bug tracker at `<https://bugzilla.proxmox.com>`_. If an
|
||||||
issue appears, file your report there. An issue can be a bug as well as a
|
issue appears, file your report there. An issue can be a bug, as well as a
|
||||||
request for a new feature or enhancement. The bug tracker helps to keep track
|
request for a new feature or enhancement. The bug tracker helps to keep track
|
||||||
of the issue and will send a notification once it has been solved.
|
of the issue and will send a notification once it has been solved.
|
||||||
|
|
||||||
|
@ -224,5 +229,6 @@ requirements.
|
||||||
|
|
||||||
In July 2020, we released the first beta version of Proxmox Backup
|
In July 2020, we released the first beta version of Proxmox Backup
|
||||||
Server, followed by the first stable version in November 2020. With support for
|
Server, followed by the first stable version in November 2020. With support for
|
||||||
incremental, fully deduplicated backups, Proxmox Backup significantly reduces
|
encryption and incremental, fully deduplicated backups, Proxmox Backup offers a
|
||||||
network load and saves valuable storage space.
|
secure environment, which significantly reduces network load and saves valuable
|
||||||
|
storage space.
|
||||||
|
|
|
@ -102,7 +102,7 @@ is stored in the file ``/etc/proxmox-backup/datastore.cfg``.
|
||||||
subdirectories per directory. That number comes from the 2\ :sup:`16`
|
subdirectories per directory. That number comes from the 2\ :sup:`16`
|
||||||
pre-created chunk namespace directories, and the ``.`` and ``..`` default
|
pre-created chunk namespace directories, and the ``.`` and ``..`` default
|
||||||
directory entries. This requirement excludes certain filesystems and
|
directory entries. This requirement excludes certain filesystems and
|
||||||
filesystem configuration from being supported for a datastore. For example,
|
filesystem configurations from being supported for a datastore. For example,
|
||||||
``ext3`` as a whole or ``ext4`` with the ``dir_nlink`` feature manually disabled.
|
``ext3`` as a whole or ``ext4`` with the ``dir_nlink`` feature manually disabled.
|
||||||
|
|
||||||
|
|
||||||
|
@ -113,14 +113,15 @@ Datastore Configuration
|
||||||
:align: right
|
:align: right
|
||||||
:alt: Datastore Overview
|
:alt: Datastore Overview
|
||||||
|
|
||||||
You can configure multiple datastores. Minimum one datastore needs to be
|
You can configure multiple datastores. A minimum of one datastore needs to be
|
||||||
configured. The datastore is identified by a simple *name* and points to a
|
configured. The datastore is identified by a simple *name* and points to a
|
||||||
directory on the filesystem. Each datastore also has associated retention
|
directory on the filesystem. Each datastore also has associated retention
|
||||||
settings of how many backup snapshots for each interval of ``hourly``,
|
settings of how many backup snapshots for each interval of ``hourly``,
|
||||||
``daily``, ``weekly``, ``monthly``, ``yearly`` as well as a time-independent
|
``daily``, ``weekly``, ``monthly``, ``yearly`` as well as a time-independent
|
||||||
number of backups to keep in that store. :ref:`backup-pruning` and
|
number of backups to keep in that store. :ref:`backup-pruning` and
|
||||||
:ref:`garbage collection <client_garbage-collection>` can also be configured to run
|
:ref:`garbage collection <client_garbage-collection>` can also be configured to
|
||||||
periodically based on a configured schedule (see :ref:`calendar-event-scheduling`) per datastore.
|
run periodically, based on a configured schedule (see
|
||||||
|
:ref:`calendar-event-scheduling`) per datastore.
|
||||||
|
|
||||||
|
|
||||||
.. _storage_datastore_create:
|
.. _storage_datastore_create:
|
||||||
|
@ -146,7 +147,8 @@ window:
|
||||||
* *Comment* can be used to add some contextual information to the datastore.
|
* *Comment* can be used to add some contextual information to the datastore.
|
||||||
|
|
||||||
Alternatively you can create a new datastore from the command line. The
|
Alternatively you can create a new datastore from the command line. The
|
||||||
following command creates a new datastore called ``store1`` on :file:`/backup/disk1/store1`
|
following command creates a new datastore called ``store1`` on
|
||||||
|
:file:`/backup/disk1/store1`
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
|
@ -156,7 +158,7 @@ following command creates a new datastore called ``store1`` on :file:`/backup/di
|
||||||
Managing Datastores
|
Managing Datastores
|
||||||
^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
To list existing datastores from the command line run:
|
To list existing datastores from the command line, run:
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
|
@ -216,8 +218,9 @@ After creating a datastore, the following default layout will appear:
|
||||||
|
|
||||||
`.lock` is an empty file used for process locking.
|
`.lock` is an empty file used for process locking.
|
||||||
|
|
||||||
The `.chunks` directory contains folders, starting from `0000` and taking hexadecimal values until `ffff`. These
|
The `.chunks` directory contains folders, starting from `0000` and increasing in
|
||||||
directories will store the chunked data after a backup operation has been executed.
|
hexadecimal values until `ffff`. These directories will store the chunked data,
|
||||||
|
categorized by checksum, after a backup operation has been executed.
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
|
|
|
@ -41,23 +41,23 @@ Binary Data (BLOBs)
|
||||||
~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
This type is used to store smaller (< 16MB) binary data such as
|
This type is used to store smaller (< 16MB) binary data such as
|
||||||
configuration files. Larger files should be stored as image archive.
|
configuration files. Larger files should be stored as image archives.
|
||||||
|
|
||||||
.. caution:: Please do not store all files as BLOBs. Instead, use the
|
.. caution:: Please do not store all files as BLOBs. Instead, use the
|
||||||
file archive to store whole directory trees.
|
file archive to store entire directory trees.
|
||||||
|
|
||||||
|
|
||||||
Catalog File: ``catalog.pcat1``
|
Catalog File: ``catalog.pcat1``
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The catalog file is an index for file archives. It contains
|
The catalog file is an index for file archives. It contains
|
||||||
the list of files and is used to speed up search operations.
|
the list of included files and is used to speed up search operations.
|
||||||
|
|
||||||
|
|
||||||
The Manifest: ``index.json``
|
The Manifest: ``index.json``
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The manifest contains the list of all backup files, their
|
The manifest contains a list of all backed up files, and their
|
||||||
sizes and checksums. It is used to verify the consistency of a
|
sizes and checksums. It is used to verify the consistency of a
|
||||||
backup.
|
backup.
|
||||||
|
|
||||||
|
@ -68,18 +68,19 @@ Backup Type
|
||||||
The backup server groups backups by *type*, where *type* is one of:
|
The backup server groups backups by *type*, where *type* is one of:
|
||||||
|
|
||||||
``vm``
|
``vm``
|
||||||
This type is used for :term:`virtual machine`\ s. Typically
|
This type is used for :term:`virtual machine`\ s. It typically
|
||||||
consists of the virtual machine's configuration file and an image archive
|
consists of the virtual machine's configuration file and an image archive
|
||||||
for each disk.
|
for each disk.
|
||||||
|
|
||||||
``ct``
|
``ct``
|
||||||
This type is used for :term:`container`\ s. Consists of the container's
|
This type is used for :term:`container`\ s. It consists of the container's
|
||||||
configuration and a single file archive for the filesystem content.
|
configuration and a single file archive for the filesystem's contents.
|
||||||
|
|
||||||
``host``
|
``host``
|
||||||
This type is used for backups created from within the backed up machine.
|
This type is used for file/directory backups created from within a machine.
|
||||||
Typically this would be a physical host but could also be a virtual machine
|
Typically this would be a physical host, but could also be a virtual machine
|
||||||
or container. Such backups may contain file and image archives, there are no restrictions in this regard.
|
or container. Such backups may contain file and image archives; there are no
|
||||||
|
restrictions in this regard.
|
||||||
|
|
||||||
|
|
||||||
Backup ID
|
Backup ID
|
||||||
|
|
|
@ -15,7 +15,7 @@ Proxmox Backup Server supports several authentication realms, and you need to
|
||||||
choose the realm when you add a new user. Possible realms are:
|
choose the realm when you add a new user. Possible realms are:
|
||||||
|
|
||||||
:pam: Linux PAM standard authentication. Use this if you want to
|
:pam: Linux PAM standard authentication. Use this if you want to
|
||||||
authenticate as Linux system user (Users need to exist on the
|
authenticate as a Linux system user (users need to exist on the
|
||||||
system).
|
system).
|
||||||
|
|
||||||
:pbs: Proxmox Backup Server realm. This type stores hashed passwords in
|
:pbs: Proxmox Backup Server realm. This type stores hashed passwords in
|
||||||
|
@ -40,13 +40,13 @@ users:
|
||||||
:align: right
|
:align: right
|
||||||
:alt: Add a new user
|
:alt: Add a new user
|
||||||
|
|
||||||
The superuser has full administration rights on everything, so you
|
The superuser has full administration rights on everything, so it's recommended
|
||||||
normally want to add other users with less privileges. You can add a new
|
to add other users with less privileges. You can add a new
|
||||||
user with the ``user create`` subcommand or through the web
|
user with the ``user create`` subcommand or through the web
|
||||||
interface, under the **User Management** tab of **Configuration -> Access
|
interface, under the **User Management** tab of **Configuration -> Access
|
||||||
Control**. The ``create`` subcommand lets you specify many options like
|
Control**. The ``create`` subcommand lets you specify many options like
|
||||||
``--email`` or ``--password``. You can update or change any user properties
|
``--email`` or ``--password``. You can update or change any user properties
|
||||||
using the ``update`` subcommand later (**Edit** in the GUI):
|
using the ``user update`` subcommand later (**Edit** in the GUI):
|
||||||
|
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
@ -74,13 +74,13 @@ The resulting user list looks like this:
|
||||||
Newly created users do not have any permissions. Please read the Access Control
|
Newly created users do not have any permissions. Please read the Access Control
|
||||||
section to learn how to set access permissions.
|
section to learn how to set access permissions.
|
||||||
|
|
||||||
If you want to disable a user account, you can do that by setting ``--enable`` to ``0``
|
You can disable a user account by setting ``--enable`` to ``0``:
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
# proxmox-backup-manager user update john@pbs --enable 0
|
# proxmox-backup-manager user update john@pbs --enable 0
|
||||||
|
|
||||||
Or completely remove the user with:
|
Or completely remove a user with:
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
|
@ -95,7 +95,7 @@ API Tokens
|
||||||
:align: right
|
:align: right
|
||||||
:alt: API Token Overview
|
:alt: API Token Overview
|
||||||
|
|
||||||
Any authenticated user can generate API tokens which can in turn be used to
|
Any authenticated user can generate API tokens, which can in turn be used to
|
||||||
configure various clients, instead of directly providing the username and
|
configure various clients, instead of directly providing the username and
|
||||||
password.
|
password.
|
||||||
|
|
||||||
|
@ -117,7 +117,7 @@ The API token is passed from the client to the server by setting the
|
||||||
``Authorization`` HTTP header with method ``PBSAPIToken`` to the value
|
``Authorization`` HTTP header with method ``PBSAPIToken`` to the value
|
||||||
``TOKENID:TOKENSECRET``.
|
``TOKENID:TOKENSECRET``.
|
||||||
|
|
||||||
Generating new tokens can done using ``proxmox-backup-manager`` or the GUI:
|
You can generate tokens from the GUI or by using ``proxmox-backup-manager``:
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
|
@ -154,9 +154,9 @@ section to learn how to set access permissions.
|
||||||
Access Control
|
Access Control
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
By default new users and API tokens do not have any permission. Instead you
|
By default, new users and API tokens do not have any permissions. Instead you
|
||||||
need to specify what is allowed and what is not. You can do this by assigning
|
need to specify what is allowed and what is not. You can do this by assigning
|
||||||
roles to users/tokens on specific objects like datastores or remotes. The
|
roles to users/tokens on specific objects, like datastores or remotes. The
|
||||||
following roles exist:
|
following roles exist:
|
||||||
|
|
||||||
**NoAccess**
|
**NoAccess**
|
||||||
|
@ -176,7 +176,7 @@ following roles exist:
|
||||||
is not allowed to read the actual data.
|
is not allowed to read the actual data.
|
||||||
|
|
||||||
**DatastoreReader**
|
**DatastoreReader**
|
||||||
Can Inspect datastore content and can do restores.
|
Can Inspect datastore content and do restores.
|
||||||
|
|
||||||
**DatastoreBackup**
|
**DatastoreBackup**
|
||||||
Can backup and restore owned backups.
|
Can backup and restore owned backups.
|
||||||
|
@ -236,7 +236,8 @@ You can list the ACLs of each user/token using the following command:
|
||||||
│ john@pbs │ /datastore/store1 │ 1 │ DatastoreAdmin │
|
│ john@pbs │ /datastore/store1 │ 1 │ DatastoreAdmin │
|
||||||
└──────────┴───────────────────┴───────────┴────────────────┘
|
└──────────┴───────────────────┴───────────┴────────────────┘
|
||||||
|
|
||||||
A single user/token can be assigned multiple permission sets for different datastores.
|
A single user/token can be assigned multiple permission sets for different
|
||||||
|
datastores.
|
||||||
|
|
||||||
.. Note::
|
.. Note::
|
||||||
Naming convention is important here. For datastores on the host,
|
Naming convention is important here. For datastores on the host,
|
||||||
|
@ -247,11 +248,11 @@ A single user/token can be assigned multiple permission sets for different datas
|
||||||
remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
|
remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
|
||||||
the remote.
|
the remote.
|
||||||
|
|
||||||
API Token permissions
|
API Token Permissions
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
API token permissions are calculated based on ACLs containing their ID
|
API token permissions are calculated based on ACLs containing their ID,
|
||||||
independent of those of their corresponding user. The resulting permission set
|
independently of those of their corresponding user. The resulting permission set
|
||||||
on a given path is then intersected with that of the corresponding user.
|
on a given path is then intersected with that of the corresponding user.
|
||||||
|
|
||||||
In practice this means:
|
In practice this means:
|
||||||
|
@ -259,10 +260,10 @@ In practice this means:
|
||||||
#. API tokens require their own ACL entries
|
#. API tokens require their own ACL entries
|
||||||
#. API tokens can never do more than their corresponding user
|
#. API tokens can never do more than their corresponding user
|
||||||
|
|
||||||
Effective permissions
|
Effective Permissions
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
To calculate and display the effective permission set of a user or API token
|
To calculate and display the effective permission set of a user or API token,
|
||||||
you can use the ``proxmox-backup-manager user permission`` command:
|
you can use the ``proxmox-backup-manager user permission`` command:
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
@ -287,7 +288,7 @@ you can use the ``proxmox-backup-manager user permission`` command:
|
||||||
|
|
||||||
.. _user_tfa:
|
.. _user_tfa:
|
||||||
|
|
||||||
Two-factor authentication
|
Two-Factor Authentication
|
||||||
-------------------------
|
-------------------------
|
||||||
|
|
||||||
Introduction
|
Introduction
|
||||||
|
@ -296,7 +297,7 @@ Introduction
|
||||||
With simple authentication, only a password (single factor) is required to
|
With simple authentication, only a password (single factor) is required to
|
||||||
successfully claim an identity (authenticate), for example, to be able to log in
|
successfully claim an identity (authenticate), for example, to be able to log in
|
||||||
as `root@pam` on a specific instance of Proxmox Backup Server. In this case, if
|
as `root@pam` on a specific instance of Proxmox Backup Server. In this case, if
|
||||||
the password gets stolen or leaked, anybody can use it to log in - even if they
|
the password gets leaked or stolen, anybody can use it to log in - even if they
|
||||||
should not be allowed to do so.
|
should not be allowed to do so.
|
||||||
|
|
||||||
With two-factor authentication (TFA), a user is asked for an additional factor
|
With two-factor authentication (TFA), a user is asked for an additional factor
|
||||||
|
@ -359,13 +360,14 @@ WebAuthn
|
||||||
|
|
||||||
For WebAuthn to work, you need to have two things:
|
For WebAuthn to work, you need to have two things:
|
||||||
|
|
||||||
* a trusted HTTPS certificate (for example, by using `Let's Encrypt
|
* A trusted HTTPS certificate (for example, by using `Let's Encrypt
|
||||||
<https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_).
|
<https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_).
|
||||||
While it probably works with an untrusted certificate, some browsers may warn
|
While it probably works with an untrusted certificate, some browsers may warn
|
||||||
or refuse WebAuthn operations if it is not trusted.
|
or refuse WebAuthn operations if it is not trusted.
|
||||||
|
|
||||||
* setup the WebAuthn configuration (see *Configuration -> Authentication* in the
|
* Setup the WebAuthn configuration (see **Configuration -> Authentication** in
|
||||||
Proxmox Backup Server web-interface). This can be auto-filled in most setups.
|
the Proxmox Backup Server web interface). This can be auto-filled in most
|
||||||
|
setups.
|
||||||
|
|
||||||
Once you have fulfilled both of these requirements, you can add a WebAuthn
|
Once you have fulfilled both of these requirements, you can add a WebAuthn
|
||||||
configuration in the *Access Control* panel.
|
configuration in the *Access Control* panel.
|
||||||
|
|
Loading…
Reference in New Issue