[Xen-devel] [RFC v3] domain snapshot documents

["Bamvor Jian Zhang" <bjzhang@xxxxxxxx>]

Hi,

here is the third version about domain snapshot documents, the second version
and the first version is here[1][2].

there are lots of potential feature about snapshots. for now, i focus on
providing the api for libvirt libxl driver in order to support the same
functionality compare with libvirt qemu driver. and you may already notice
david is working on libvirt libxl driver. it is a GSoC project[3]. it is
important for him to know the api in order to start coding in libvirt side.
i plan to work on other "advanced feature" after my first stage patch ack.

there are two types of snapshots supported by libxl: disk snapshot and domain
snapshot and four types of operations: create, delete, list and revert.

Disk snapshot will only be crash-consistent if the domain is running. Disk
snapshots can also be internal (qcow2) or external (snapshot in one file, delta
in another).

Domain snapshots include disk snapshots and domain state, allowing to resume
the domain from the same state when the snapshot was created. This type of
snapshot is also referred to as a domain checkpoint or system checkpoint.

In libvirt, there is a something like resource manager for domain snapshot
managements. So, in libxl, all these information is transfered through
libxl_domain_snapshot struct. xl will manage the snapshot by itself.

Domain snapshot create means save domain state and do disk snapshots.
At the beginning of domain snapshot create, it will check whether it is
snapshotable. it is snapshotable if all the disk is qdisk backed.

Domain snapshot revert means rollback the current snapshot state. and
Because the limitation of the qemu qmp, the revert could only support domain
snapshot with internal disk snapshot. revert the domain snapshot with external
snapshot doest not support.

there are live flag in snasphot configuration file, it will be save domain
memory and do external disk snapshot. to make the thing simple, i do not want
to implement in my first verion of patch.

As Ian Campbell said, the support of non-qdisk snapshot is very useful.
unfortuntely, i have no idea what it need to do. the only non-qdisk i know is
blktap. and i do not know does how to do snapshot create, delete, list and
revert for blktap? does it support internal or external support?
i treat it as an "advanced" feature, i will not cover it in my first version of
patch.

the new struct, api and command is as follows:
1, new struct
1), libxl_snapshot
store a disk snapshot information, it is used by disk snapshot create and 
delete.
libxl_disk_snapshot = Struct("disk_snapshot",[
    ("device",        string),
    ("name",          string),
    ("file",          string),
    ("format",        string),
    ])

device: device name to snapshot. e.g. sda, hda...
name: snapshot name given by user. it will the be same name as domain snapshot
name.
the following paramenter is only useful for external snapshot.
file: external snapshot file.
format: the format of external snapshot file

2), libxl_domain_snapshot
store domain snapshot information which store in the path shown above. i add
some api for create, delete and list these information.
libxl_domain_snapshot = Struct("domain_snapshot",[
    ("name",          string),
    ("creation_time", uint64),
    ("save",          string),
    ("disks", Array(libxl_disk_snapshot, "num_disks")),
    ])

name: snapshot name given by user. if user do not provide the name, it will be
the epoch seconds.
creation_time: the epoch seconds.
save: the memory save file for this snapshot.
disks: store the disk snapshot information assoiate with this domain.

2, new functions
there is no common api like libxl_snapshot_xxx. the reason is that different
toolstack may need to different event handling machanism(synchronize or
asynchronize). and obviously, domain snapshot create need async handler. so i
decide to only provide the sub api for xl and other toolstack(e.g. libvirt).
it make eailer for toolstack to handle the event by themselves.

1), in libxl/libxl.h
the implementation will be located in libxl_snapshot.c
/* disk snapshot api
 * support create for external and internal disks, support delete for internal
 * snapshot of disks.
 */
/* create disk snapshot according to the device name in snapshot array. nb is
 * the number of snapshot array.
 * use the qmp transaction to ensure all snapshot of disk is coherence.
 */
int libxl_disk_snapshot_create(libxl_ctx *ctx, int domid,
                               libxl_disk_snapshot *snapshot, int nb,
                               const libxl_asyncop_how *ao_how);
/* delete number of nb disk snapshot describe in snapshot array
 */
int libxl_disk_snapshot_delete(libxl_ctx *ctx, int domid,
                               libxl_disk_snapshot *snapshot, int nb);

2), xl_cmdimpl.c
int libxl_snapshot_create(int domid, libxl_domain_snapshot *snapshot);
int libxl_snapshot_delete(int domid, libxl_domain_snapshot *snapshot);
int libxl_snapshot_get(int domid, libxl_domain_snapshot *snapshot, int nb);
int libxl_snapshot_revert(int domid, libxl_domain_snapshot *snapshot);

support create, delete, list and revert for domain snasphot.

libxl_snapshot_get will read the domain snapshot configuration file stored in
disk and list snapshot information in simple or long format.

3, snapshot information file
i will write manpage for this with patch.

i found the Wei v5 patch about xl json format.
http://lists.xen.org/archives/html/xen-devel/2014-05/msg01670.html
it seems that i could use these apis for parsing and generating the snapshot
information file.

the domain snapshot information will store in the follow path:
/var/lib/xen/snapshots/<domain_uuid>/snapshotdata-<snapshot_name>.xl

here is an example for snapshot information file:
description="a snapshot after installation"
name="1397207577"
creationtime="1397207577"
save="1397207577.save"
type="internal"/"external"
live="no"
disk_only="no"
disk=[ 'hda=disk_hda.qcow2,type=qcow2', 'hdc=disk_hdc.qcow2,type=qcow2']

the save and disk image file base on the path of 
"/var/lib/xen/snapshots/<domain_uuid>"

the user could give a snapshot name when vm snapshot created. if not, the epoch
seconds will set as name as the above examples.

3, new command
i will write manpage for this with patch.
1), snapshot-create
Usage: xl snapshot-create <ConfigFile> [options] [Domain]

Create domain snapshot with ConfigFile or options

Options:
-n                snapshot name
--live            do live snapshot
--disk-only       only disk snapshot, do not save memory.

2), snapshot-list
Usage: xl snapshot-list [options] [Domain]

List domain snapshot information about all/some snapshot in one domain.

Options:
-l, --long        Output all domain snapshot details
-n                snapshot name

3), snapshot-delete
Usage: xl snapshot-delete [options] [Domain]

Delete domain snapshot relative data, including domain state, disk snapshot
and domain snapshot information file.

Options:
-n                snapshot name

4), snapshot-revert
Usage: xl snapshot-revert [options] [Domain]

Rollback the domain to snapshot state.

Options:
-n                snapshot name

[1] http://lists.xen.org/archives/html/xen-devel/2014-04/msg00414.html
    http://lists.xen.org/archives/html/xen-devel/2014-04/msg00244.html
[2] http://lists.xen.org/archives/html/xen-devel/2014-04/msg02549.html
[3] 
http://en.opensuse.org/openSUSE:GSOC_ideas#Add_virtual_machine_snapshot_support_to_libvirt_Xen_driver

changes since v2:
1), reorgnized the whole docments.
2), do not export the dedicated the disk snapshot commands.
3), others changes according to Ian and Jim's comment.

regards

bamvor


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel