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:
Dylan Whyte 2021-10-11 13:11:43 +02:00 committed by Dietmar Maurer
parent 75442e813e
commit 717ce40612
7 changed files with 87 additions and 74 deletions

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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.