[RFC V5 1/5] docs: libxl Domain Snapshot HOWTO

[Bamvor Jian Zhang <bjzhang@suse.com>]

libxl Domain Snapshot HOWTO
--------

Author:
   Bamvor Jian Zhang <bjzhang@suse.com>

* Overview:
    Two levels of snapshot: disk snapshot and domain snapshot
    Four types of snapshot operations: create, delete, list and revert.

    * Disk snapshot
        Disk snapshot is crash-consistent if the domain is running. It could be
        "internal" (like in qcow2 format, snapshot and delta are both in one
        image file), or "external" (snapshot in one file, delta in another).

    * Domain snapshot
        Domain snapshot includes disk snapshots and domain state saving. domain
        could be resumed to the very state when the snapshot was created. This
        kind of snapshot is also referred to as a domain checkpoint or system
        checkpoint.

        "domain snapshot create" means saving domain state and doing disk
        snapshots. In the beginning of creating domain snapshot, it will check
        whether it is snapshotable.

        "domain snapshot revert" means rolling back to the state of indicated
        snapshot.

* Operations of Snapshot

    * Create Snapshot:

        User could create internal or external snapshot with or without config
        file. Refer to xl.snapshot.5 ( RFC Doc 5/5) for details of the config
        file. The Config file could provide all the features of snapshot, e.g.
        User could determine which disk will be included in snapshot(one or all
        disks).

        Use Cases:

        1), create an internal snapshot with default name (autogenerated name:
            epoch second from 1, Jan 1970). Internal snapshot is only supported
            by qcow2 format.
            e.g.:
                #xl snapshot-create your_domain

        2), create an internal snapshot with specific snapshot name.
            e.g.:
                #xl snapshot-create -n domain_snapshot_name your_domain

        3), create an external snapshot
            To create an external snapshot, you must specify a config file, in
            which you could specify the external path and the snapshot type in
            'disk'.
            e.g.:
                #xl snapshot-create your_domain config_file

            #cat snapshot_external_config_file
            name = "1397207577"
            description="Snapshot after OS installation. External snapshot"
            memory="yes"
            disk=['hda=/var/lib/xen/snapshots/<domain_uuid>/disk_hda.qcow2,type=qcow2',
                  'hdc=/var/lib/xen/snapshots/<domain_uuid>/disk_hdc.qcow2,type=qcow2']

        4), create disk-only snapshot, which means no memory state will be saved
            in this snapshot. Could be internal and external.
            e.g.:
                (internal)
                #xl snapshot-create --disk-only your_domain

                (external)
                #xl snapshot-create your_domain disk_only_config_file

            specific config file (to indicate which disks to be snapshotted).
            #cat disk_only_config_file
            name = "1397207577"
            description="Snapshot after OS installation. External disk-only\
                         snapsot. Only care about the root file system"
            disk=['hda=/var/lib/xen/snapshots/<domain_uuid>/disk_hda.qcow2,type=qcow2']

    * List Snapshot:

        Use Cases:

        1), List short information of all snapshots for the specific domain.
            Short information include snapshot name, creation time, the domain
            state when create snapshot, whether it is a disk-only snapshot.

            e.g.:
                #xl snapshot-list your_domain

        2), List full information of one snapshot for specific domain.
            Full information include short information and all the disk snapshot
            relative to that domain snapshot.
            e.g.:
                #xl snapshot-list -l -n domain_snapshot_name your_domain

        3), list full information of all snapshots for specific domain.
            e.g.:
                #xl snapshot-list -l your_domain

    * Delete snapshot:

        Use Cases:

        1), delete a snapshot for specific domain.
            This operation will delete all relative to this snapshot
            e.g.:
               #xl snapshot-delete -n domain_snapshot_name your_domain

    * Revert snapshot:

        Use Cases:

        Curently, only internal snapshot revert is supportted.
        Following command will revert an internal disk snapshot and memory state.
        e.g.:
            #xl snapshot-revert -n domain_snapshot_name your_domain