21.41. Managing Snapshots

The sections that follow describe actions that can be done in order to manipulate guest virtual machine snapshots. Snapshots take the disk, memory, and device state of a guest virtual machine at a specified point in time, and save it for future use. Snapshots have many uses, from saving a "clean" copy of an OS image to saving a guest virtual machine’s state before what may be a potentially destructive operation. Snapshots are identified with a unique name. See the libvirt upstream website for documentation of the XML format used to represent properties of snapshots.

Important

Red Hat Enterprise Linux 7 only supports creating snapshots while the guest virtual machine is paused or powered down. Creating snapshots of running guests (also known as live snapshots) is available on Red Hat Virtualization. For details, call your service representative.

21.41.1. Creating Snapshots

The virsh snapshot-create command creates a snapshot for guest virtual machine with the properties specified in the guest virtual machine's XML file (such as <name> and <description> elements, as well as <disks>). To create a snapshot run:
# virsh snapshot-create domain XML file [--redefine [--current] [--no-metadata] [--halt] [--disk-only] [--reuse-external] [--quiesce] [--atomic]
The guest virtual machine name, id, or uid may be used as the guest virtual machine requirement. The XML requirement is a string that must in the very least contain the name, description, and disks elements.
The remaining optional arguments are as follows:
  • --disk-only - the memory state of the guest virtual machine is not included in the snapshot.
  • If the XML file string is completely omitted, libvirt will choose a value for all fields. The new snapshot will become current, as listed by snapshot-current. In addition, the snapshot will only include the disk state rather than the usual system checkpoint with guest virtual machine 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. Note that mixing --halt and --disk-only loses any data that was not flushed to disk at the time.
  • --halt - causes the guest virtual machine to be left in an inactive state after the snapshot is created. Mixing --halt and --disk-only loses any data that was not flushed to disk at the time as well as the memory state.
  • --redefine specifies that if all XML elements produced by virsh snapshot-dumpxml are valid; it can be used to migrate snapshot hierarchy from one machine to another, to recreate hierarchy for the case of a transient guest virtual machine 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 guest virtual machine XML embedded in the snapshot). When this flag is supplied, the xmlfile argument is mandatory, and the guest virtual machine’s current snapshot will not be altered unless the --current flag is also given.
  • --no-metadata creates the snapshot, 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).
  • --reuse-external, if used and snapshot XML requests an external snapshot with a destination of an existing file, the destination must exist, and is reused; otherwise, a snapshot is refused to avoid losing contents of the existing files.
  • --quiesce libvirt will try to to freeze and unfreeze the guest virtual machine’s mounted file system(s), using the guest agent. However, if the guest virtual machine does not have a guest agent, snapshot creation will fail. The snapshot can contain the memory state of the virtual guest machine. The snapshot must be external.
  • --atomic causes libvirt to guarantee that the snapshot either succeeds, or fails with no changes. Note that not all hypervisors support this. If this flag is not specified, then some hypervisors may fail after partially performing the action, and virsh dumpxml must be used to see whether any partial changes occurred.
Existence of snapshot metadata will prevent attempts to undefine a persistent guest virtual machine. However, for transient guest virtual machines, snapshot metadata is silently lost when the guest virtual machine quits running (whether by a command such as destroy or by an internal guest action).

21.41.2. Creating a Snapshot for the Current Guest Virtual Machine

The virsh snapshot-create-as command creates a snapshot for guest virtual machine with the properties specified in the domain XML file (such as name and description elements). If these values are not included in the XML string, libvirt will choose a value. To create a snapshot run:
# snapshot-create-as domain {[--print-xml] | [--no-metadata] [--halt] [--reuse-external]} [name] [description] [--disk-only [--quiesce]] [--atomic] [[--memspec memspec]] [--diskspec] diskspec]
The remaining optional arguments are as follows:
  • --print-xmlcreates appropriate XML for snapshot-create as output, rather than actually creating a snapshot.
  • --halt keeps the guest virtual machine in an inactive state after the snapshot is created.
  • --disk-only creates a snapshot that does not include the guest virtual machine state.
  • --memspec can be used to control whether a checkpoint is internal or external. The flag is mandatory, followed by a memspec of the form [file=]name[,snapshot=type], where type can be none, internal, or external. To include a literal comma in file=name, escape it with a second comma.
  • --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]. If --diskspec is omitted for a specific disk, the default behavior in the virtual machine configuraition is used. 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:
    
    <disk name=’vda’ snapshot=’external’>
       <source file=’/path/to,new’/>
    </disk>
    

    Important

    Red Hat recommends the use of external snapshots, as they are more flexible and reliable when handled by other virtualization tools. To create an external snapshot, use the virsh-create-as command with the --diskspec vda,snapshot=external option
    If this option is not used, virsh creates internal snapshots, which are not recommended for use due to their lack of stability and optimization. For more information, see Section A.14, “Workaround for Creating External Snapshots with libvirt”.
  • --reuse-external is specified, and the domain XML or diskspec option requests an external snapshot with a destination of an existing file, then the destination must exist, and is reused; otherwise, a snapshot is refused to avoid losing contents of the existing files.
  • --quiesce is specified, libvirt will try to use guest agent to freeze and unfreeze guest virtual machine’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.
  • --no-metadata creates snapshot data but any metadata is immediately discarded (that is,libvirt does not treat the snapshot as current, and cannot revert to the snapshot unless snapshot-create is later used to teach libvirt about the metadata again). This flag is incompatible with --print-xml
  • --atomic will cause libvirt to guarantee that the snapshot either succeeds, or fails with no changes. It should be noted that not all hypervisors support this. If this flag is not specified, then some hypervisors may fail after partially performing the action, and virsh dumpxml must be used to see whether any partial changes occurred.

Warning

Creating snapshots of KVM guests running on a 64-bit ARM platform host currently does not work. Note that KVM on 64-bit ARM is provided as a Technology Preview.

21.41.3. Displaying the Snapshot Currently in Use

The virsh snapshot-current command is used to query which snapshot is currently in use.
# virsh snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
If snapshotname is not used, snapshot XML for the guest virtual machine’s current snapshot (if there is one) will be displayed as output. If --name is specified, just the current snapshot name instead of the full XML will be sent as output. If --security-info is supplied security sensitive information will be included in the XML. Using snapshotname, generates a request to make the existing named snapshot become the current snapshot, without reverting it to the guest virtual machine.

21.41.4. snapshot-edit

This command is used to edit the snapshot that is currently in use:
# virsh snapshot-edit domain [snapshotname] [--current] {[--rename] [--clone]}
If both snapshotname and --current are specified, it forces the edited snapshot to become the current snapshot. If snapshotname is omitted, then --current must be supplied, in order to edit the current snapshot.
This is equivalent to the following command sequence below, but it also includes some error checking:
# virsh snapshot-dumpxml dom name > snapshot.xml 
# vi snapshot.xml [note - this can be any editor] 
# virsh snapshot-create dom snapshot.xml --redefine [--current] 
If the --rename is specified, then the snapshot is renamed. If --clone is specified, then changing the snapshot name will create a clone of the snapshot metadata. If neither is specified, then the edits will 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 snapshot name.

21.41.5. snapshot-info

The snapshot-info domain command displays information about the snapshots. To use, run:
# snapshot-info domain {snapshot | --current}
Outputs basic information about a specified snapshot , or the current snapshot with --current.

21.41.6. snapshot-list

List all of the available snapshots for the given guest virtual machine, defaulting to show columns for the snapshot name, creation time, and guest virtual machine state. To use, run:
# virsh snapshot-list domain [{--parent | --roots | --tree}] [{[--from] snapshot | --current} [--descendants]] [--metadata] [--no-metadata] [--leaves] [--no-leaves] [--inactive] [--active] [--disk-only] [--internal] [--external]
The optional arguments are as follows:
  • --parent adds a column to the output table giving the name of the parent of each snapshot. This option may not be used with --roots or --tree.
  • --roots filters the list to show only the snapshots that have no parents. This option may not be used with --parent or --tree.
  • --tree displays output in a tree format, listing just snapshot names. This option may not be used with --roots or --parent.
  • --from filters the list to snapshots which are children of the given snapshot or, if --current is provided, will cause the list to 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.
  • --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.
  • --metadata is specified, the list will be filtered to just snapshots that involve libvirt metadata, and thus would prevent the undefining of a persistent guest virtual machine, or be lost on destroy of a transient guest virtual machine. Likewise, if --no-metadata is specified, the list will be filtered to just snapshots that exist without the need for libvirt metadata.
  • --inactive is specified, the list will be filtered to snapshots that were taken when the guest virtual machine was shut off. If --active is specified, the list will be filtered to snapshots that were taken when the guest virtual machine 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 guest virtual machine was running, but where the snapshot includes only disk state.
  • --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.

21.41.7. snapshot-dumpxml

The virsh snapshot-dumpxml domain snapshot command outputs the snapshot XML for the guest virtual machine’s snapshot named snapshot. To use, run:
# virsh snapshot-dumpxml domain snapshot [--security-info]
The --security-info option will also include security sensitive information. Use virsh snapshot-current to easily access the XML of the current snapshot.

21.41.8. snapshot-parent

Outputs the name of the parent snapshot, if any, for the given snapshot, or for the current snapshot with --current. To use, run:
# virsh snapshot-parent domain {snapshot | --current}

21.41.9. snapshot-revert

Reverts the given domain to the snapshot specified by snapshot, or to the current snapshot with --current.

Warning

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.
To revert the snapshot, run:
# virsh snapshot-revert domain {snapshot | --current} [{--running | --paused}] [--force]
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 guest virtual machine state leaves the domain in an inactive state. Passing either the --running or --paused option 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; 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.

21.41.10. snapshot-delete

The virsh snapshot-delete domain command deletes the snapshot for the specified domain. To do this, run:
# virsh snapshot-delete domain {snapshot | --current} [--metadata] [{--children | --children-only}]
This command deletes 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 the option --children is used, then it will delete this snapshot and any children of this snapshot. If --children-only is used, then it will delete any children of this snapshot, but leave this snapshot intact. These two flags are mutually exclusive.
The --metadata is used it will delete the snapshot's metadata maintained by libvirt, while leaving the snapshot contents intact for access by external tools; otherwise deleting a snapshot also removes its data contents from that point in time.