[libvirt] [PATCH 03/21] backup: Document new XML for backups

[Eric Blake]

On 11/26/19 3:39 PM, Peter Krempa wrote:
> From: Eric Blake <eblake at redhat.com>
> 
> Prepare for new backup APIs by describing the XML that will represent
> a backup.  The XML resembles snapshots and checkpoints in being able
> to select actions for a set of disks, but has other differences.  It
> can support both push model (the hypervisor does the backup directly
> into the destination file) and pull model (the hypervisor exposes an
> access port for a third party to grab what is necessary).  Add
> testsuite coverage for some minimal uses of the XML.
> 
> The <disk> element within <domainbackup> tries to model the same
> elements as a <disk> under <domain>, but sharing the RNG grammar
> proved to be hairy. That is in part because while <domain> use
> <source> to describe a host resource in use by the guest, a backup job
> is using a host resource that is not visible to the guest: a push
> backup action is instead describing a <target> (which ultimately could
> be a remote network resource, but for simplicity the RNG just
> validates a local file for now), and a pull backup action is instead
> describing a temporary local file <scratch> (which probably should not
> be a remote resource).  A future refactoring may thus introduce some
> way to parameterize RNG to accept <disk type='FOO'>...</disk> so that
> the name of the subelement can be <source> for domain, or <target> or
> <scratch> as needed for backups. Future patches may improve this area
> of code.
> 
> Signed-off-by: Eric Blake <eblake at redhat.com>
> Signed-off-by: Peter Krempa <pkrempa at redhat.com>
> ---

It's odd reviewing my own patch ;)


> +    <dl>
> +      <dt><code>incremental</code></dt>
> +      <dd>An optional element giving the name of an existing
> +        checkpoint of the domain, which will be used to make this
> +        backup an incremental one. In the push model, only changes
> +        since the named checkpoint are written to the destination. In
> +        the pull model, the NBD server uses the
> +        NBD_OPT_SET_META_CONTEXT extension to advertise to the client
> +        which portions of the export contain changes since the named
> +        checkpoint. If omitted, a full backup is performed.
> +      </dd>

Given my comments on 1/21, it would not be hard to add a future 
attribute to control whether pull mode exposes only the differential or 
the entire image over the NBD server (corresponding to whether qemu 
allows the temp file to grow to the entire guest-visible size, or 
constrains non-dirty reads with EIO to limit the temp file to the bitmap 
size).

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