tyler/proxmox-backup
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: language fixup: faq and appendix

Browse Source 
minor formatting and language fixes to the faq section and the appendix

Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
This commit is contained in:
Dylan Whyte 2021-10-27 16:19:27 +02:00 committed by Dietmar Maurer
parent 9b1e2ae83c
commit 2bc1250c28
17 changed files with 90 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/backup-protocol.rst
View File

@ -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 <api-viewer/index.html>`_ 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 <data-blob-format>`).
Blobs are uploaded using ``POST /blob``. The HTTP body contains the
data encoded as :ref:`Data Blob <data-blob-format>`.
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 <data-blob-format>`).
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 <api-viewer/index.html>`_ 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 <data-blob-format>`.
Download Chunks
~~~~~~~~~~~~~~~
Downloading chunks is done using ``GET /chunk``. The HTTP body contains the
data encoded as :ref:`Data Blob <data-blob-format>`).
Chunks are downloaded using ``GET /chunk``. The HTTP body contains the
data encoded as :ref:`Data Blob <data-blob-format>`.
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 <fixed-index-format>`
or :ref:`Dynamic Index <dynamic-index-format>`.

12
docs/calendarevents.rst
View File

@ -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.

2
docs/command-syntax.rst
View File

@ -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

6
docs/config/acl/format.rst
View File

@ -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

6
docs/config/datastore/format.rst
View File

@ -1,9 +1,9 @@
The file contains a list of datastore configuration sections. Each
section starts with a header ``datastore: <name>``, followed by the
This file contains a list of datastore configuration sections. Each
section starts with the header ``datastore: <name>``, followed by the
datastore configuration options.
::
datastore: <name1>
path <path1>
<option1> <value1>

4
docs/config/media-pool/format.rst
View File

@ -1,4 +1,4 @@
Each entry starts with a header ``pool: <name>``, followed by the
Each entry starts with the header ``pool: <name>``, 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.

4
docs/config/remote/format.rst
View File

@ -1,6 +1,6 @@
This file contains information used to access remote servers.
Each entry starts with a header ``remote: <name>``, followed by the
Each entry starts with the header ``remote: <name>``, 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.

4
docs/config/sync/format.rst
View File

@ -1,4 +1,4 @@
Each entry starts with a header ``sync: <name>``, followed by the
Each entry starts with the header ``sync: <name>``, 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.

2
docs/config/tape-job/format.rst
View File

@ -1,4 +1,4 @@
Each entry starts with a header ``backup: <name>``, followed by the
Each entry starts with the header ``backup: <name>``, followed by the
job configuration options.
::

6
docs/config/tape/format.rst
View File

@ -1,7 +1,7 @@
Each LTO drive configuration section starts with a header ``lto: <name>``,
Each LTO drive configuration section starts with the header ``lto: <name>``,
followed by the drive configuration options.
Tape changer configurations starts with ``changer: <name>``,
Tape changer configurations start with the header ``changer: <name>``,
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.

4
docs/config/user/format.rst
View File

@ -1,9 +1,9 @@
This file contains the list of API users and API tokens.
Each user configuration section starts with a header ``user: <name>``,
Each user configuration section starts with the header ``user: <name>``,
followed by the user configuration options.
API token configuration starts with a header ``token:
API token configuration starts with the header ``token:
<userid!token_name>``, followed by the token configuration. The data
used to authenticate tokens is stored in a separate file
(``token.shadow``).

2
docs/config/verification/format.rst
View File

@ -1,4 +1,4 @@
Each entry starts with a header ``verification: <name>``, followed by the
Each entry starts with the header ``verification: <name>``, followed by the
job configuration options.
::

2
docs/configuration-files.rst
View File

@ -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/``.

6
docs/faq.rst
View File

@ -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.

30
docs/file-formats.rst
View File

@ -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

12
docs/glossary.rst
View File

@ -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`

4
docs/output-format.rst
View File

@ -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.