[libvirt] [PATCH v6 6/9] backup: Document new XML for backups

[Daniel P. Berrangé]

On Tue, Mar 26, 2019 at 01:13:50AM -0500, Eric Blake wrote:
> 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>
> ---
>  docs/docs.html.in                            |   3 +-
>  docs/format.html.in                          |   1 +
>  docs/formatbackup.html.in                    | 179 +++++++++++++++
>  docs/index.html.in                           |   3 +-
>  docs/schemas/domainbackup.rng                | 219 +++++++++++++++++++
>  libvirt.spec.in                              |   1 +
>  mingw-libvirt.spec.in                        |   2 +
>  tests/Makefile.am                            |   2 +
>  tests/domainbackupxml2xmlin/backup-pull.xml  |   9 +
>  tests/domainbackupxml2xmlin/backup-push.xml  |   9 +
>  tests/domainbackupxml2xmlin/empty.xml        |   1 +
>  tests/domainbackupxml2xmlout/backup-pull.xml |   9 +
>  tests/domainbackupxml2xmlout/backup-push.xml |   9 +
>  tests/domainbackupxml2xmlout/empty.xml       |   7 +
>  tests/virschematest.c                        |   2 +
>  15 files changed, 454 insertions(+), 2 deletions(-)
>  create mode 100644 docs/formatbackup.html.in
>  create mode 100644 docs/schemas/domainbackup.rng
>  create mode 100644 tests/domainbackupxml2xmlin/backup-pull.xml
>  create mode 100644 tests/domainbackupxml2xmlin/backup-push.xml
>  create mode 100644 tests/domainbackupxml2xmlin/empty.xml
>  create mode 100644 tests/domainbackupxml2xmlout/backup-pull.xml
>  create mode 100644 tests/domainbackupxml2xmlout/backup-push.xml
>  create mode 100644 tests/domainbackupxml2xmlout/empty.xml

Reviewed-by: Daniel P. Berrangé <berrange at redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|