From a6a25d5cb69999c7fb438110b890f43e351dc438 Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Wed, 13 Mar 2019 21:38:52 -0500 Subject: [PATCH] snapshot: More clarification about REDEFINE MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 , 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 sub-element that matches the original output representing the domain state at the time the snapshot was first created. In fact, reverting without a 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 ; even though there are other drivers like vbox that do not output because they have other reliable ways to revert. And based on the confusion caused when omitting from snapshot XML, the initial design for checkpoints in later patches will make a mandatory element during its REDEFINE. [Side note: the fact that can appear in 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 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 sub-element be omitted on output, but such output is no longer suitable for sane REDEFINE input.] Signed-off-by: Eric Blake Reviewed-by: Daniel P. Berrangé --- docs/formatsnapshot.html.in | 3 ++- src/libvirt-domain-snapshot.c | 24 +++++++++++++++--------- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in index c60b4fb7c9..146908ce76 100644 --- a/docs/formatsnapshot.html.in +++ b/docs/formatsnapshot.html.in @@ -79,7 +79,8 @@ redefining a snapshot (since 0.9.5), with the VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE flag of virDomainSnapshotCreateXML(), 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.

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 947547627a..be9bf71af9 100644 --- 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 -- 2.39.5