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
Dietmar Maurer
parent
75442e813e
commit
717ce40612
@ -1,5 +1,5 @@
|
||||
.. Epilog (included at top of each file)
|
||||
|
||||
|
||||
We use this file to define external links and common replacement
|
||||
patterns.
|
||||
|
||||
@ -13,7 +13,6 @@
|
||||
.. _Proxmox: https://www.proxmox.com
|
||||
.. _Proxmox Community Forum: https://forum.proxmox.com
|
||||
.. _Proxmox Virtual Environment: https://www.proxmox.com/proxmox-ve
|
||||
.. FIXME
|
||||
.. _Proxmox Backup: https://pbs.proxmox.com/wiki/index.php/Main_Page
|
||||
.. _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
|
||||
@ -23,6 +22,7 @@
|
||||
.. _Virtual machine: https://en.wikipedia.org/wiki/Virtual_machine
|
||||
.. _APT: http://en.wikipedia.org/wiki/Advanced_Packaging_Tool
|
||||
.. _QEMU: https://www.qemu.org/
|
||||
.. _LXC: https://linuxcontainers.org/lxc/introduction/
|
||||
|
||||
.. _Client-server model: https://en.wikipedia.org/wiki/Client-server_model
|
||||
.. _AE: https://en.wikipedia.org/wiki/Authenticated_encryption
|
||||
|
||||
13
docs/gui.rst
13
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.
|
||||
|
||||
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
|
||||
process.
|
||||
login is `root`, and the password is either the one specified during the
|
||||
installation process or the password of the root user, in case of installation
|
||||
on top of Debian.
|
||||
|
||||
|
||||
Features
|
||||
@ -110,7 +111,7 @@ The administration menu item also contains a disk management subsection:
|
||||
* **Disks**: View information on available disks
|
||||
|
||||
* **Directory**: Create and view information on *ext4* and *xfs* disks
|
||||
* **ZFS**: Create and view information on *ZFS* disks
|
||||
* **ZFS**: Create and view information on *ZFS* disks
|
||||
|
||||
Tape Backup
|
||||
^^^^^^^^^^^
|
||||
@ -133,9 +134,9 @@ Datastore
|
||||
:alt: Datastore Configuration
|
||||
|
||||
The Datastore section contains interfaces for creating and managing
|
||||
datastores. It contains a button to create a new datastore on the server, as
|
||||
well as a subsection for each datastore on the system, in which you can use the
|
||||
top panel to view:
|
||||
datastores. It also contains a button for creating a new datastore on the
|
||||
server, as well as a subsection for each datastore on the system, in which you
|
||||
can use the top panel to view:
|
||||
|
||||
* **Summary**: Access a range of datastore usage statistics
|
||||
* **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.
|
||||
|
||||
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
|
||||
you to partition the local disk(s), apply basic system configurations
|
||||
(e.g. timezone, language, network), and install all required packages.
|
||||
you to partition the local disk(s), apply basic system configuration
|
||||
(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
|
||||
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.
|
||||
|
||||
Install `Proxmox Backup`_ with the Installer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Install `Proxmox Backup`_ Server using the Installer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Download the ISO from |DOWNLOADS|.
|
||||
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
|
||||
|
||||
* Complete operating system (Debian Linux, 64-bit)
|
||||
@ -63,7 +63,7 @@ standard Debian installation. After configuring the
|
||||
# apt-get update
|
||||
# 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.
|
||||
|
||||
If you want to install the same set of packages as the installer
|
||||
|
||||
@ -4,15 +4,15 @@ Introduction
|
||||
What is Proxmox Backup Server?
|
||||
------------------------------
|
||||
|
||||
Proxmox Backup Server is an enterprise-class, client-server backup software
|
||||
package that backs up :term:`virtual machine`\ s, :term:`container`\ s, and
|
||||
Proxmox Backup Server is an enterprise-class, client-server backup solution that
|
||||
is capable of backing up :term:`virtual machine`\ s, :term:`container`\ s, and
|
||||
physical hosts. It is specially optimized for the `Proxmox Virtual Environment`_
|
||||
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
|
||||
encryption (AE_). Using :term:`Rust` as the implementation language guarantees high
|
||||
performance, low resource usage, and a safe, high-quality codebase.
|
||||
encryption (AE_). Using :term:`Rust` as the implementation language guarantees
|
||||
high performance, low resource usage, and a safe, high-quality codebase.
|
||||
|
||||
Proxmox Backup uses state of the art cryptography for both client-server
|
||||
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
|
||||
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
|
||||
line tool ``proxmox-backup-client`` you can create backups and restore data.
|
||||
For QEMU_ with `Proxmox Virtual Environment`_ we deliver an integrated client.
|
||||
The backup client uses this API to access the backed up data. You can use the
|
||||
``proxmox-backup-client`` command line tool to create and restore file backups.
|
||||
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
|
||||
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.
|
||||
This way, it's easy to access and restore only important parts of the backup,
|
||||
without the need to scan the whole backup.
|
||||
This way, it's easy to access and restore only the important parts of the
|
||||
backup, without the need to scan the whole backup.
|
||||
|
||||
|
||||
Main Features
|
||||
-------------
|
||||
|
||||
: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.
|
||||
|
||||
: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
|
||||
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
|
||||
user interface.
|
||||
|
||||
@ -80,7 +85,7 @@ Main Features
|
||||
backup-clients.
|
||||
|
||||
: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
|
||||
subscription level get access to the Proxmox Backup :ref:`Enterprise
|
||||
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
|
||||
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
|
||||
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
|
||||
Server, followed by the first stable version in November 2020. With support for
|
||||
incremental, fully deduplicated backups, Proxmox Backup significantly reduces
|
||||
network load and saves valuable storage space.
|
||||
encryption and incremental, fully deduplicated backups, Proxmox Backup offers a
|
||||
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`
|
||||
pre-created chunk namespace directories, and the ``.`` and ``..`` default
|
||||
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.
|
||||
|
||||
|
||||
@ -113,14 +113,15 @@ Datastore Configuration
|
||||
:align: right
|
||||
: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
|
||||
directory on the filesystem. Each datastore also has associated retention
|
||||
settings of how many backup snapshots for each interval of ``hourly``,
|
||||
``daily``, ``weekly``, ``monthly``, ``yearly`` as well as a time-independent
|
||||
number of backups to keep in that store. :ref:`backup-pruning` and
|
||||
:ref:`garbage collection <client_garbage-collection>` can also be configured to run
|
||||
periodically based on a configured schedule (see :ref:`calendar-event-scheduling`) per datastore.
|
||||
:ref:`garbage collection <client_garbage-collection>` can also be configured to
|
||||
run periodically, based on a configured schedule (see
|
||||
:ref:`calendar-event-scheduling`) per datastore.
|
||||
|
||||
|
||||
.. _storage_datastore_create:
|
||||
@ -146,7 +147,8 @@ window:
|
||||
* *Comment* can be used to add some contextual information to the datastore.
|
||||
|
||||
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
|
||||
|
||||
@ -156,7 +158,7 @@ following command creates a new datastore called ``store1`` on :file:`/backup/di
|
||||
Managing Datastores
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To list existing datastores from the command line run:
|
||||
To list existing datastores from the command line, run:
|
||||
|
||||
.. 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.
|
||||
|
||||
The `.chunks` directory contains folders, starting from `0000` and taking hexadecimal values until `ffff`. These
|
||||
directories will store the chunked data after a backup operation has been executed.
|
||||
The `.chunks` directory contains folders, starting from `0000` and increasing in
|
||||
hexadecimal values until `ffff`. These directories will store the chunked data,
|
||||
categorized by checksum, after a backup operation has been executed.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
||||
@ -41,23 +41,23 @@ Binary Data (BLOBs)
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
file archive to store whole directory trees.
|
||||
file archive to store entire directory trees.
|
||||
|
||||
|
||||
Catalog File: ``catalog.pcat1``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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 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
|
||||
backup.
|
||||
|
||||
@ -68,18 +68,19 @@ Backup Type
|
||||
The backup server groups backups by *type*, where *type* is one of:
|
||||
|
||||
``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
|
||||
for each disk.
|
||||
|
||||
``ct``
|
||||
This type is used for :term:`container`\ s. Consists of the container's
|
||||
configuration and a single file archive for the filesystem content.
|
||||
This type is used for :term:`container`\ s. It consists of the container's
|
||||
configuration and a single file archive for the filesystem's contents.
|
||||
|
||||
``host``
|
||||
This type is used for backups created from within the backed up 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.
|
||||
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
|
||||
or container. Such backups may contain file and image archives; there are no
|
||||
restrictions in this regard.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
: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).
|
||||
|
||||
:pbs: Proxmox Backup Server realm. This type stores hashed passwords in
|
||||
@ -40,13 +40,13 @@ users:
|
||||
:align: right
|
||||
:alt: Add a new user
|
||||
|
||||
The superuser has full administration rights on everything, so you
|
||||
normally want to add other users with less privileges. You can add a new
|
||||
The superuser has full administration rights on everything, so it's recommended
|
||||
to add other users with less privileges. You can add a new
|
||||
user with the ``user create`` subcommand or through the web
|
||||
interface, under the **User Management** tab of **Configuration -> Access
|
||||
Control**. The ``create`` subcommand lets you specify many options like
|
||||
``--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
|
||||
@ -74,13 +74,13 @@ The resulting user list looks like this:
|
||||
Newly created users do not have any permissions. Please read the Access Control
|
||||
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
|
||||
|
||||
# proxmox-backup-manager user update john@pbs --enable 0
|
||||
|
||||
Or completely remove the user with:
|
||||
Or completely remove a user with:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -95,7 +95,7 @@ API Tokens
|
||||
:align: right
|
||||
: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
|
||||
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
|
||||
``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
|
||||
|
||||
@ -154,9 +154,9 @@ section to learn how to set access permissions.
|
||||
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
|
||||
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:
|
||||
|
||||
**NoAccess**
|
||||
@ -176,7 +176,7 @@ following roles exist:
|
||||
is not allowed to read the actual data.
|
||||
|
||||
**DatastoreReader**
|
||||
Can Inspect datastore content and can do restores.
|
||||
Can Inspect datastore content and do restores.
|
||||
|
||||
**DatastoreBackup**
|
||||
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 │
|
||||
└──────────┴───────────────────┴───────────┴────────────────┘
|
||||
|
||||
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::
|
||||
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
|
||||
the remote.
|
||||
|
||||
API Token permissions
|
||||
API Token Permissions
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
API token permissions are calculated based on ACLs containing their ID
|
||||
independent of those of their corresponding user. The resulting permission set
|
||||
API token permissions are calculated based on ACLs containing their ID,
|
||||
independently of those of their corresponding user. The resulting permission set
|
||||
on a given path is then intersected with that of the corresponding user.
|
||||
|
||||
In practice this means:
|
||||
@ -259,17 +260,17 @@ In practice this means:
|
||||
#. API tokens require their own ACL entries
|
||||
#. 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:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# proxmox-backup-manager user permissions john@pbs --path /datastore/store1
|
||||
Privileges with (*) have the propagate flag set
|
||||
|
||||
|
||||
Path: /datastore/store1
|
||||
- Datastore.Audit (*)
|
||||
- Datastore.Backup (*)
|
||||
@ -277,17 +278,17 @@ you can use the ``proxmox-backup-manager user permission`` command:
|
||||
- Datastore.Prune (*)
|
||||
- Datastore.Read (*)
|
||||
- Datastore.Verify (*)
|
||||
|
||||
|
||||
# proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1'
|
||||
# proxmox-backup-manager user permissions 'john@pbs!client1' --path /datastore/store1
|
||||
Privileges with (*) have the propagate flag set
|
||||
|
||||
|
||||
Path: /datastore/store1
|
||||
- Datastore.Backup (*)
|
||||
|
||||
.. _user_tfa:
|
||||
|
||||
Two-factor authentication
|
||||
Two-Factor Authentication
|
||||
-------------------------
|
||||
|
||||
Introduction
|
||||
@ -296,7 +297,7 @@ Introduction
|
||||
With simple authentication, only a password (single factor) is required to
|
||||
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
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
* 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>`_).
|
||||
While it probably works with an untrusted certificate, some browsers may warn
|
||||
or refuse WebAuthn operations if it is not trusted.
|
||||
|
||||
* setup the WebAuthn configuration (see *Configuration -> Authentication* in the
|
||||
Proxmox Backup Server web-interface). This can be auto-filled in most setups.
|
||||
* Setup the WebAuthn configuration (see **Configuration -> Authentication** in
|
||||
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
|
||||
configuration in the *Access Control* panel.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user