docs/backup-protocol.rst

   1 Backup Protocol
   2 ===============
   3
   4 Proxmox Backup Server uses a REST based API. While the management
   5 interface use normal HTTP, the actual backup and restore interface use
   6 HTTP/2 for improved performance. Both HTTP and HTTP/2 are well known
   7 standards, so the following section assumes that you are familiar on
   8 how to use them.
   9
  10
  11 Backup Protocol API
  12 -------------------
  13
  14 To start a new backup, the API call ``GET /api2/json/backup`` needs to
  15 be upgraded to a HTTP/2 connection using
  16 ``proxmox-backup-protocol-v1`` as protocol name::
  17
  18   GET /api2/json/backup HTTP/1.1
  19   UPGRADE: proxmox-backup-protocol-v1
  20
  21 The server replies with HTTP 101 Switching Protocol status code,
  22 and you can then issue REST commands on that updated HTTP/2 connection.
  23
  24 The backup protocol allows you to upload three different kind of files:
  25
  26 - Chunks and blobs (binary data)
  27
  28 - Fixed Indexes (List of chunks with fixed size)
  29
  30 - Dynamic Indexes (List of chunk with variable size)
  31
  32 The following section gives a short introduction how to upload such
  33 files. Please use the `API Viewer <api-viewer/index.html>`_ for
  34 details about available REST commands.
  35
  36
  37 Upload Blobs
  38 ~~~~~~~~~~~~
  39
  40 Uploading blobs is done using ``POST /blob``. The HTTP body contains the
  41 data encoded as :ref:`Data Blob <data-blob-format>`).
  42
  43 The file name needs to end with ``.blob``, and is automatically added
  44 to the backup manifest.
  45
  46
  47 Upload Chunks
  48 ~~~~~~~~~~~~~
  49
  50 Chunks belong to an index, so you first need to open an index (see
  51 below). After that, you can upload chunks using ``POST /fixed_chunk``
  52 and ``POST /dynamic_chunk``. The HTTP body contains the chunk data
  53 encoded as :ref:`Data Blob <data-blob-format>`).
  54
  55
  56 Upload Fixed Indexes
  57 ~~~~~~~~~~~~~~~~~~~~
  58
  59 Fixed indexes are use to store VM image data. The VM image is split
  60 into equally sized chunks, which are uploaded individually. The index
  61 file simply contains a list to chunk digests.
  62
  63 You create a fixed index with ``POST /fixed_index``. Then upload
  64 chunks with ``POST /fixed_chunk``, and append them to the index with
  65 ``PUT /fixed_index``. When finished, you need to close the index using
  66 ``POST /fixed_close``.
  67
  68 The file name needs to end with ``.fidx``, and is automatically added
  69 to the backup manifest.
  70
  71
  72 Upload Dynamic Indexes
  73 ~~~~~~~~~~~~~~~~~~~~~~
  74
  75 Dynamic indexes are use to store file archive data. The archive data
  76 is split into dynamically sized chunks, which are uploaded
  77 individually. The index file simply contains a list to chunk digests
  78 and offsets.
  79
  80 You create a dynamic sized index with ``POST /dynamic_index``. Then
  81 upload chunks with ``POST /dynamic_chunk``, and append them to the index with
  82 ``PUT /dynamic_index``. When finished, you need to close the index using
  83 ``POST /dynamic_close``.
  84
  85 The file name needs to end with ``.didx``, and is automatically added
  86 to the backup manifest.
  87
  88 Finish Backup
  89 ~~~~~~~~~~~~~
  90
  91 Once you have uploaded all data, you need to call ``POST
  92 /finish``. This commits all data and ends the backup protocol.
  93
  94
  95 Restore/Reader Protocol API
  96 ---------------------------
  97
  98 To start a new reader, the API call ``GET /api2/json/reader`` needs to
  99 be upgraded to a HTTP/2 connection using
 100 ``proxmox-backup-reader-protocol-v1`` as protocol name::
 101
 102   GET /api2/json/reader HTTP/1.1
 103   UPGRADE: proxmox-backup-reader-protocol-v1
 104
 105 The server replies with HTTP 101 Switching Protocol status code,
 106 and you can then issue REST commands on that updated HTTP/2 connection.
 107
 108 The reader protocol allows you to download three different kind of files:
 109
 110 - Chunks and blobs (binary data)
 111
 112 - Fixed Indexes (List of chunks with fixed size)
 113
 114 - Dynamic Indexes (List of chunk with variable size)
 115
 116 The following section gives a short introduction how to download such
 117 files. Please use the `API Viewer <api-viewer/index.html>`_ for details about
 118 available REST commands.
 119
 120
 121 Download Blobs
 122 ~~~~~~~~~~~~~~
 123
 124 Downloading blobs is done using ``GET /download``. The HTTP body contains the
 125 data encoded as :ref:`Data Blob <data-blob-format>`.
 126
 127
 128 Download Chunks
 129 ~~~~~~~~~~~~~~~
 130
 131 Downloading chunks is done using ``GET /chunk``. The HTTP body contains the
 132 data encoded as :ref:`Data Blob <data-blob-format>`).
 133
 134
 135 Download Index Files
 136 ~~~~~~~~~~~~~~~~~~~~
 137
 138 Downloading index files is done using ``GET /download``. The HTTP body
 139 contains the data encoded as :ref:`Fixed Index <fixed-index-format>`
 140 or :ref:`Dynamic Index <dynamic-index-format>`.