From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 41F3874A83 for ; Mon, 11 Oct 2021 13:13:08 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 3FAC91E8B1 for ; Mon, 11 Oct 2021 13:13:08 +0200 (CEST) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id 7CAEA1E87E for ; Mon, 11 Oct 2021 13:13:05 +0200 (CEST) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 56BA545CCE for ; Mon, 11 Oct 2021 13:13:05 +0200 (CEST) From: Dylan Whyte To: pbs-devel@lists.proxmox.com Date: Mon, 11 Oct 2021 13:11:43 +0200 Message-Id: <20211011111144.116672-1-d.whyte@proxmox.com> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.021 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% KAM_ASCII_DIVIDERS 0.8 Spam that uses ascii formatting tricks KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pbs-devel] [PATCH v2 proxmox-backup 1/2] docs: language and formatting fixup X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 11 Oct 2021 11:13:08 -0000 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 --- 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 `. 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 `_. Users at every subscription level get access to the Proxmox Backup :ref:`Enterprise Repository `. In addition, with a Basic, @@ -173,7 +178,7 @@ Bug Tracker ~~~~~~~~~~~ Proxmox runs a public bug tracker at ``_. 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 ` can also be configured to run -periodically based on a configured schedule (see :ref:`calendar-event-scheduling`) per datastore. +:ref:`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@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 `_). 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