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 0343279AE1 for ; Wed, 27 Oct 2021 16:20:07 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id E9A8E143D7 for ; Wed, 27 Oct 2021 16:19:36 +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) server-digest SHA256) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id 2EA92143BF for ; Wed, 27 Oct 2021 16:19:35 +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 09E5D468BB for ; Wed, 27 Oct 2021 16:19:35 +0200 (CEST) From: Dylan Whyte To: pbs-devel@lists.proxmox.com Date: Wed, 27 Oct 2021 16:19:27 +0200 Message-Id: <20211027141927.110446-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.023 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 proxmox-backup] docs: language fixup: faq and appendix 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: Wed, 27 Oct 2021 14:20:07 -0000 minor formatting and language fixes to the faq section and the appendix Signed-off-by: Dylan Whyte --- docs/backup-protocol.rst | 71 +++++++++++++++-------------- docs/calendarevents.rst | 12 ++--- docs/command-syntax.rst | 2 +- docs/config/acl/format.rst | 6 +-- docs/config/datastore/format.rst | 6 +-- docs/config/media-pool/format.rst | 4 +- docs/config/remote/format.rst | 4 +- docs/config/sync/format.rst | 4 +- docs/config/tape-job/format.rst | 2 +- docs/config/tape/format.rst | 6 +-- docs/config/user/format.rst | 4 +- docs/config/verification/format.rst | 2 +- docs/configuration-files.rst | 2 +- docs/faq.rst | 6 +-- docs/file-formats.rst | 30 ++++++------ docs/glossary.rst | 12 ++--- docs/output-format.rst | 4 +- 17 files changed, 90 insertions(+), 87 deletions(-) diff --git a/docs/backup-protocol.rst b/docs/backup-protocol.rst index 41a2e9f2..47f6a6bc 100644 --- a/docs/backup-protocol.rst +++ b/docs/backup-protocol.rst @@ -1,10 +1,10 @@ Backup Protocol =============== -Proxmox Backup Server uses a REST based API. While the management -interface use normal HTTP, the actual backup and restore interface use +Proxmox Backup Server uses a REST-based API. While the management +interface uses normal HTTP, the actual backup and restore interface uses HTTP/2 for improved performance. Both HTTP and HTTP/2 are well known -standards, so the following section assumes that you are familiar on +standards, so the following section assumes that you are familiar with how to use them. @@ -13,35 +13,35 @@ Backup Protocol API To start a new backup, the API call ``GET /api2/json/backup`` needs to be upgraded to a HTTP/2 connection using -``proxmox-backup-protocol-v1`` as protocol name:: +``proxmox-backup-protocol-v1`` as the protocol name:: GET /api2/json/backup HTTP/1.1 UPGRADE: proxmox-backup-protocol-v1 -The server replies with HTTP 101 Switching Protocol status code, -and you can then issue REST commands on that updated HTTP/2 connection. +The server replies with the ``HTTP 101 Switching Protocol`` status code, +and you can then issue REST commands on the updated HTTP/2 connection. The backup protocol allows you to upload three different kind of files: - Chunks and blobs (binary data) -- Fixed Indexes (List of chunks with fixed size) +- Fixed indexes (List of chunks with fixed size) -- Dynamic Indexes (List of chunk with variable size) +- Dynamic indexes (List of chunks with variable size) -The following section gives a short introduction how to upload such +The following section provides a short introduction on how to upload such files. Please use the `API Viewer `_ for -details about available REST commands. +details about the available REST commands. Upload Blobs ~~~~~~~~~~~~ -Uploading blobs is done using ``POST /blob``. The HTTP body contains the -data encoded as :ref:`Data Blob `). +Blobs are uploaded using ``POST /blob``. The HTTP body contains the +data encoded as :ref:`Data Blob `. -The file name needs to end with ``.blob``, and is automatically added -to the backup manifest. +The file name must end with ``.blob``, and is automatically added +to the backup manifest, following the call to ``POST /finish``. Upload Chunks @@ -56,40 +56,41 @@ encoded as :ref:`Data Blob `). Upload Fixed Indexes ~~~~~~~~~~~~~~~~~~~~ -Fixed indexes are use to store VM image data. The VM image is split +Fixed indexes are used to store VM image data. The VM image is split into equally sized chunks, which are uploaded individually. The index -file simply contains a list to chunk digests. +file simply contains a list of chunk digests. -You create a fixed index with ``POST /fixed_index``. Then upload +You create a fixed index with ``POST /fixed_index``. Then, upload chunks with ``POST /fixed_chunk``, and append them to the index with ``PUT /fixed_index``. When finished, you need to close the index using ``POST /fixed_close``. The file name needs to end with ``.fidx``, and is automatically added -to the backup manifest. +to the backup manifest, following the call to ``POST /finish``. Upload Dynamic Indexes ~~~~~~~~~~~~~~~~~~~~~~ -Dynamic indexes are use to store file archive data. The archive data +Dynamic indexes are used to store file archive data. The archive data is split into dynamically sized chunks, which are uploaded -individually. The index file simply contains a list to chunk digests +individually. The index file simply contains a list of chunk digests and offsets. -You create a dynamic sized index with ``POST /dynamic_index``. Then +You can create a dynamically sized index with ``POST /dynamic_index``. Then, upload chunks with ``POST /dynamic_chunk``, and append them to the index with ``PUT /dynamic_index``. When finished, you need to close the index using ``POST /dynamic_close``. -The file name needs to end with ``.didx``, and is automatically added -to the backup manifest. +The filename needs to end with ``.didx``, and is automatically added +to the backup manifest, following the call to ``POST /finish``. + Finish Backup ~~~~~~~~~~~~~ -Once you have uploaded all data, you need to call ``POST -/finish``. This commits all data and ends the backup protocol. +Once you have uploaded all data, you need to call ``POST /finish``. This +commits all data and ends the backup protocol. Restore/Reader Protocol API @@ -102,39 +103,39 @@ be upgraded to a HTTP/2 connection using GET /api2/json/reader HTTP/1.1 UPGRADE: proxmox-backup-reader-protocol-v1 -The server replies with HTTP 101 Switching Protocol status code, +The server replies with the ``HTTP 101 Switching Protocol`` status code, and you can then issue REST commands on that updated HTTP/2 connection. -The reader protocol allows you to download three different kind of files: +The reader protocol allows you to download three different kinds of files: - Chunks and blobs (binary data) -- Fixed Indexes (List of chunks with fixed size) +- Fixed indexes (list of chunks with fixed size) -- Dynamic Indexes (List of chunk with variable size) +- Dynamic indexes (list of chunks with variable size) -The following section gives a short introduction how to download such +The following section provides a short introduction on how to download such files. Please use the `API Viewer `_ for details about -available REST commands. +the available REST commands. Download Blobs ~~~~~~~~~~~~~~ -Downloading blobs is done using ``GET /download``. The HTTP body contains the +Blobs are downloaded using ``GET /download``. The HTTP body contains the data encoded as :ref:`Data Blob `. Download Chunks ~~~~~~~~~~~~~~~ -Downloading chunks is done using ``GET /chunk``. The HTTP body contains the -data encoded as :ref:`Data Blob `). +Chunks are downloaded using ``GET /chunk``. The HTTP body contains the +data encoded as :ref:`Data Blob `. Download Index Files ~~~~~~~~~~~~~~~~~~~~ -Downloading index files is done using ``GET /download``. The HTTP body +Index files are downloaded using ``GET /download``. The HTTP body contains the data encoded as :ref:`Fixed Index ` or :ref:`Dynamic Index `. diff --git a/docs/calendarevents.rst b/docs/calendarevents.rst index cffd124f..82e252fc 100644 --- a/docs/calendarevents.rst +++ b/docs/calendarevents.rst @@ -37,7 +37,7 @@ Each field can contain multiple values in the following formats: * and a combination of the above: e.g., 01,05..10,12/02 * or a `*` for every possible value: e.g., \*:00 -There are some special values that have specific meaning: +There are some special values that have a specific meaning: ================================= ============================== Value Syntax @@ -81,19 +81,19 @@ Not all features of systemd calendar events are implemented: * no Unix timestamps (e.g. `@12345`): instead use date and time to specify a specific point in time -* no timezone: all schedules use the set timezone on the server +* no timezone: all schedules use the timezone of the server * no sub-second resolution * no reverse day syntax (e.g. 2020-03~01) * no repetition of ranges (e.g. 1..10/2) -Notes on scheduling +Notes on Scheduling ------------------- -In `Proxmox Backup`_ scheduling for most tasks is done in the +In `Proxmox Backup`_, scheduling for most tasks is done in the `proxmox-backup-proxy`. This daemon checks all job schedules -if they are due every minute. This means that even if +every minute, to see if any are due. This means that even though `calendar events` can contain seconds, it will only be checked -once a minute. +once per minute. Also, all schedules will be checked against the timezone set in the `Proxmox Backup`_ server. diff --git a/docs/command-syntax.rst b/docs/command-syntax.rst index 3e3c8176..86dbd4a9 100644 --- a/docs/command-syntax.rst +++ b/docs/command-syntax.rst @@ -10,7 +10,7 @@ Command Syntax Catalog Shell Commands ~~~~~~~~~~~~~~~~~~~~~~ -Those command are available when you start an interactive restore shell: +The following commands are available in an interactive restore shell: .. code-block:: console diff --git a/docs/config/acl/format.rst b/docs/config/acl/format.rst index 82c61e44..a6f71500 100644 --- a/docs/config/acl/format.rst +++ b/docs/config/acl/format.rst @@ -2,13 +2,13 @@ This file contains the access control list for the Proxmox Backup Server API. Each line starts with ``acl:``, followed by 4 additional values -separated by collon. +separated by colon. -:propagate: Propagate permissions down the hierachrchy +:propagate: Propagate permissions down the hierarchy :path: The object path -:User/Token: List of users and token +:User/Token: List of users and tokens :Role: List of assigned roles diff --git a/docs/config/datastore/format.rst b/docs/config/datastore/format.rst index e93c86f2..858d7708 100644 --- a/docs/config/datastore/format.rst +++ b/docs/config/datastore/format.rst @@ -1,9 +1,9 @@ -The file contains a list of datastore configuration sections. Each -section starts with a header ``datastore: ``, followed by the +This file contains a list of datastore configuration sections. Each +section starts with the header ``datastore: ``, followed by the datastore configuration options. :: - + datastore: path diff --git a/docs/config/media-pool/format.rst b/docs/config/media-pool/format.rst index 5c7a08d9..21993c58 100644 --- a/docs/config/media-pool/format.rst +++ b/docs/config/media-pool/format.rst @@ -1,4 +1,4 @@ -Each entry starts with a header ``pool: ``, followed by the +Each entry starts with the header ``pool: ``, followed by the media pool configuration options. :: @@ -8,6 +8,6 @@ media pool configuration options. retention overwrite pool: ... - + You can use the ``proxmox-tape pool`` command to manipulate this file. diff --git a/docs/config/remote/format.rst b/docs/config/remote/format.rst index 1881e7d5..bfe34ac4 100644 --- a/docs/config/remote/format.rst +++ b/docs/config/remote/format.rst @@ -1,6 +1,6 @@ This file contains information used to access remote servers. -Each entry starts with a header ``remote: ``, followed by the +Each entry starts with the header ``remote: ``, followed by the remote configuration options. :: @@ -11,7 +11,7 @@ remote configuration options. ... remote: ... - + You can use the ``proxmox-backup-manager remote`` command to manipulate this file. diff --git a/docs/config/sync/format.rst b/docs/config/sync/format.rst index f6a01363..66b0caf5 100644 --- a/docs/config/sync/format.rst +++ b/docs/config/sync/format.rst @@ -1,4 +1,4 @@ -Each entry starts with a header ``sync: ``, followed by the +Each entry starts with the header ``sync: ``, followed by the job configuration options. :: @@ -9,7 +9,7 @@ job configuration options. remote lina sync: ... - + You can use the ``proxmox-backup-manager sync-job`` command to manipulate this file. diff --git a/docs/config/tape-job/format.rst b/docs/config/tape-job/format.rst index 6eaf60ad..aa773c7c 100644 --- a/docs/config/tape-job/format.rst +++ b/docs/config/tape-job/format.rst @@ -1,4 +1,4 @@ -Each entry starts with a header ``backup: ``, followed by the +Each entry starts with the header ``backup: ``, followed by the job configuration options. :: diff --git a/docs/config/tape/format.rst b/docs/config/tape/format.rst index 51687471..45d80f35 100644 --- a/docs/config/tape/format.rst +++ b/docs/config/tape/format.rst @@ -1,7 +1,7 @@ -Each LTO drive configuration section starts with a header ``lto: ``, +Each LTO drive configuration section starts with the header ``lto: ``, followed by the drive configuration options. -Tape changer configurations starts with ``changer: ``, +Tape changer configurations start with the header ``changer: ``, followed by the changer configuration options. :: @@ -18,5 +18,5 @@ followed by the changer configuration options. You can use the ``proxmox-tape drive`` and ``proxmox-tape changer`` commands to manipulate this file. -.. NOTE:: The ``virtual:`` drive type is experimental and onyl used +.. NOTE:: The ``virtual:`` drive type is experimental and should only be used for debugging. diff --git a/docs/config/user/format.rst b/docs/config/user/format.rst index e7da6dd3..eac654eb 100644 --- a/docs/config/user/format.rst +++ b/docs/config/user/format.rst @@ -1,9 +1,9 @@ This file contains the list of API users and API tokens. -Each user configuration section starts with a header ``user: ``, +Each user configuration section starts with the header ``user: ``, followed by the user configuration options. -API token configuration starts with a header ``token: +API token configuration starts with the header ``token: ``, followed by the token configuration. The data used to authenticate tokens is stored in a separate file (``token.shadow``). diff --git a/docs/config/verification/format.rst b/docs/config/verification/format.rst index dbe8bf84..859fb13a 100644 --- a/docs/config/verification/format.rst +++ b/docs/config/verification/format.rst @@ -1,4 +1,4 @@ -Each entry starts with a header ``verification: ``, followed by the +Each entry starts with the header ``verification: ``, followed by the job configuration options. :: diff --git a/docs/configuration-files.rst b/docs/configuration-files.rst index 6b21a111..047636a2 100644 --- a/docs/configuration-files.rst +++ b/docs/configuration-files.rst @@ -1,7 +1,7 @@ Configuration Files =================== -All Proxmox Backup Server configuration files resides inside directory +All Proxmox Backup Server configuration files reside in the directory ``/etc/proxmox-backup/``. diff --git a/docs/faq.rst b/docs/faq.rst index 94d48ab4..a4bd517a 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -69,6 +69,6 @@ be able to read the data. Is the backup incremental/deduplicated? --------------------------------------- -With Proxmox Backup Server, backups are sent incremental and data is -deduplicated on the server. -This minimizes both the storage consumed and the network impact. +With Proxmox Backup Server, backups are sent incrementally to the server, and +data is then deduplicated on the server. This minimizes both the storage +consumed and the impact on the network. diff --git a/docs/file-formats.rst b/docs/file-formats.rst index c1b2c79a..43ecfefc 100644 --- a/docs/file-formats.rst +++ b/docs/file-formats.rst @@ -14,7 +14,8 @@ Proxmox File Archive Format (``.pxar``) Data Blob Format (``.blob``) ---------------------------- -The data blob format is used to store small binary data. The magic number decides the exact format: +The data blob format is used to store small binary data. The magic number +decides the exact format: .. list-table:: :widths: auto @@ -32,7 +33,8 @@ The data blob format is used to store small binary data. The magic number decide - encrypted - compressed -Compression algorithm is ``zstd``. Encryption cipher is ``AES_256_GCM``. +The compression algorithm used is ``zstd``. The encryption cipher is +``AES_256_GCM``. Unencrypted blobs use the following format: @@ -43,9 +45,9 @@ Unencrypted blobs use the following format: * - ``CRC32: [u8; 4]`` * - ``Data: (max 16MiB)`` -Encrypted blobs additionally contains a 16 byte IV, followed by a 16 -byte Authenticated Encyryption (AE) tag, followed by the encrypted -data: +Encrypted blobs additionally contain a 16 byte initialization vector (IV), +followed by a 16 byte authenticated encryption (AE) tag, followed by the +encrypted data: .. list-table:: @@ -72,19 +74,19 @@ All numbers are stored as little-endian. * - ``ctime: i64``, - Creation Time (epoch) * - ``index_csum: [u8; 32]``, - - Sha256 over the index (without header) ``SHA256(digest1||digest2||...)`` + - SHA-256 over the index (without header) ``SHA256(digest1||digest2||...)`` * - ``size: u64``, - Image size * - ``chunk_size: u64``, - Chunk size * - ``reserved: [u8; 4016]``, - - overall header size is one page (4096 bytes) + - Overall header size is one page (4096 bytes) * - ``digest1: [u8; 32]`` - - first chunk digest + - First chunk digest * - ``digest2: [u8; 32]`` - - next chunk + - Second chunk digest * - ... - - next chunk ... + - Next chunk digest ... .. _dynamic-index-format: @@ -103,16 +105,16 @@ All numbers are stored as little-endian. * - ``ctime: i64``, - Creation Time (epoch) * - ``index_csum: [u8; 32]``, - - Sha256 over the index (without header) ``SHA256(offset1||digest1||offset2||digest2||...)`` + - SHA-256 over the index (without header) ``SHA256(offset1||digest1||offset2||digest2||...)`` * - ``reserved: [u8; 4032]``, - Overall header size is one page (4096 bytes) * - ``offset1: u64`` - End of first chunk * - ``digest1: [u8; 32]`` - - first chunk digest + - First chunk digest * - ``offset2: u64`` - End of second chunk * - ``digest2: [u8; 32]`` - - second chunk digest + - Second chunk digest * - ... - - next chunk offset/digest + - Next chunk offset/digest diff --git a/docs/glossary.rst b/docs/glossary.rst index 37e32a0e..98079723 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -11,7 +11,7 @@ Glossary `Container`_ A container is an isolated user space. Programs run directly on - the host's kernel, but with limited access to the host resources. + the host's kernel, but with limited access to the host's resources. Datastore @@ -23,19 +23,19 @@ Glossary Rust is a new, fast and memory-efficient system programming language. It has no runtime or garbage collector. Rust’s rich type system and ownership model guarantee memory-safety and - thread-safety. I can eliminate many classes of bugs + thread-safety. This can eliminate many classes of bugs at compile-time. `Sphinx`_ - Is a tool that makes it easy to create intelligent and - beautiful documentation. It was originally created for the - documentation of the Python programming language. It has excellent facilities for the + Is a tool that makes it easy to create intelligent and nicely formatted + documentation. It was originally created for the documentation of the + Python programming language. It has excellent facilities for the documentation of software projects in a range of languages. `reStructuredText`_ - Is an easy-to-read, what-you-see-is-what-you-get plaintext + Is an easy-to-read, what-you-see-is-what-you-get, plaintext markup syntax and parser system. `FUSE` diff --git a/docs/output-format.rst b/docs/output-format.rst index 79f8a10f..78611e16 100644 --- a/docs/output-format.rst +++ b/docs/output-format.rst @@ -1,5 +1,5 @@ -Most commands producing output supports the ``--output-format`` -parameter. It accepts the following values: +Most commands that produce output support the ``--output-format`` +parameter. This accepts the following values: :``text``: Text format (default). Structured data is rendered as a table. -- 2.30.2