Applications based on libvirt such as OpenStack need some public APIs
about export/import of external snapshot during daily backup, snapshot
recovery or system migration. virDomainSnapshotDiskExport,
virDomainSnapshotVmstateExport and virDomainSnapshotImport are designed
to satisfy such requirement.



@flags: virDomainSnapshotExportImportFlags include,
        DATA_FULL: all data snapshot
        DATA_DELTA: delta data only



/**
 * virDomainSnapshotDiskExport
 * @domain: the domain object to be exported snapshot
 * @id: top Overlays which to be exported
 * @base_id: RootBase of snapshot to be exported
 * @disk: block device of domain
 * @export_path: path of snapshots export
 * @flags: bitwise-OR of virDomainSnapshotExportImportFlags
 *
 * Import snapshot disk data to the pointed path.
 *
 * If @flags includes DATA_FULL, full backup snapshot will be exported.
 *
 * If @flags includes DATA_DELTA, incremental backup snapshot will be
 * exported.
 *
 * DATA_FULL and DATA_DELTA should not appear at the same time
 *
 * Returns 0 on success, or -1 on error
 */
int virDomainSnapshotDiskExport(virDomain *domain,
                                virSnapshotId *id,
                                virSnapshotId *base_id,
                                virDevice *disk,
                                char *export_path,
                                unsigned int flags)

Usage: export external snapshot disk file from virtual machine to the
       target path.



/**
 * virDomainSnapshotVmstateExport
 * @domain: the domain object to be exported snapshot
 * @id: top Overlays which to be exported
 * @export_path: path of snapshots export
 * @flags: not used yet, so callers should always pass 0
 *
 * Import snapshot vmstate data to the pointed path.
 *
 * If @flags includes DATA_FULL, full backup snapshot will be exported.
 *
 * If @flags includes DATA_DELTA, incremental backup snapshot will be
 * exported.
 *
 * DATA_FULL and DATA_DELTA should not appear at the same time
 *
 * Returns 0 on success, or -1 on error
 */
int virDomainSnapshotVmstateExport(virDomain *domain,
                                   virSnapshotId *id,
                                   char *export_path,
                                   unsigned int flags)

Usage: dump vmstate file of snapshot and copy it to the target path.



/**
 * virDomainSnapshotImport
 * @domain: the domain object to be exported snapshot
 * @xmlDesc: string containing an XML description of the domain
 * @flags: bitwise-OR of virDomainSnapshotExportImportFlags
 *
 * Import snapshot data to the pointed path.
 *
 * If @flags includes DATA_FULL, full backup snapshot will be exported.
 *
 * If @flags includes DATA_DELTA, incremental backup snapshot will be
 * exported.
 *
 * DATA_FULL and DATA_DELTA should not appear at the same time
 *
 * Returns 0 on success, or -1 on error
 */
int virDomainSnapshotImport(virDomain *domain,
                            const char *xmlDesc,
                            unsigned int flags)

Usage: import .xml file of external snapshot and use it for recovering
       a virtual machine.



Usecase:
  If users want to finish daily backup&recovery work by above APIs,
the process should be,
  1. call virDomainSnapshotDiskExport() to export pointed snapshot
disk files to the traget path.

  -------------------                         ---------------------
  |    host A       |                         |    host B         |
  | --------------- |                         | ----------------- |
  | | dom1        | |   snapshot disk files   | | backup folder | |
  | | base.img----------------------------------->base.img      | |
  | | snap1.qcow2-------------------------------->snap1.qcow2   | |
  | | snap2.qcow2-------------------------------->snap2.qcow2   | |
  | --------------- |                         | ----------------- |
  -------------------                         ---------------------
                  virDomainSnapshotDiskSnapshot()

  2. call virDomainSnapshotVmstateExport() to export vmstate data
file to the target path.

  ---------------                         ---------------------
  |   host A    |                         |    host B         |
  | ----------- |                         | ----------------- |
  | | dom1    | |   vmstate data files    | | backup folder | |
  | | dumpxml-------------------------------->vmstate.xml   | |
  | ----------- |                         | ----------------- |
  ---------------                         ---------------------
             virDomainSnapshotVmstateSnapshot()

  3. when some error occured, or guest copy/migration, users copy
snapshot disk files from host B to the target host and edit <source
file> field of <disk> tag. Then users call virDomainSnapshotImport
to recovery domain to the snapshot.

  a. copy snapshot disk files to the target host:
  -------------------------------             ---------------------
  |    host A                   |  snapshot   |    host B         |
  | --------------------------- |   disk      | ----------------- |
  | | /var/lib/libvirt/images | |   files     | | backup folder | |
  | | base.img<-----------------------------------base.img      | |
  | | snap1.qcow2<--------------------------------snap1.qcow2   | |
  | | snap2.qcow2<--------------------------------snap2.qcow2   | |
  | --------------------------- |             | ----------------- |
  -------------------------------             ---------------------
                          snapshot disk files transfer

  b. import vmstate data to recovery snapshot:
                                      ---------------------
  -------------------                 |    host B         |
  |     host A      |                 | ----------------- |
  | --------------- |   vmstate data  | | backup folder | |
  | | dom1<-------------------------------vmstate.xml   | |
  | | base.img    | |                 | ----------------- |
  | | snap1.qcow2 | |                 ---------------------
  | | snap2.qcow2 | |
  | --------------- |
  -------------------
                virDomainSnapshotImport()