[libvirt] [PATCH v3 12/18] domain: Add VIR_DOMAIN_XML_SNAPSHOTS flag

[Eric Blake]

Right now, copying the state of a transient domain with snapshots
from one host to another requires multiple API calls on both
machines - on the host: get the domain XML, get a list of the
snapshots, and then for each snapshot get the snapshot's XML;
then on the destination: create the domain, then multiple
domain snapshot create calls with the REDEFINE flag.  This
patch aims to make the process use fewer APIs by making it
possible to grab the XML for all snapshots at the same time as
grabbing the domain XML.  Note that we had to do the modification
to virDomainGetXMLDesc(), rather than virDomainSnapshotGetXMLDesc(),
since the latter requires a single non-NULL snapshot object,
whereas we want the list of all snapshots for the domain (even
if the list has 0 elements).

Once wired up in drivers in later patches, the new information
is provided as:

<domain ...>
  ...
  </devices>
  <snapshots current='name'>
    <domainsnapshot>
      ...
    </domainsnapshot>
    <domainsnapshot>
      ...
    </domainsnapshot>
  </snapshots>
</domain>

For now, I did not modify the schema to permit this information
during virDomainDefineXML; it is still necessary to use
virDomainSnapshotCreateXML with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE
multiple times to recreate the added state output here.

Unfortunately, libvirt versions between 1.2.12 and 5.0.0 will
silently ignore the new flag, rather than diagnosing that they
don't support it; but at least silent lack of snapshots from
an older server is not a security hole.

Signed-off-by: Eric Blake <eblake at redhat.com>
Reviewed-by: John Ferlan <jferlan at redhat.com>
---
 include/libvirt/libvirt-domain.h |  1 +
 src/conf/domain_conf.c           | 13 ++++++++-----
 src/libvirt-domain.c             |  8 +++++++-
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 1d5bdb545d..a8ebb68388 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -1570,6 +1570,7 @@ typedef enum {
     VIR_DOMAIN_XML_INACTIVE     = (1 << 1), /* dump inactive domain information */
     VIR_DOMAIN_XML_UPDATE_CPU   = (1 << 2), /* update guest CPU requirements according to host CPU */
     VIR_DOMAIN_XML_MIGRATABLE   = (1 << 3), /* dump XML suitable for migration */
+    VIR_DOMAIN_XML_SNAPSHOTS    = (1 << 4), /* include all snapshots in the dump */
 } virDomainXMLFlags;

 typedef enum {
diff --git a/src/conf/domain_conf.c b/src/conf/domain_conf.c
index f383f00b8b..2cf12e4d95 100644
--- a/src/conf/domain_conf.c
+++ b/src/conf/domain_conf.c
@@ -28674,11 +28674,12 @@ virDomainDefFormatInternal(virBufferPtr buf,
     return -1;
 }

-/* Converts VIR_DOMAIN_XML_COMMON_FLAGS into VIR_DOMAIN_DEF_FORMAT_*
- * flags, and silently ignores any other flags.  Note that the caller
- * should validate the set of flags it is willing to accept; see also
- * the comment on VIR_DOMAIN_XML_COMMON_FLAGS about security
- * considerations with adding new flags. */
+/* Converts VIR_DOMAIN_XML_COMMON_FLAGS and VIR_DOMAIN_XML_SNAPSHOTS
+ * into VIR_DOMAIN_DEF_FORMAT_* flags, and silently ignores any other
+ * flags.  Note that the caller should validate the set of flags it is
+ * willing to accept; see also the comment on
+ * VIR_DOMAIN_XML_COMMON_FLAGS about security considerations with
+ * adding new flags. */
 unsigned int virDomainDefFormatConvertXMLFlags(unsigned int flags)
 {
     unsigned int formatFlags = 0;
@@ -28689,6 +28690,8 @@ unsigned int virDomainDefFormatConvertXMLFlags(unsigned int flags)
         formatFlags |= VIR_DOMAIN_DEF_FORMAT_INACTIVE;
     if (flags & VIR_DOMAIN_XML_MIGRATABLE)
         formatFlags |= VIR_DOMAIN_DEF_FORMAT_MIGRATABLE;
+    if (flags & VIR_DOMAIN_XML_SNAPSHOTS)
+        formatFlags |= VIR_DOMAIN_DEF_FORMAT_SNAPSHOTS;

     return formatFlags;
 }
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 072b92b717..c886e0bdbe 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -1,7 +1,7 @@
 /*
  * libvirt-domain.c: entry points for virDomainPtr APIs
  *
- * Copyright (C) 2006-2015 Red Hat, Inc.
+ * Copyright (C) 2006-2019 Red Hat, Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -2570,6 +2570,12 @@ virDomainGetControlInfo(virDomainPtr domain,
  * XML might not validate against the schema, so it is mainly for
  * internal use.
  *
+ * If @flags contains VIR_DOMAIN_XML_SNAPSHOTS, the XML will include
+ * an additional <snapshots> child element describing all snapshots
+ * belonging to the domain, including an attribute current='name' if
+ * one of those snapshots is current. Note that some older servers
+ * silently ignore this flag instead of diagnosing it as unsupported.
+ *
  * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
  *         the caller must free() the returned value.
  */
-- 
2.20.1