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>

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

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
+ * captured from virDomainSnapshotGetXMLDesc() before removing that
- * to recreate a snapshot hierarchy on a destination, then remove it
+ * metadata, rather than creating a new snapshot.  This can be used to
- * on the source, in order to allow migration (since migration
+ * recreate a snapshot hierarchy on a destination, then remove it on
- * normally fails if snapshot metadata still remains on the source
+ * the source, in order to allow migration (since migration normally
- * machine).  When redefining snapshot metadata, the current snapshot
+ * fails if snapshot metadata still remains on the source machine).
- * will not be altered unless the VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT
+ * Note that while original creation can omit a number of elements
- * flag is also present.  It is an error to request the
+ * from @xmlDesc (and libvirt will supply sane defaults based on the
- * VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT flag without
+ * domain state at that point in time), a redefinition must supply
- * VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE.  On some hypervisors,
+ * 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