[libvirt] [PATCH 04/21] backup: Introduce virDomainBackup APIs

[Eric Blake]

On 11/26/19 3:39 PM, Peter Krempa wrote:
> From: Eric Blake <eblake at redhat.com>
> 
> Introduce a few new public APIs related to incremental backups.  This
> builds on the previous notion of a checkpoint (without an existing
> checkpoint, the new API is a full backup, differing from
> virDomainBlockCopy in the point of time chosen and in operation on
> multiple disks at once); and also allows creation of a new checkpoint
> at the same time as starting the backup (after all, an incremental
> backup is only useful if it covers the state since the previous
> backup).
> 
> A backup job also affects filtering a listing of domains, as well as
> adding event reporting for signaling when a push model backup
> completes (where the hypervisor creates the backup); note that the
> pull model does not have an event (starting the backup lets a third
> party access the data, and only the third party knows when it is
> finished).
> 
> The full list of new APIs:
>          virDomainBackupBegin;
>          virDomainBackupGetXMLDesc;
> 
> Signed-off-by: Eric Blake <eblake at redhat.com>
> Signed-off-by: Peter Krempa <pkrempa at redhat.com>

The cover letter mentions obvious changes from when I wrote this: no job 
id parameter, and reuse existing abort job API instead of adding 
virDomainBackupEnd.  We'll still have to revisit how a decent job API 
addition down the road affects things, but I can live with this API for 
the short term use of only one backup job at a time.

> +
> +/**
> + * virDomainBackupBegin:
> + * @domain: a domain object
> + * @backupXML: description of the requested backup
> + * @checkpointXML: description of a checkpoint to create or NULL
> + * @flags: unused; callers must pass 0
> + *
> + * Start a point-in-time backup job for the specified disks of a
> + * running domain.
> + *
> + * A backup job is a domain job and thus mutually exclusive with any other
> + * domain job such as migration.

A limitation we hope to lift later with a proper job API, but not a 
show-stopper for this interface.

> + *
> + * For now, backup jobs are also mutually exclusive with any
> + * other block job on the same device, although this restriction may
> + * be lifted in a future release. Progress of the backup job can be
> + * tracked via virDomainGetJobStats(). Completion of the job is also announced
> + * asynchronously via VIR_DOMAIN_EVENT_ID_JOB_COMPLETED event.

Is that true for pull mode, or only for push mode?  With push mode, it's 
obvious when the event is needed - when qemu finishes pushing.  But in 
pull mode, the only time an event makes sense is when you finally abort 
the job and the NBD server goes away - but as that is always an explicit 
libvirt API call, does the event still make sense?

> + *
> + * There are two fundamental backup approaches. The first, called a
> + * push model, instructs the hypervisor to copy the state of the guest
> + * disk to the designated storage destination (which may be on the
> + * local file system or a network device). In this mode, the
> + * hypervisor writes the content of the guest disk to the destination,
> + * then emits VIR_DOMAIN_EVENT_ID_JOB_COMPLETED when the backup is
> + * either complete or failed (the backup image is invalid if the job
> + * fails or virDomainAbortJob() is used prior to the event being
> + * emitted). This kind of the job finishes automatically. Users can
> + * determine success by using virDomainGetJobStats() with
> + * VIR_DOMAIN_JOB_STATS_COMPLETED flag.
> + *
> + * The second, called a pull model, instructs the hypervisor to expose
> + * the state of the guest disk over an NBD export. A third-party
> + * client can then connect to this export and read whichever portions
> + * of the disk it desires.  In this mode libvir has to be informed via

libvirt

> + * virDomainAbortJob() when the third-party NBD client is done and the backup
> + * resources can be released.
> + *
> + * The @backupXML parameter contains details about the backup in the top-level
> + * element <domainbackup> , including which backup mode to use, whether the

no space before comma

> + * backup is incremental from a previous checkpoint, which disks
> + * participate in the backup, the destination for a push model backup,
> + * and the temporary storage and NBD server details for a pull model
> + * backup.
> + *
> + * virDomainBackupGetXMLDesc() can be called to learn actual
> + * values selected.  For more information, see
> + * formatcheckpoint.html#BackupAttributes.
> + *
> + * The @checkpointXML parameter is optional; if non-NULL, then libvirt
> + * behaves as if virDomainCheckpointCreateXML() were called to create
> + * a checkpoint atomically covering the same point in time as the
> + * backup.
> + * The creation of a new checkpoint allows for future incremental backups.
> + * Note that some hypervisors may require a particular disk format, such as
> + * qcow2, in order to take advantage of checkpoints, while allowing arbitrary
> + * formats if checkpoints are not involved.
> + *
> + * Returns 0 on success or -1 on failure.
> + */

> +/**
> + * virDomainBackupGetXMLDesc:
> + * @domain: a domain object
> + * @flags: extra flags; not used yet, so callers should always pass 0
> + *
> + * Queries the configuration of the active backup job.
> + *
> + * In some cases, a user can start a backup job without supplying all
> + * details and rely on libvirt to fill in the rest (for example,
> + * selecting the port used for an NBD export). This API can then be
> + * used to learn what default values were chosen.
> + *
> + * Returns a NUL-terminated UTF-8 encoded XML instance or NULL in
> + * case of error.  The caller must free() the returned value.
> + */

Do we need any further tweaks to the virDomainAbortJob() API to mention 
that it is used to end a backup?

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org