[pbs-devel] [PATCH v2 proxmox-backup 1/2] docs: language and formatting fixup

Dylan Whyte d.whyte at proxmox.com
Mon Oct 11 13:11:43 CEST 2021


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 at proxmox.com>
---
v1 -> v2:

- Include updated epilog.rst
    - Note: decided not to change the `Proxmox Backup` link reference to
      `Proxmox Backup Server` as there were still some places `Proxmox
       Backup` was more appropriate.
- Replace '`Proxmox Backup Server`_', with '`Proxmox Backup`_ Server'

 docs/epilog.rst          |  4 ++--
 docs/gui.rst             | 13 +++++-----
 docs/installation.rst    | 16 ++++++-------
 docs/introduction.rst    | 36 ++++++++++++++++------------
 docs/storage.rst         | 19 ++++++++-------
 docs/terminology.rst     | 21 ++++++++--------
 docs/user-management.rst | 52 +++++++++++++++++++++-------------------
 7 files changed, 87 insertions(+), 74 deletions(-)

diff --git a/docs/epilog.rst b/docs/epilog.rst
index 644d5df2..54e21a03 100644
--- a/docs/epilog.rst
+++ b/docs/epilog.rst
@@ -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
diff --git a/docs/gui.rst b/docs/gui.rst
index bc0cfab0..a6a8ac86 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
@@ -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
diff --git a/docs/installation.rst b/docs/installation.rst
index 9e623f61..a3367d17 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)
@@ -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