Backup Protocol

Proxmox Backup Server uses a REST-based API. While the management interface uses normal HTTP, the actual backup and restore interface uses HTTP/2 for improved performance. Both HTTP and HTTP/2 are well known standards, so the following section assumes that you are familiar with 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 the protocol name:

GET /api2/json/backup HTTP/1.1
UPGRADE: proxmox-backup-protocol-v1

The server replies with the HTTP 101 Switching Protocol status code, and you can then issue REST commands on the 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 chunks with variable size)

The following section provides a short introduction on how to upload such files. Please use the API Viewer for details about the available REST commands.

Upload Blobs

Blobs are uploaded using POST /blob. The HTTP body contains the data encoded as Data Blob.

The file name must end with .blob, and is automatically added to the backup manifest, following the call to POST /finish.

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 Data Blob).

Upload Fixed Indexes

Fixed indexes are used 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 of 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, following the call to POST /finish.

Upload Dynamic Indexes

Dynamic indexes are used 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 of chunk digests and offsets.

You can create a dynamically 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 filename needs to end with .didx, and is automatically added to the backup manifest, following the call to POST /finish.

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 the 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 kinds of files:

  • Chunks and blobs (binary data)

  • Fixed indexes (list of chunks with fixed size)

  • Dynamic indexes (list of chunks with variable size)

The following section provides a short introduction on how to download such files. Please use the API Viewer for details about the available REST commands.

Download Blobs

Blobs are downloaded using GET /download. The HTTP body contains the data encoded as Data Blob.

Download Chunks

Chunks are downloaded using GET /chunk. The HTTP body contains the data encoded as Data Blob.

Download Index Files

Index files are downloaded using GET /download. The HTTP body contains the data encoded as Fixed Index or Dynamic Index.