141 lines
4.2 KiB
ReStructuredText
141 lines
4.2 KiB
ReStructuredText
Backup Protocol
|
|
===============
|
|
|
|
Proxmox Backup Server uses a REST based API. While the management
|
|
interface use normal HTTP, the actual backup and restore interface use
|
|
HTTP/2 for improved performance. Both HTTP and HTTP/2 are well known
|
|
standards, so the following section assumes that you are familiar on
|
|
how to use them.
|
|
|
|
|
|
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::
|
|
|
|
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 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 <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
|
|
---------------------------
|
|
|
|
To start a new reader, the API call ``GET /api2/json/reader`` needs to
|
|
be upgraded to a HTTP/2 connection using
|
|
``proxmox-backup-reader-protocol-v1`` as protocol name::
|
|
|
|
GET /api2/json/reader HTTP/1.1
|
|
UPGRADE: proxmox-backup-reader-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 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.
|
|
|
|
|
|
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).
|