[pbs-devel] [PATCH proxmox-backup 1/2] docs: language and formatting fixup
Dylan Whyte
d.whyte at proxmox.com
Wed Oct 6 17:19:56 CEST 2021
Some minor changes to the sections: Introduction, Installation,
Terminology, GUI, Storage, and User Management
Signed-off-by: Dylan Whyte <d.whyte at proxmox.com>
---
docs/gui.rst | 15 ++++++------
docs/installation.rst | 18 +++++++-------
docs/introduction.rst | 36 ++++++++++++++++------------
docs/storage.rst | 19 ++++++++-------
docs/terminology.rst | 21 ++++++++--------
docs/user-management.rst | 52 +++++++++++++++++++++-------------------
6 files changed, 87 insertions(+), 74 deletions(-)
diff --git a/docs/gui.rst b/docs/gui.rst
index bc0cfab0..bbe59e5a 100644
--- a/docs/gui.rst
+++ b/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
@@ -109,8 +110,8 @@ 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
+ * **Directory**: Create and view information on *ext4* and *xfs* file systems
+ * **ZFS**: Create and view information on *ZFS* file systems
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
diff --git a/docs/installation.rst b/docs/installation.rst
index 9e623f61..283f2047 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -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)
@@ -51,7 +51,7 @@ It includes the following:
is used by default and all existing data is removed.
-Install `Proxmox Backup`_ Server on Debian
+Install `Proxmox Backup Server`_ on Debian
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Proxmox ships as a set of Debian packages which can be installed on top of a
@@ -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
diff --git a/docs/introduction.rst b/docs/introduction.rst
index ddfdcf17..ed1816d3 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -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.
diff --git a/docs/storage.rst b/docs/storage.rst
index 76755beb..562da160 100644
--- a/docs/storage.rst
+++ b/docs/storage.rst
@@ -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
diff --git a/docs/terminology.rst b/docs/terminology.rst
index 5a2e30a0..dcce117b 100644
--- a/docs/terminology.rst
+++ b/docs/terminology.rst
@@ -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
diff --git a/docs/user-management.rst b/docs/user-management.rst
index 8a580217..435e0368 100644
--- a/docs/user-management.rst
+++ b/docs/user-management.rst
@@ -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 at 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 at 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 at 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 at pbs!client1'
# proxmox-backup-manager user permissions 'john at 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 at 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.
--
2.30.2
More information about the pbs-devel
mailing list