snapshot: More clarification about REDEFINE

Based on recent list questions about the proposed addition of
virDomainCheckpointCreateXML(REDEFINE), it is worth adding some
clarification to the existing snapshot redefine documentation that is
serving as the basis for checkpoints.

Normal snapshot creation requires very few elements from the user XML
(libvirt can pick sane defaults for items that are omitted, and many
fields, including <domain>, are documented as readonly output fields
ignored on input, produced by drivers that track it). But during
REDEFINE, the API wants the complete XML produced by an earlier
virDomainSnapshotGetXMLDesc; as the domain definition has likely
changed since the snapshot was first created, libvirt is unable to
recreate a <domain> sub-element that matches the original output
representing the domain state at the time the snapshot was first
created. In fact, reverting without a <domain> sub-element is risky
enough that we had to add a FORCE flag for virDomainSnapshotRevert().
In short, we only support omitting domain for qemu because of
backwards-compatibility to snapshots created before 0.9.5 started
capturing <domain>; even though there are other drivers like vbox that
do not output <domain> because they have other reliable ways to
revert.

And based on the confusion caused when omitting <domain> from snapshot
XML, the initial design for checkpoints in later patches will make
<domain> a mandatory element during its REDEFINE.

[Side note: the fact that <domain> can appear in <domainsnapshot> is a
reason we cannot add a new API for a bulk listing or redefine of all
snapshots of a single domain in one XML call (for example, a 1M
<domain> XML * 16 snapshots explodes into 16M in a bulk form, which
gets difficult to send over RPC). Perhaps we could add a flag to
request that the <domain> sub-element be omitted on output, but such
output is no longer suitable for sane REDEFINE input.]

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in
index c60b4fb7c9d41871513dc549392e5310943bc85d..146908ce767429676b09c27b8247ffca18615c90 100644 (file)
--- a/docs/formatsnapshot.html.in
+++ b/docs/formatsnapshot.html.in
@@ -79,7 +79,8 @@
       redefining a snapshot (<span class="since">since 0.9.5</span>),
       with the <code>VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE</code> flag
       of <code>virDomainSnapshotCreateXML()</code>, all of the XML
-      described here is relevant.
+      described here is relevant on input, even the fields that are
+      normally described as readonly for output.
     </p>
     <p>
       Snapshots are maintained in a hierarchy.  A domain can have a

diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c
index 947547627a2ac6603b2c1e23ca8913db9ebfbd94..be9bf71af9c6df58b3cb01c88c3bb06417a3e577 100644 (file)
--- a/src/libvirt-domain-snapshot.c
+++ b/src/libvirt-domain-snapshot.c
@@ -117,15 +117,21 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
  *
  * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE, then this
  * is a request to reinstate snapshot metadata that was previously
- * discarded, rather than creating a new snapshot.  This can be used
- * to recreate a snapshot hierarchy on a destination, then remove it
- * on the source, in order to allow migration (since migration
- * normally fails if snapshot metadata still remains on the source
- * machine).  When redefining snapshot metadata, the current snapshot
- * will not be altered unless the VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT
- * flag is also present.  It is an error to request the
- * VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT flag without
- * VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE.  On some hypervisors,
+ * captured from virDomainSnapshotGetXMLDesc() before removing that
+ * metadata, rather than creating a new snapshot.  This can be used to
+ * recreate a snapshot hierarchy on a destination, then remove it on
+ * the source, in order to allow migration (since migration normally
+ * fails if snapshot metadata still remains on the source machine).
+ * Note that while original creation can omit a number of elements
+ * from @xmlDesc (and libvirt will supply sane defaults based on the
+ * domain state at that point in time), a redefinition must supply
+ * more elements (as the domain may have changed in the meantime, so
+ * that libvirt no longer has a way to resupply correct
+ * defaults). When redefining snapshot metadata, the domain's current
+ * snapshot will not be altered unless the
+ * VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT flag is also present.  It is an
+ * error to request the VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT flag
+ * without VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE.  On some hypervisors,
  * redefining an existing snapshot can be used to alter host-specific
  * portions of the domain XML to be used during revert (such as
  * backing filenames associated with disk devices), but must not alter