From mboxrd@z Thu Jan  1 00:00:00 1970
From: Chunyan Liu <cyliu@suse.com>
Subject: [RFC V10 3/4] domain snapshot design: xl
Date: Mon, 26 Jan 2015 11:25:12 +0800
Message-ID: <1422242713-3744-4-git-send-email-cyliu@suse.com>
References: <1422242713-3744-1-git-send-email-cyliu@suse.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Return-path: <xen-devel-bounces@lists.xen.org>
In-Reply-To: <1422242713-3744-1-git-send-email-cyliu@suse.com>
List-Unsubscribe: <http://lists.xen.org/cgi-bin/mailman/options/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=unsubscribe>
List-Post: <mailto:xen-devel@lists.xen.org>
List-Help: <mailto:xen-devel-request@lists.xen.org?subject=help>
List-Subscribe: <http://lists.xen.org/cgi-bin/mailman/listinfo/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=subscribe>
Sender: xen-devel-bounces@lists.xen.org
Errors-To: xen-devel-bounces@lists.xen.org
To: xen-devel@lists.xen.org
Cc: wei.liu2@citrix.com, jfehlig@suse.com, ian.jackson@eu.citrix.com, Ian.Campbell@citrix.com, Chunyan Liu <cyliu@suse.com>
List-Id: xen-devel@lists.xenproject.org

Changes to V9:
  * add --internal|--external option to snapshot-create.
  * add @path to snapshot-create
  * remove --name to snapshot-create
  * add detailed description for snapshot-create default behaviors
    and behaviors with options
  * add description about deleting domain snapshot for a full picture
    and as background knowledge for a possible discussion later.
  * add 'memory' in cfgfile syntax for future disk-only snapshot usage

===========================================================================

XL Design

1. User Interface

xl snapshot-create:
  Create a snapshot (disk and RAM) of a domain.

  SYNOPSIS:
    snapshot-create [--live] [--internal|--external] <domain> [path] [<cfgfile>]
  OPTIONS:
    --live           take a live snapshot
    --internal       take internal disk snapshots to all disks
    --external       take external disk snapshots to all disks

    If no options specified and no @cfgfile and no @path specified:
    e.g. # xl snapshot-create domain
    By default, it will create a domain snapshot with default name
    generated according to creation time. This name will be used to
    generate default RAM snaphsot name and disk snapshot name, and
    generate the default directory to store all the snapshot data
    (RAM snapshot file, external disk snapshot files, etc.)
    e.g. result of above command would be:
    default snapshot root directory:
        /var/lib/xen/snapshots/
    default snapshot name generated :
        20150122xxx
    default subdirectory to save data of this snapshot:
        /var/lib/xen/snapshots/domain_uuid/20150122xxx/
    RAM snapshot file:
        By default, it will save memory. Location is here:
        /var/lib/xen/snapshots/domain_uuid/20150122xxx/20150122xxx.save
    disk snapshots:
        By default, to each domain disk, take internal disk snapshot if
        that disk supports, otherwise, take external disk snapshot.

        Internal disk snapshot: take disk snapshot with name 20150122xxx
        External disk snapshot: external file is:
        /var/lib/xen/snapshots/domain_uuid/20150122xxx/vda_20150122xxx.qcow2
        /var/lib/xen/snapshots/domain_uuid/20150122xxx/vdb_20150122xxx.qcow2

    If option includes --live, then the domain is not paused while creating
    the snapshot, like live migration. This increases size of the memory
    dump file, but reducess downtime of the guest.

    If @path is given, all snapshot data will be saved in this @path.
    If no @cfgfile:name specified, then use the basename of @path as snapshot
    name.

    User could specify snapshot information in details through @cfgfile, see
    following cfgfile syntax. If configuration in @cfgfile conflicts with
    other options, @cfgfile will supercede other options. (e.g. if --internal
    conflicts with disk spec in cfgfile, use disk spec in @cfgfile.)


xl snapshot-revert:
  Revert domain to status of a snapshot.

  SYNOPSIS:
      snapshot-revert <domain> <cfgfile> [--running] [--force]

  OPTIONS:
    --running        after reverting, change state to running
    --force          try harder on risky reverts

    Normally, the domain will revert to the same state the domain was in while
    the snapshot was taken (whether running, or paused).

    If option includes --running, then overrides the snapshot state to
    guarantee a running domain after the revert.


About domain snapshot delete:
    xl doesn't have snapshot chain information, so it couldn't do the full work.
    If supply:
      xl snapshot-delete <domain> <cfgfile>
    For internal disk snapshot, deleting disk snapshot doesn't need snapshot chain
    info, this commands can finish the work. But for external disk snapshot,
    deleting disk snapshot will need to merge backing file chain, then will need
    the backing file chain information, this xl command can not finish that.

    So, deleting domain snapshots will be left to user:

    user could delete RAM snapshots and disk snapshots by themselves:
    RAM snapshot file: user could remove it directly.
    Disk snapshots:
      - Internal disk snapshot, issue 'qemu-img snapshot -d'
      - External disk snapshot,


2. cfgfile syntax

# snapshot name. If user doesn't provide a VM snapshot name, xl will generate
# a name automatically by creation time or by @path basename.
name=""

# save memory or disk-only.
# If memory is '0', doesn't save memory, take disk-only domain snapshot.
# If memory is '1', domain memory is saved.
# Default if 1.
memory=1

# memory location. This field is valid when memory=1.
# If it is set to "", xl will generate a path by creation time or by @path
# basename.
memory_path=""

# disk snapshot specification
# For easier parsing config work, reuse disk configuration in xl.cfg, but
# with different meanings.
# disk syntax meaning: 'external path, external format, target device'
#
# By default, if no disks is specified here, it will take disk snapshot
# to all disks: take internal disk snapshot if disk support internal disk
# snapshot; and external disk snapshot to other disks.

#disks=['/tmp/hda_snapshot.qcow2,qcow2,hda', ',,hdb',]

3. xl snapshot-xxx implementation

"xl snapshot-create"

    1), parse args or user configuration file.
    2), if saveing memory: save domain (store saved memory to memory_path)
        if taking disk-only snapshot: pause domain, quiece disks. (not
        supported now, maybe in future.)
    3), create disk snapshots according to disk snapshot configuration
    4), unpause domain

"xl snapshot-revert"

    1), parse user configuration file
    2), destroy current domain
    3), revert disk snapshots according to disk snapshot configuration
    4), restore domain from saved memory.

4. Notes

* user should take care of snapshot data: saved memory file, disk
  snapshots info (internal, external, etc.), snapshot chain relationship
* user should delete snapshots by themselves with CLI commands like: rm,
  qemu-img, etc.