Proxmox/proxmox-backup
5
0
Fork 0
mirror of git://git.proxmox.com/git/proxmox-backup.git synced 2025-02-10 13:57:40 +03:00
Code Releases Activity

docs: improve backup protocol docs

Browse Source
This commit is contained in:
Dietmar Maurer 2021-02-28 09:07:13 +01:00
parent 7eb9f48485
commit 5006632550
1 changed files with 103 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
docs/backup-protocol.rst
View File

@ -19,10 +19,77 @@ be upgraded to a HTTP/2 connection using
UPGRADE: proxmox-backup-protocol-v1 UPGRADE: proxmox-backup-protocol-v1
The server replies with HTTP 101 Switching Protocol status code, The server replies with HTTP 101 Switching Protocol status code,
and you can then issue REST command on that updated HTTP/2 connection. and you can then issue REST commands on that updated HTTP/2 connection.
Please use the `API Viewer <api-viewer/index.html>`_ for details about The backup protocol allows you to upload three different kind of files:
available REST commands.
- Chunks and blobs (binary data)
- Fixed Indexes (List of chunks with fixed size)
- Dynamic Indexes (List of chunk with variable size)
The following section gives a short introduction how to upload such
files. Please use the `API Viewer <api-viewer/index.html>`_ for
details about available REST commands.
Upload Blobs
~~~~~~~~~~~~
Uploading blobs is done using ``POST /blob``. The HTTP body contains the
data encoded as ``DataBlob`` (see source code).
The file name needs to end with ``.blob``, and is automatically added
to the backup manifest.
Upload Chunks
~~~~~~~~~~~~~
Chunks belong to an index, so you first need to open an index (see
below). After that, you can upload chunks using ``POST /fixed_chunk``
and ``POST /dynamic_chunk``. The HTTP body contains the chunk data
encoded as ``DataBlob`` (see source code).
Upload Fixed Indexes
~~~~~~~~~~~~~~~~~~~~
Fixed indexes are use 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.
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.
Upload Dynamic Indexes
~~~~~~~~~~~~~~~~~~~~~~
Dynamic indexes are use 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
and offsets.
You create a dynamic 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.
Finish Backup
~~~~~~~~~~~~~
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 Restore/Reader Protocol API
@ -36,7 +103,38 @@ be upgraded to a HTTP/2 connection using
UPGRADE: proxmox-backup-reader-protocol-v1 UPGRADE: proxmox-backup-reader-protocol-v1
The server replies with HTTP 101 Switching Protocol status code, The server replies with HTTP 101 Switching Protocol status code,
and you can then issue REST command on that updated HTTP/2 connection. and you can then issue REST commands on that updated HTTP/2 connection.
Please use the `API Viewer <api-viewer/index.html>`_ for details about The reader protocol allows you to download three different kind of files:
- Chunks and blobs (binary data)
- Fixed Indexes (List of chunks with fixed size)
- Dynamic Indexes (List of chunk with variable size)
The following section gives a short introduction how to download such
files. Please use the `API Viewer <api-viewer/index.html>`_ for details about
available REST commands. available REST commands.
Download Blobs
~~~~~~~~~~~~~~
Downloading blobs is done using ``GET /download``. The HTTP body contains the
data encoded as ``DataBlob`` (see source code).
Download Chunks
~~~~~~~~~~~~~~~
Downloading chunks is done using ``GET /chunk``. The HTTP body contains the
data encoded as ``DataBlob`` (see source code).
Download Index Files
~~~~~~~~~~~~~~~~~~~~
Downloading index files is done using ``GET /download``. The HTTP body
contains the data encoded as ``FixedIndex`` or ``DynamicIndex`` (see
source code).