[libvirt] [PATCH v2 04/25] backup: Document new XML for backups

[Ján Tomko]

On Tue, Dec 03, 2019 at 06:17:26PM +0100, 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>
>---
> docs/docs.html.in                             |   3 +-
> docs/format.html.in                           |   1 +
> docs/formatbackup.html.in                     | 175 ++++++++++++++
> docs/formatcheckpoint.html.in                 |  12 +-
> docs/index.html.in                            |   3 +-
> docs/schemas/domainbackup.rng                 | 223 ++++++++++++++++++
> libvirt.spec.in                               |   1 +
> mingw-libvirt.spec.in                         |   2 +
> tests/Makefile.am                             |   1 +
> .../backup-pull-seclabel.xml                  |  18 ++
> tests/domainbackupxml2xmlin/backup-pull.xml   |  10 +
> .../backup-push-seclabel.xml                  |  17 ++
> tests/domainbackupxml2xmlin/backup-push.xml   |  10 +
> tests/domainbackupxml2xmlin/empty.xml         |   1 +
> tests/virschematest.c                         |   1 +
> 15 files changed, 470 insertions(+), 8 deletions(-)
> create mode 100644 docs/formatbackup.html.in
> create mode 100644 docs/schemas/domainbackup.rng
> create mode 100644 tests/domainbackupxml2xmlin/backup-pull-seclabel.xml
> create mode 100644 tests/domainbackupxml2xmlin/backup-pull.xml
> create mode 100644 tests/domainbackupxml2xmlin/backup-push-seclabel.xml
> create mode 100644 tests/domainbackupxml2xmlin/backup-push.xml
> create mode 100644 tests/domainbackupxml2xmlin/empty.xml
>
>diff --git a/docs/formatbackup.html.in b/docs/formatbackup.html.in
>new file mode 100644
>index 0000000000..d2e4609c1c
>--- /dev/null
>+++ b/docs/formatbackup.html.in
>@@ -0,0 +1,175 @@

[...]

>+    <h2><a id="example">Examples</a></h2>
>+
>+    <p>Use <code>virDomainBackupBegin()</code> to perform a full
>+      backup using push mode. The example lets libvirt pick the
>+      destination and format for 'vda', fully specifies that we want a
>+      raw backup of 'vdb', and omits 'vdc' from the operation.
>+    </p>
>+    <pre>
>+<domainbackup>
>+  <disks/>
extra slash -^

>+    <disk name='vda' backup='yes'/>
>+    <disk name='vdb' type='file'>
>+      <target file='/path/to/vdb.backup'/>
>+      <driver type='raw'/>
>+    </disk>
>+    <disk name='vdc' backup='no'/>
>+  </disks/>
here too -----^

>+</domainbackup>
>+    </pre>
>+
>+    <p>If the previous full backup also passed a parameter describing
>+      <a href="formatcheckpoint.html">checkpoint XML</a> that resulted
>+      in a checkpoint named <code>1525889631</code>, we can make
>+      another call to <code>virDomainBackupBegin()</code> to perform
>+      an incremental backup of just the data changed since that
>+      checkpoint, this time using the following XML to start a pull
>+      model export of the 'vda' and 'vdb' disks, where a third-party
>+      NBD client connecting to '/path/to/server' completes the backup
>+      (omitting 'vdc' from the explicit list has the same effect as
>+      the backup='no' from the previous example):
>+    </p>
>+    <pre>
>+<domainbackup mode="pull">
>+  <incremental>1525889631</incremental>
>+  <server transport="unix" socket="/path/to/server"/>
>+  <disks/>
here too ----^

>+    <disk name='vda' backup='yes' type='file'>
>+      <scratch file='/path/to/file1.scratch'/>
>+    </disk>
>+  </disks/>
here too -----^
>+</domainbackup>
>+    </pre>
>+  </body>
>+</html>

With that fixed:
Reviewed-by: Ján Tomko <jtomko at redhat.com>

Jano
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20191209/eb569888/attachment-0001.sig>