[libvirt] [RFC PATCHv3 5/5] snapshot: add another revert API flag

Eric Blake eblake at redhat.com
Wed Nov 21 00:36:59 UTC 2012

Now that we can create external snapshot branches, we need to be able
to switch between them.  Add a new flag, which states that we will
merely use the external files as-is (and assume that the user hasn't
done any nasty hotplug or hotunplug of disks after that branch was
created, since we don't have any way to track the guest ABI at a tip
of a branch that we are about to leave).

* include/libvirt/libvirt.h.in
* src/libvirt.c (virDomainRevertToSnapshot): Document it.
* tools/virsh-snapshot.c (cmdDomainSnapshotRevert): Add --follow
* tools/virsh.pod (snapshot-revert): Document it.
 include/libvirt/libvirt.h.in |  3 +++
 src/libvirt.c                | 14 +++++++++++++-
 tools/virsh-snapshot.c       |  4 ++++
 tools/virsh.pod              |  9 ++++++++-
 4 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index be16629..0957300 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -3897,6 +3897,9 @@ typedef enum {
     VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING = 1 << 0, /* Run after revert */
     VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED  = 1 << 1, /* Pause after revert */
     VIR_DOMAIN_SNAPSHOT_REVERT_FORCE   = 1 << 2, /* Allow risky reverts */
+    VIR_DOMAIN_SNAPSHOT_REVERT_FOLLOW  = 1 << 3, /* Follow subsequent disk
+                                                    state rather than point of
+                                                    external snapshot */
 } virDomainSnapshotRevertFlags;

 /* Revert the domain to a point-in-time snapshot.  The
diff --git a/src/libvirt.c b/src/libvirt.c
index 3229133..d2447c3 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -18727,12 +18727,24 @@ error:
  * into an inactive state, so transient domains require the use of one
  * of these two flags.
+ * In the case of external snapshots, it is also possible to resume from
+ * the state of the external disks as modified after the snapshot was
+ * originally taken, by adding VIR_DOMAIN_SNAPSHOT_REVERT_FOLLOW to
+ * @flags.  In particular, this is the only way to switch between two
+ * external branches as created with VIR_DOMAIN_SNAPSHOT_CREATE_BRANCH
+ * by virDomainSnapshotCreateXML().
+ *
  * Reverting to any snapshot discards all configuration changes made since
  * the last snapshot.  Additionally, reverting to a snapshot from a running
  * domain is a form of data loss, since it discards whatever is in the
  * guest's RAM at the time.  Since the very nature of keeping snapshots
  * implies the intent to roll back state, no additional confirmation is
- * normally required for these lossy effects.
+ * normally required for these lossy effects.  Users are advised to
+ * pause or shut down a domain and create a final snapshot at the tip of
+ * that branch before using revert, if it may be desirable to return to
+ * that branch later on (especially true when the current execution
+ * descends from an external snapshot, to ensure pending I/O has been
+ * flushed to disk for later use by VIR_DOMAIN_SNAPSHOT_REVERT_FOLLOW).
  * However, there are two particular situations where reverting will
  * be refused by default, and where @flags must include
diff --git a/tools/virsh-snapshot.c b/tools/virsh-snapshot.c
index 6232ec2..fed728c 100644
--- a/tools/virsh-snapshot.c
+++ b/tools/virsh-snapshot.c
@@ -1696,6 +1696,8 @@ static const vshCmdOptDef opts_snapshot_revert[] = {
     {"running", VSH_OT_BOOL, 0, N_("after reverting, change state to running")},
     {"paused", VSH_OT_BOOL, 0, N_("after reverting, change state to paused")},
     {"force", VSH_OT_BOOL, 0, N_("try harder on risky reverts")},
+    {"follow", VSH_OT_BOOL, 0,
+     N_("follow disk changes made since an external snapshot")},
     {NULL, 0, 0, NULL}

@@ -1714,6 +1716,8 @@ cmdDomainSnapshotRevert(vshControl *ctl, const vshCmd *cmd)
     if (vshCommandOptBool(cmd, "paused"))
+    if (vshCommandOptBool(cmd, "follow"))
     /* We want virsh snapshot-revert --force to work even when talking
      * to older servers that did the unsafe revert by default but
      * reject the flag, so we probe without the flag, and only use it
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 38c691e..dc70e68 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -2837,7 +2837,7 @@ Output the name of the parent snapshot, if any, for the given
 I<snapshot>, or for the current snapshot with I<--current>.

 =item B<snapshot-revert> I<domain> {I<snapshot> | I<--current>}
-[{I<--running> | I<--paused>}] [I<--force>]
+[{I<--running> | I<--paused>}] [I<--force>] [I<--follow>]

 Revert the given domain to the snapshot specified by I<snapshot>, or to
 the current snapshot with I<--current>.  Be aware
@@ -2870,6 +2870,13 @@ snapshot that uses a provably incompatible configuration, as well as
 with an inactive snapshot that is combined with the I<--start> or
 I<--pause> flag.

+When reverting to an external snapshot, the I<--follow> flag specifies
+to revert to the subsequent state contained in the external disks rather
+than the state at the time the snapshot was taken.  This works best when
+paired with B<snapshot-create> with the I<--branch> flag, and where the
+guest is shut down before reverting between branches, so as not to lose
+in-flight guest I/O that was not flushed to disk before reverting.
 =item B<snapshot-delete> I<domain> {I<snapshot> | I<--current>} [I<--metadata>]
 [{I<--children> | I<--children-only>}]


More information about the libvir-list mailing list