[libvirt] [RFC]: Snapshot API v2

[Matthias Bolte]

2010/3/24 Chris Lalancette <clalance at redhat.com>:
> Based on discussion, I've modified the snapshot API to the below.  I've
> incorporated most of the semantic changes we talked about; the renaming
> of various API calls I've left for later, since it is a minor point.
> More comments welcome!
>
> /* NOTE: struct _virDomainSnapshot is a private structure, ala
>  * struct _virDomain.
>  */
> typedef struct _virDomainSnapshot virDomainSnapshot;
>
> /* Take a snapshot of the current VM state.  Throws an error if
>  * the VM is not currently running */
> 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);
>
> /* Start the guest "domain" from the snapshot "snapshot" */
> int virDomainCreateWithSnapshot(virDomainPtr domain,
>                                virDomainSnapshotPtr snapshot,
>                                unsigned int flags);
>
> /* Deactivate a snapshot - with no flags, the snapshot is not used anymore,
>  * but also not removed.  With a MERGE flag, it merges the snapshot into
>  * the parent snapshot (or the base image, if there is no parent snapshot).
>  * Note that if other snapshots would be discarded because of this
>  * MERGE action, this operation will fail.  If that is really what is intended,
>  * use MERGE_FORCE.
>  *
>  * With a DISCARD flag, it deletes the snapshot.  Note that if other snapshots
>  * would be discarded because of this delete action, this operation will
>  * fail.  If this is really what is intended, use DISCARD_FORCE.
>  *
>  * MERGE, MERGE_FORCE, DISCARD, and DISCARD_FORCE are mutually-exclusive.
>  *
>  * Note that this operation can generally only happen when the domain is shut
>  * down, though this is hypervisor-specific */
> typedef enum {
>    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_MERGE,
>    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_MERGE_FORCE,
>    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_DISCARD,
>    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_DISCARD_FORCE,
> } virDomainSnapshotDeactivate;
> int virDomainSnapshotDeactivate(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 "off", <compression> will be empty, 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>, <description>, and <compression>; the rest are ignored,
> and filled in by the driver when the snapshot is actually created.
> NOTE: <compression> is used to compress snapshots, and may or may not be
> supported by individual hypervisor implementations.  If <compression> is
> specified and the underlying hypervisor does not support it, an error will
> be thrown.
>
> <domainsnapshot>
>   <name>XYZ</name>
>   <creationdate>...</creationdate>
>   <description>...</description>
>   <state>RUNNING</state>
>   <domain>
>      <uuid>XXXXX-XXXX-XXXX-XXXX-XXXXXXXXX</uuid>
>   </domain>
>   <compression>gzip</compression>
>   <parent>
>     <name>ABC</name>
>   </parent>
> </domainsnapshot>
>
> The virsh commands will be:
> virsh snapshot-create [--compress] <dom> <xmlfile>
> virsh snapshot-list <dom>
> virsh snapshot-dumpxml <dom> <name>
> virsh create-with-snapshot <dom> <snapshotname>

It should be called start-with-snapshot.

I'm not sure if this start-with-snapshot is a good idea, because I
think this concept is not intuitive to the user. A typical lifecycle
of a domain in the ESX or VirtualBox context may look like this:

- define a new domain
- start it
- install the OS
- create a snapshot A to have a backup of the state with a clean OS installation
- do some work in the domain
- shutdown the domain
- start the domain again (in ESX or VirtualBox UIs this is done by the
normal start button)

The user expects to start the domain with the exact same state as at
last shutdown. But with virsh if you use the normal start command as
you normally do you'll get something different. In the context of ESX
or VirtualBox I'm not even sure what the "base image" would be, is it
the empty disk before OS installation?

> virsh snapshot-deactivate <dom> <snapshotname> [--merge|--delete|--mergeforce|--mergedelete]
>
>
> --
> Chris Lalancette
>

Matthias