docs/backup-protocol.rst

   1 Backup Protocol
   2 ===============
   3
   4 Proxmox Backup Server uses a REST-based API. While the management
   5 interface uses normal HTTP, the actual backup and restore interface uses
   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 with
   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 the protocol name::
  17
  18   GET /api2/json/backup HTTP/1.1
  19   UPGRADE: proxmox-backup-protocol-v1
  20
  21 The server replies with the ``HTTP 101 Switching Protocol`` status code,
  22 and you can then issue REST commands on the 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 chunks with variable size)
  31
  32 The following section provides a short introduction on how to upload such
  33 files. Please use the `API Viewer <api-viewer/index.html>`_ for
  34 details about the available REST commands.
  35
  36
  37 Upload Blobs
  38 ~~~~~~~~~~~~
  39
  40 Blobs are uploaded using ``POST /blob``. The HTTP body contains the
  41 data encoded as :ref:`Data Blob <data-blob-format>`.
  42
  43 The file name must end with ``.blob``, and is automatically added
  44 to the backup manifest, following the call to ``POST /finish``.
  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 used 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 of 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, following the call to ``POST /finish``.
  70
  71
  72 Upload Dynamic Indexes
  73 ~~~~~~~~~~~~~~~~~~~~~~
  74
  75 Dynamic indexes are used 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 of chunk digests
  78 and offsets.
  79
  80 You can create a dynamically 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 filename needs to end with ``.didx``, and is automatically added
  86 to the backup manifest, following the call to ``POST /finish``.
  87
  88
  89 Finish Backup
  90 ~~~~~~~~~~~~~
  91
  92 Once you have uploaded all data, you need to call ``POST /finish``. This
  93 commits all data and ends the backup protocol.
  94
  95
  96 Restore/Reader Protocol API
  97 ---------------------------
  98
  99 To start a new reader, the API call ``GET /api2/json/reader`` needs to
 100 be upgraded to a HTTP/2 connection using
 101 ``proxmox-backup-reader-protocol-v1`` as protocol name::
 102
 103   GET /api2/json/reader HTTP/1.1
 104   UPGRADE: proxmox-backup-reader-protocol-v1
 105
 106 The server replies with the ``HTTP 101 Switching Protocol`` status code,
 107 and you can then issue REST commands on that updated HTTP/2 connection.
 108
 109 The reader protocol allows you to download three different kinds of files:
 110
 111 - Chunks and blobs (binary data)
 112
 113 - Fixed indexes (list of chunks with fixed size)
 114
 115 - Dynamic indexes (list of chunks with variable size)
 116
 117 The following section provides a short introduction on how to download such
 118 files. Please use the `API Viewer <api-viewer/index.html>`_ for details about
 119 the available REST commands.
 120
 121
 122 Download Blobs
 123 ~~~~~~~~~~~~~~
 124
 125 Blobs are downloaded using ``GET /download``. The HTTP body contains the
 126 data encoded as :ref:`Data Blob <data-blob-format>`.
 127
 128
 129 Download Chunks
 130 ~~~~~~~~~~~~~~~
 131
 132 Chunks are downloaded using ``GET /chunk``. The HTTP body contains the
 133 data encoded as :ref:`Data Blob <data-blob-format>`.
 134
 135
 136 Download Index Files
 137 ~~~~~~~~~~~~~~~~~~~~
 138
 139 Index files are downloaded using ``GET /download``. The HTTP body
 140 contains the data encoded as :ref:`Fixed Index <fixed-index-format>`
 141 or :ref:`Dynamic Index <dynamic-index-format>`.