KVM virsh snapshot commands and examples

The following commands manipulate domain snapshots. Snapshots take the disk, memory, and device state of a domain at a point-of-time, and save it for future use. They have many uses, from saving a "clean" copy of an OS image to saving a domain's state before a potentially destructive operation. Snapshots are identified with a unique name. See http://libvirt.org/formatsnapshot.html for documentation of the XML format used to represent properties of snapshots.

For difference between external and internal snapshots see KVM virsh external vs internal snapshots.


snapshot-create

snapshot-create domain [xmlfile] {[--redefine [--current]] | [--no-metadata] [--halt] [--disk-only] [--reuse-external] [--quiesce] [--atomic] [--live]}

Create a snapshot for domain domain with the properties specified in xmlfile. Normally, the only properties settable for a domain snapshot are the <name> and <description> elements, as well as <disks> if --disk-only is given; the rest of the fields are ignored, and automatically filled in by libvirt. If xmlfile is completely omitted, then libvirt will choose a value for all fields. The new snapshot will become current, as listed by snapshot-current.

  • If --halt is specified, the domain will be left in an inactive state after the snapshot is created.
  • If --disk-only is specified, the snapshot will only include disk state rather than the usual system checkpoint with vm state. Disk snapshots are faster than full system checkpoints, but reverting to a disk snapshot may require fsck or journal replays, since it is like the disk state at the point when the power cord is abruptly pulled; and mixing --halt and --disk-only loses any data that was not flushed to disk at the time.
  • If --redefine is specified, then all XML elements produced by snapshot-dumpxml are valid; this can be used to migrate snapshot hierarchy from one machine to another, to recreate hierarchy for the case of a transient domain that goes away and is later recreated with the same name and UUID, or to make slight alterations in the snapshot metadata (such as host-specific aspects of the domain XML embedded in the snapshot). When this flag is supplied, the xmlfile argument is mandatory, and the domain's current snapshot will not be altered unless the --current flag is also given.
  • If --no-metadata is specified, then the snapshot data is created, but any metadata is immediately discarded (that is, libvirt does not treat the snapshot as current, and cannot revert to the snapshot unless --redefine is later used to teach libvirt about the metadata again).
  • If --reuse-external is specified, and the snapshot XML requests an external snapshot with a destination of an existing file, then the destination must exist and be pre-created with correct format and metadata. The file is then reused; otherwise, a snapshot is refused to avoid losing contents of the existing files.
  • If --quiesce is specified, libvirt will try to use guest agent to freeze and unfreeze domain's mounted file systems. However, if domain has no guest agent, snapshot creation will fail. Currently, this requires --disk-only to be passed as well.
  • If --atomic is specified, libvirt will guarantee that the snapshot either succeeds, or fails with no changes; not all hypervisors support this. If this flag is not specified, then some hypervisors may fail after partially performing the action, and dumpxml must be used to see whether any partial changes occurred.
  • If --live is specified, libvirt takes the snapshot (checkpoint) while the guest is running. Both disk snapshot and domain memory snapshot are taken. This increases the size of the memory image of the external checkpoint. This is currently supported only for external checkpoints.

Existence of snapshot metadata will prevent attempts to undefine a persistent domain. However, for transient domains, snapshot metadata is silently lost when the domain quits running (whether by command such as destroy or by internal guest action).

snapshot-create examples

Named snapshots:

1
2
3
4
5
# virsh snapshot-create-as fedora-27 named
Domain snapshot named created

# virsh snapshot-create-as fedora-27 --name named2 --description 'some description'
Domain snapshot named2 created

Unnamed and named (via xmlfile) snapshot creation:

# virsh snapshot-create fedora-27  
Domain snapshot 1519723398 created

# cat ./config 
<domainsnapshot>
  <name>named-snapshot</name>
</domainsnapshot>

# virsh snapshot-create fedora-27 ./config          
Domain snapshot named-snapshot created from './config'

# virsh snapshot-list fedora-27                        
 Name                 Creation Time             State
------------------------------------------------------------
 1519723398           2018-02-27 12:23:18 +0300 running
 named-snapshot       2018-02-27 12:25:22 +0300 running

Shutdown after creation with --halt:

1
2
3
4
5
6
7
8
# virsh domstate fedora-27                             
running

# virsh snapshot-create fedora-27 --halt
Domain snapshot 1519723714 created

# virsh domstate fedora-27              
shut off

snapshot-create-as

snapshot-create-as domain {[--print-xml] | [--no-metadata] [--halt] [--reuse-external]} [name] [description] [--disk-only [--quiesce]] [--atomic] [[--live] [--memspec memspec]] [--diskspec] diskspec]...

Create a snapshot for domain domain with the given <name> and <description>; if either value is omitted, libvirt will choose a value. If --print-xml is specified, then XML appropriate for snapshot-create is output, rather than actually creating a snapshot. Otherwise, if --halt is specified, the domain will be left in an inactive state after the snapshot is created, and if --disk-only is specified, the snapshot will not include vm state.

  • The --memspec option can be used to control whether a checkpoint is internal or external. The --memspec flag is mandatory, followed by a memspec of the form [file=]name[,snapshot=type], where type can be no, internal, or external. To include a literal comma in file=name, escape it with a second comma. --memspec cannot be used together with --disk-only.
  • The --diskspec option can be used to control how --disk-only and external checkpoints create external files. This option can occur multiple times, according to the number of <disk> elements in the domain xml. Each <diskspec> is in the form disk[,snapshot=type][,driver=type][,file=name]. A diskspec must be provided for disks backed by block devices as libvirt doesn't auto-generate file names for those. To include a literal comma in disk or in file=name, escape it with a second comma. A literal --diskspec must precede each diskspec unless all three of domain, name, and description are also present. For example, a diskspec of vda,snapshot=external,file=/path/to,,new results in the following XML:
    1
    2
    3
    <disk name='vda' snapshot='external'>
      <source file='/path/to,new'/>
    </disk>
    
  • --no-metadata - same as in snapshot-create. This flag is incompatible with --print-xml.

snapshot-create-as examples

Full external snapshot:

# virsh snapshot-create-as fedora-27 --memspec file=/external-snapshot-1,snapshot=external external-snapshot-name-1
Domain snapshot external-snapshot-name-1 created

# file /external-snapshot-1
/external-snapshot-1: Libvirt QEMU Suspend Image, version 2, XML length 4428, running

# virsh snapshot-list fedora-27      
 Name                       Creation Time             State
--------------------------------------------------------------
 external-snapshot-name-1   2018-02-27 12:51:53 +0300 running

Disk only external snapshot:

# virsh snapshot-create-as fedora-27 --disk-only --diskspec vda,file=/disk-snapshot-1,snapshot=external --name disk-snapshot-1 
Domain snapshot disk-snapshot-1 created
#
# file /disk-snapshot-1 
/disk-snapshot-1: QEMU QCOW Image (v3), has backing file (path /home/user/.vms/fedora-27.name2), 16106127360 bytes

# virsh snapshot-list fedora-27      
 Name                 Creation Time             State
------------------------------------------------------------
 disk-snapshot-1      2018-02-28 11:36:04 +0300 disk-snapshot

snapshot-current

snapshot-current domain {[--name] | [--security-info] | [snapshotname]}

Without snapshotname, this will output the snapshot XML for the domain's current snapshot (if any). If --name is specified, just the current snapshot name instead of the full xml. Otherwise, using --security-info will also include security sensitive information in the XML.

With snapshotname, this is a request to make the existing named snapshot become the current snapshot, without reverting the domain.

snapshot-current examples

Changing current snapshot:

# virsh snapshot-list fedora-27 
 Name                 Creation Time             State
------------------------------------------------------------
 old                  2018-02-27 13:56:16 +0300 running
 new                  2018-02-27 13:56:33 +0300 running

# virsh snapshot-current fedora-27 --name
old

# virsh snapshot-current fedora-27 new
Snapshot new set as current

# virsh snapshot-current fedora-27 --name
new

snapshot-edit

snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}

Edit the XML configuration file for snapshotname of a domain. If both snapshotname and --current are specified, also force the edited snapshot to become the current snapshot. If snapshotname is omitted, then --current must be supplied, to edit the current snapshot.

This is equivalent to:

1
2
3
virsh snapshot-dumpxml dom name > snapshot.xml
vi snapshot.xml (or make changes with your other text editor)
virsh snapshot-create dom snapshot.xml --redefine [--current]

except that it does some error checking.

The editor used can be supplied by the $VISUAL or $EDITOR environment variables, and defaults to "vi".

If --rename is specified, then the edits can change the snapshot name. If --clone is specified, then changing the snapshot name will create a clone of the snapshot metadata. If neither is specified, then the edits must not change the snapshot name. Note that changing a snapshot name must be done with care, since the contents of some snapshots, such as internal snapshots within a single qcow2 file, are accessible only from the original name.

snapshot-edit examples

Edit current snapshot:

# virsh snapshot-edit fedora-27 --current
Snapshot new edited.

Edit snapshot nm and clone it:

# virsh snapshot-edit fedora-27 sn --clone
Snapshot sn edited.

snapshot-info

snapshot-info domain {snapshot | --current}

Output basic information about a named <snapshot>, or the current snapshot with --current.

snapshot-info examples

# virsh snapshot-info fedora-27  --current
Name:           nm
Domain:         fedora-27
Current:        yes
State:          running
Location:       external
Parent:         1519725138
Children:       2
Descendants:    3
Metadata:       yes

# virsh snapshot-info fedora-27  1519723398                                               
Name:           1519723398
Domain:         fedora-27
Current:        no
State:          running
Location:       internal
Parent:         -
Children:       1
Descendants:    9
Metadata:       yes

snapshot-list

snapshot-list domain [--metadata] [--no-metadata] [{--parent | --roots | [{--tree | --name}]}] [{[--from] snapshot | --current} [--descendants]] [--leaves] [--no-leaves] [--inactive] [--active] [--disk-only] [--internal] [--external]

List all of the available snapshots for the given domain, defaulting to show columns for the snapshot name, creation time, and domain state.

  • If --parent is specified, add a column to the output table giving the name of the parent of each snapshot. If --roots is specified, the list will be filtered to just snapshots that have no parents. If --tree is specified, the output will be in a tree format, listing just snapshot names. These three options are mutually exclusive. If --name is specified only the snapshot name is printed. This option is mutually exclusive with --tree.
  • If --from is provided, filter the list to snapshots which are children of the given snapshot; or if --current is provided, start at the current snapshot. When used in isolation or with --parent, the list is limited to direct children unless --descendants is also present. When used with --tree, the use of --descendants is implied. This option is not compatible with --roots. Note that the starting point of --from or --current is not included in the list unless the --tree option is also present.
  • If --leaves is specified, the list will be filtered to just snapshots that have no children. Likewise, if --no-leaves is specified, the list will be filtered to just snapshots with children. (Note that omitting both options does no filtering, while providing both options will either produce the same list or error out depending on whether the server recognizes the flags). Filtering options are not compatible with --tree.
  • If --metadata is specified, the list will be filtered to just snapshots that involve libvirt metadata, and thus would prevent undefine of a persistent domain, or be lost on destroy of a transient domain. Likewise, if --no-metadata is specified, the list will be filtered to just snapshots that exist without the need for libvirt metadata.
  • If --inactive is specified, the list will be filtered to snapshots that were taken when the domain was shut off. If --active is specified, the list will be filtered to snapshots that were taken when the domain was running, and where the snapshot includes the memory state to revert to that running state. If --disk-only is specified, the list will be filtered to snapshots that were taken when the domain was running, but where the snapshot includes only disk state.
  • If --internal is specified, the list will be filtered to snapshots that use internal storage of existing disk images. If --external is specified, the list will be filtered to snapshots that use external files for disk images or memory state.

snapshot-list examples

# virsh snapshot-list fedora-27 --tree     
1519723398
  |
  +- named-snapshot
      |
      +- 1519723714
          |
          +- 1519724896
              |
              +- external
                  |
                  +- 1519725138
                      |
                      +- nm
                          |
                          +- name1
                          +- name2
                              |
                              +- name3

# virsh snapshot-list fedora-27 --external
 Name                 Creation Time             State           Parent
------------------------------------------------------------
 1519725138           2018-02-27 12:52:18 +0300 running         external
 name1                2018-02-27 13:56:16 +0300 running         nm
 name2                2018-02-27 13:56:33 +0300 running         nm
 name3                2018-02-28 11:36:04 +0300 disk-snapshot   name2
 nm                   2018-02-27 13:40:01 +0300 running         1519725138
 external             2018-02-27 12:51:53 +0300 running         1519724896

snapshot-dumpxml

snapshot-dumpxml domain snapshot [--security-info]

Output the snapshot XML for the domain's snapshot named snapshot. Using --security-info will also include security sensitive information. Use snapshot-current to easily access the XML of the current snapshot.

snapshot-dumpxml examples

# snapshot-dumpxml fedora-27 nm --security-info > xml

snapshot-parent

snapshot-parent domain {snapshot | --current}

Output the name of the parent snapshot, if any, for the given snapshot, or for the current snapshot with --current.

snapshot-parent examples

1
2
3
4
5
# virsh snapshot-parent fedora-27 --current 
1519725138

# virsh snapshot-parent fedora-27 snapshot3
snapshot2

snapshot-revert

snapshot-revert domain {snapshot | --current} [{--running | --paused}] [--force]

Revert the given domain to the snapshot specified by snapshot, or to the current snapshot with --current. Be aware that this is a destructive action; any changes in the domain since the last snapshot was taken will be lost. Also note that the state of the domain after snapshot-revert is complete will be the state of the domain at the time the original snapshot was taken.

Normally, reverting to a snapshot leaves the domain in the state it was at the time the snapshot was created, except that a disk snapshot with no vm state leaves the domain in an inactive state. Passing either the --running or --paused flag will perform additional state changes (such as booting an inactive domain, or pausing a running domain). Since transient domains cannot be inactive, it is required to use one of these flags when reverting to a disk snapshot of a transient domain.

There are two cases where a snapshot revert involves extra risk, which requires the use of --force to proceed. One is the case of a snapshot that lacks full domain information for reverting configuration (such as snapshots created prior to libvirt 0.9.5); since libvirt cannot prove that the current configuration matches what was in use at the time of the snapshot, supplying --force assures libvirt that the snapshot is compatible with the current configuration (and if it is not, the domain will likely fail to run). The other is the case of reverting from a running domain to an active state where a new hypervisor has to be created rather than reusing the existing hypervisor, because it implies drawbacks such as breaking any existing VNC or Spice connections; this condition happens with an active snapshot that uses a provably incompatible configuration, as well as with an inactive snapshot that is combined with the --start or --pause flag.

snapshot-revert examples

# virsh snapshot-revert fedora-27 bak

Note: to revert to an external snapshot you have to manually power off the vm, edit the XML to point at the desired disk image.


snapshot-delete

snapshot-delete domain {snapshot | --current} [--metadata] [{--children | --children-only}]

Delete the snapshot for the domain named snapshot, or the current snapshot with --current. If this snapshot has child snapshots, changes from this snapshot will be merged into the children. If --children is passed, then delete this snapshot and any children of this snapshot. If --children-only is passed, then delete any children of this snapshot, but leave this snapshot intact. These two flags are mutually exclusive.

If --metadata is specified, then only delete the snapshot metadata maintained by libvirt, while leaving the snapshot contents intact for access by external tools; otherwise deleting a snapshot also removes the data contents from that point in time.

snapshot-delete examples

Due to virsh behavior these examples work only for internal shapshots. Deleting external snapshots is more tricky. See KVM virsh how to delete external snapshot.

1
2
3
4
5
6
7
8
9
# virsh snapshot-list fedora-27 --tree          
1519723398
  |
  +- 1519723714
      |
      +- name1
      +- name2
          |
          +- name3

Delete name2 and its children (name3):

# virsh snapshot-delete fedora-27 name2 --children
Domain snapshot name2 deleted

Delete only 1519723398:

#virsh snapshot-delete fedora-27 1519723398    
Domain snapshot 1519723398 deleted
Edit Report
Pub: 28 Feb 2018 10:55 UTC
Edit: 06 Mar 2018 07:47 UTC
Views: 3277