diff --git a/docs/backup-protocol.rst b/docs/backup-protocol.rst index ec594c7c..27adcb1d 100644 --- a/docs/backup-protocol.rst +++ b/docs/backup-protocol.rst @@ -19,10 +19,77 @@ be upgraded to a HTTP/2 connection using UPGRADE: proxmox-backup-protocol-v1 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 `_ for details about -available REST commands. +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) + +- 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 `_ 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 @@ -36,7 +103,38 @@ be upgraded to a HTTP/2 connection using UPGRADE: proxmox-backup-reader-protocol-v1 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 `_ 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 `_ for details about 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).