[Xen-devel] [RFC V7 3/3] xl snapshot-xxx Design

[Chunyan Liu <cyliu@xxxxxxxx>]

1. xl commandline interface design

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

  SYNOPSIS:
    snapshot-create <domain> [<cfgfile>] [--disk-only] [--reuse-external]
    [--live]

  OPTIONS:
    [--domain] <string>  domain name, id or uuid
    [--cfgfile] <string>  domain snapshot configuration
    --disk-only      capture disk state but not vm state
    --reuse-external  reuse any existing external files
    --live           take a live snapshot

    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. Only support this flag
    during external checkpoints.

    If option includes --disk-only, then the snapshot will be limited to
    the disks, and no VM state will be saved. For an active guest, this is
    not supported.

    If specify @cfgfile, cfgfile is prioritized.

xl snapshot-delete:
  Delete a snapshot of a domain.

  SYNOPSIS:
    snapshot-delete <domain> <snapshotname> [--children] [--children-only]

    By default, just this snapshot is deleted, and changes from this
    snapshot are automatically merged into children snapshots.

  OPTIONS:
    [--domain] <string>  domain name, id or uuid
    [--snapshotname] <string>  snapshot name
    --children       delete snapshot and all children
    --children-only  delete children but not snapshot

    If option includes --children, then this snapshot and any descendant
    snapshots are deleted.

    If option include --children-only, only descendant snapshots are deleted,
    this snapshot is not deleted.

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

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

  OPTIONS:
    [--domain] <string>  domain name, id or uuid
    [--snapshotname] <string>  snapshot name
    --running        after reverting, change state to running
    --paused         after reverting, change state to paused
    --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 inactive, running, or paused).

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

    If option includes --paused, then guarantees a paused domain after
    the revert.

xl snapshot-list:
  List snapshots for a domain.

  SYNOPSIS:
    snapshot-list <domain> [--parent] [--disk-only] [--internal] [--external]
    [--tree] [--name]

  OPTIONS:
    --disk-only      filter by disk-only snapshots
    --internal       filter by internal snapshots
    --external       filter by external snapshots
    --tree           list snapshots in a tree
    --parent         add a column showing parent snapshot
    --name           list snapshot names only

2. cfgfile syntax

"xl snapshot-create" supports creating a VM snapshot with user provided
configuration file. The configuration file syntax is as below:

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

#snapshot description. Default is NULL.
description=""

#save memory or not. 1 (true) or 0 (false). Default is 0.
memory=0

#memory location. This field should be filled when memory=1. Default is NULL.
memory_path=""

#disk snapshot information
disks=['sda,1,qcow2,/tmp/sda_snapshot.qcow2','sdb,1,qcow2,/tmp/sda_snapshot.qcow2']
or
disks=['sda,0','sdb,0']

disk syntax:
'target device, external disk snapshot?, external format, external path'

3. xl structure to maintain VM snapshot info

libxl_disk_snapshot = Struct("disk_snapshot",[
    # target disk
    ("disk",            libxl_device_disk),

    # disk snapshot name
    ("name",            string),

    # internal/external disk snapshot?
    ("external",        bool),

    # for external disk snapshot, specify following two field
    ("external_format", string),
    ("external_path",   string),
    ])

libxl_domain_snapshot_info = Struct("domain_snapshot_info",[
    # snapshot name
    ("name",          string)

    ("create_time",   string)
    ("description",   string)

    # save memory or not. "false" means disk-only snapshot
    ("memory",        bool),

    # memory state path when snapshot is external
    ("memory_path",   string),

    # array to store disk snapshot info
    ("disks",         Array(libxl_disk_snapshot, "num_disks")),

    # parent snapshot name
    ("parent",        string),

    # array to store all children snapshot name
    ("children",      Array(string, "num_children"),
    ]

According to libxl_domain_snapshot_info, a json file will be saved on disk.

4. xl snapshot-xxx implementation details

"xl snapshot-create"

    1), parse args or domain snapshot configuration file.
    2), fill info in libxl_domain_snapshot_args struct according to
        options or config file.
    3), call libxl_domain_snapshot_create()
    4), fill info in libxl_domain_snapshot_info.
    5), save snapshot info in json file under                                   
                          "/var/lib/xen/snapshots/domain_uuid"

"xl snapshot-list"

    1), read all domain snapshot related json file under
        "/var/lib/xen/snapshots/domain_uuid". Parse each file and fill in
        libxl_domain_snapshot_info struct.
    2), display information from those libxl_domain_snapshot_info(s)

"xl snapshot-delete"

    1), read snapshot json file from
        "/var/lib/xen/snapshots/domain_uuid/snapshotdata-<snapshot_name>\
        .libxl-json", parse the file and fill in libxl_domain_snapshot_info
    2), according to parent/children info in libxl_domain_snapshot_info
        and commandline options, decide which domain snapshot to be deleted.
        To delete each domain snapshot, fill in
        libxl_domain_snapshot_args and call libxl_domain_snapshot_delete().
    3), refresh parent/children relationship, delete json file for those
        already deleted snapshot.

"xl snapshot-revert"

    1), read snapshot json file from
        "/var/lib/xen/snapshots/domain_uuid/snapshotdata-<snapshot_name>\
        .libxl-json", parse the file and fill in libxl_domain_snapshot_info.
    2), fill in libxl_domain_snapshot_args
    3). call libxl_domain_snapshot_revert().

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