Virtuozzo Backup/Restore API

Overview

The Virtuozzo API provides the backup and restore capabilities using block snapshots and block export. Block export is used to provide access to the captured state of a block device so it can be backed up. Currently only access over the NBD protocol is supported. Also block export is used for restore to provide access to domain's block device so it can be written from a previously backed up state.

Note that this API is only available in the version of libvirt shipped with Virtuozzo Hybrid Server. The respective API call names and XML are marked with the letter X.

A block snapshot (which may also be called a temporary snapshot) is used to capture the state of the block device to be backed up. A regular external snapshot creates a new image with the data written to the block device after the snapshot is created; and the original image holds the state of the block device at the moment when the snapshot was taken. A block snapshot is different. It also uses an extra image, but the data written to the block device after taking the snapshot still goes to the original image. The data to be overwritten in the original image is pushed to the extra image. So the extra image backed by the original image holds the snapshot. When backing up, a snapshot is only needed while a backup is being created and is usually discarded afterwards. Deleting a block snapshot is as easy as discarding an extra image. With a regular external snapshot, however, the changes made after taking the snapshot need to be commited to the original image.

The backup procedure goes as follows:

  1. virDomainBlockSnapshotXCreate is called to create a block snapshot of the specified block devices.
  2. virDomainBlockExportXStart is called to export the block snapshot over the NBD protocol to be backed up.
  3. The backup software creates a backup.
  4. Once the backup is created, virDomainBlockExportXStop is called to finish exporting.
  5. virDomainBlockSnapshotXDelete is called to delete the now unneeded block snapshot.

Making a full backup of block devices every time is suboptimal. The Virtuozzo backup API allows making incremental or differential backups. Each time a block snapshot is created, a checkpoint can be created as well. Specify it during a block export and the information about blocks changed between the checkpoint and the current snapshot will be provided as well from the changed blocks table (CBT).

For example, create a full backup and a checkpoint first. Next, when creating the next backup, use this checkpoint to obtain the difference between the first snapshot and the current snapshot and create a backup of only that difference.

Checkpoints are not deleted when a block snapshot is deleted, so block snapshots can be deleted after backup as usual. Checkpoints can be deleted with virDomainBlockCheckpointXRemove.

When restoring a backup, the domain needs to be started in the paused mode first. Then export the block devices of interest over NBD using virDomainBlockExportXStart. Block devices are writeable during export, so one can write them from a previously saved backup. The checkpoints are also available on restore, so one can transfer only the parts that have changed since the backup. After the restore is finished, call virDomainBlockExportXStop to stop the export, same as for backup. Now the domain can be unpaused and started or destroyed (if its target state is shut down).

Block Snapshot XML 

    <domainblocksnapshot>
      <name>5b30f0e0-690b-43ea-bad3-3e77f2f478cd</name>
      <disk name="sda">
        <fleece file="/tmp/centos-sda.qcow2"/>
      </disk>
      <disk name="sdb">
        <fleece file="/tmp/centos-sdb.qcow2"/>
      </disk>
    </domainblocksnapshot>
name
Optional snapshot ID. If not set, it will be generated as a UUID. If checkpoint creation is requested for the snapshot, the checkpoint will have the same ID.
disk
Represents a block snapshot of a single disk.
fleece
Describes the image that holds the snapshot data. file is the path to that image.

Block Export XML 

    <domainblockexport type="nbd">
      <address type="ip" host="0.0.0.0" port="8080"/>
      <disk name="sda" snapshot="d599e5fd-5fe2-4393-8abd-6a3539a4d30e"
                       checkpoint="5b30f0e0-690b-43ea-bad3-3e77f2f478cd"
                       exportname="sda-d599e5fd-5fe2-4393-8abd-6a3539a4d30e"
                       readonly="yes"/>
      <disk name="sdb" snapshot="d599e5fd-5fe2-4393-8abd-6a3539a4d30e"
                       checkpoint="5b30f0e0-690b-43ea-bad3-3e77f2f478cd"
                       exportname="sdb-d599e5fd-5fe2-4393-8abd-6a3539a4d30e"
                       readonly="yes"/>
    </domainblockexport>
type
Export protocol for the block devices. Currently only nbd is supported.
address
Export interface. Currently only the ip type is supported. It stands for an IPv4 server socket specified by host and port.
disk
Describes the export options for a single disk.
name
Disk name which corresponds to target[@dev] of the disk element in the domain XML.
snapshot
Optional snapshot ID. If set, the snapshot with the specified ID will be exported instead of the block device itself.
checkpoint
Optional checkpoint ID. If set, the bitmap of blocks changed since the given checkpoint (i.e. the CBT) will be available in the export protocol.
readonly
An optional boolean parameter which specifies the access mode for the block device or its snapshot. If set to yes, block data will be read-only. If set to no, it will be both readable and writeable. The default value is yes for exported snapshots and no for exported block devices.
exportname
A readonly attribute available only in introspection. It specifies the ID used to identify the block device or its snapshot over the NBD protocol.

Introspection

Block snapshots can be listed with virDomainBlockSnapshotXList. If the snapshot ID is known, a reference to the snapshot can be obtained with virDomainBlockSnapshotXLookupByName. The XML description for a snapshot can be obtained with virDomainBlockSnapshotXGetXMLDesc

The current block exports are visible in domain XML in the devices section under the element x-blockexport. Note that it is different from domainblockexport mentioned above. Currently only a single NBD server export address is supported, so there can be only one block export element.

Checkpoint information is available per disk. For every checkpoint there is an x-checkpoint element with the checkpoint ID. Checkpoint information is available for active domains only.