10:52 a.m.
Hello,
Here is the 4th (and hopefully final) draft for the snapshot API that
we've been discussing. There is one minor change and one major change in
this draft. The minor change is that we've added a virDomainSnapshotHasCurrent
and virDomainSnapshotCurrent methods to get at the current snapshot. The
major change is that I've removed all but one of the possible
virDomainSnapshotDelete() flags. After reviewing ESX, virtualbox, and qemu, it
seems that the deletion of any snapshots that have children will *automatically*
merge the changes from that snapshot into the children to keep the children
viable. Therefore, the MERGE and MERGE_FORCE flags are nonsensical. Since this
is the virDomainSnapshotDelete call, we don't really need a flag to say
"delete",
so I've removed the DISCARD flag. What that leaves us with is a single flag to
the delete API that says to delete this snapshot, and all children of this
snapshot. This could be useful to clean out a tree of snapshots instead of
doing it one-by-one.
If there are no further major objections to this API, we'll be posting
patches later today or tomorrow that implement this API for both qemu and
virtualbox.
Note that I've not included my full notes from last time. If anyone
is still interested in those, I can either repost them or send them privately.
/* NOTE: struct _virDomainSnapshot is a private structure, ala
* struct _virDomain.
*/
typedef struct _virDomainSnapshot virDomainSnapshot;
/* Take a snapshot of the current VM state. */
virDomainSnapshotPtr virDomainSnapshotCreateXML(virDomainPtr domain,
const char *xmlDesc,
unsigned int flags);
/* Dump the XML of a snapshot */
/* NOTE: see below for proposed XML */
char *virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
unsigned int flags);
/* Return the number of snapshots for this domain */
int virDomainSnapshotNum(virDomainPtr domain, unsigned int flags);
/* Get the names of all snapshots for this domain */
int virDomainListSnapshotNames(virDomainPtr domain, char **names, int nameslen,
unsigned int flags);
/* Get a handle to a named snapshot */
virDomainSnapshotPtr virDomainSnapshotLookupByName(virDomainPtr domain,
const char *name,
unsigned int flags);
/* Find out if domain "domain" has a current snapshot */
int virDomainSnapshotHasCurrent(virDomainPtr domain, unsigned int flags);
/* Get a handle to the current in-use snapshot for the domain. */
int virDomainSnapshotCurrent(virDomainPtr domain,
unsigned int flags);
/* Start the guest from the snapshot "snapshot". Note that
* the guest may either be running or not.
*
* In the case the VM is running, then the snapshot *must* have
* been taken while the VM was running (i.e. the snapshot <state>
* tag must be "RUNNING"). This will revert the disk and memory to
* "snapshot".
*
* In the case the VM is not running, then the snapshot may
* have been taken while the VM was not running or not. In
* either case it will revert just the disk to "snapshot".
*/
int virDomainCreateFromSnapshot(virDomainSnapshotPtr snapshot,
unsigned int flags);
/* Delete a snapshot.
*
* TREE: discard this snapshot and any children snapshots
*
* Note that this operation can happen when the domain is running or shut
* down, though this is hypervisor specific */
*/
typedef enum {
VIR_DOMAIN_SNAPSHOT_DELETE_TREE,
} virDomainSnapshotDelete;
int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
unsigned int flags);
int virDomainSnapshotFree(virDomainSnapshotPtr snapshot);
NOTE: During snapshot creation, *none* of the fields are required. That is,
you can call virDomainSnapshotCreateXML() with an XML of
"<domainsnapshot/>".
In this case, the individual driver will make up a <name> for you,
the <creationdate> will be set to the current time+date, <description> will
be
empty, <state> will be the current state of the VM, and <parent> will
be set to the current snapshot (if any). If you do want to specify some
fields during virDomainSnapshotCreateXML(), note that the only ones that are
settable are <name> and <description>;
the rest are ignored, and filled in by the driver when the snapshot is
actually created.
NOTE: <state> refers to the state of the VM when the snapshot was taken.
NOTE: <creationdate> is in the format %Y-%m-%d_%T as defined by strptime.
Also note that the granularity of <creationdate> is in seconds.
<domainsnapshot>
<name>XYZ</name>
<creationdate>...</creationdate>
<description>...</description>
<state>RUNNING</state>
<domain>
<uuid>XXXXX-XXXX-XXXX-XXXX-XXXXXXXXX</uuid>
</domain>
<parent>
<name>ABC</name>
</parent>
</domainsnapshot>
The virsh commands will be:
virsh snapshot-create <dom> [<xmlfile>]
virsh snapshot-list <dom>
virsh snapshot-dumpxml <dom> <name>
virsh start-from-snapshot <dom> <snapshotname>
virsh snapshot-delete <dom> <snapshotname> [--children]
--
Chris Lalancette