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
--haltis specified, the domain will be left in an inactive state after the snapshot is created. - If
--disk-onlyis 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--haltand--disk-onlyloses any data that was not flushed to disk at the time. - If
--redefineis specified, then all XML elements produced bysnapshot-dumpxmlare 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, thexmlfileargument is mandatory, and the domain's current snapshot will not be altered unless the--currentflag is also given. - If
--no-metadatais 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--redefineis later used to teach libvirt about the metadata again). - If
--reuse-externalis 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
--quiesceis 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-onlyto be passed as well. - If
--atomicis 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, anddumpxmlmust be used to see whether any partial changes occurred. - If
--liveis 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:
Unnamed and named (via xmlfile) snapshot creation:
Shutdown after creation with --halt:
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
--memspecoption can be used to control whether a checkpoint is internal or external. The--memspecflag is mandatory, followed by amemspecof the form[file=]name[,snapshot=type], where type can beno,internal, orexternal. To include a literal comma infile=name, escape it with a second comma.--memspeccannot be used together with--disk-only. - The
--diskspecoption can be used to control how--disk-onlyand 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 formdisk[,snapshot=type][,driver=type][,file=name]. Adiskspecmust be provided for disks backed by block devices as libvirt doesn't auto-generate file names for those. To include a literal comma indiskor infile=name, escape it with a second comma. A literal--diskspecmust precede eachdiskspecunless all three of domain, name, and description are also present. For example, a diskspec ofvda,snapshot=external,file=/path/to,,newresults in the following XML: --no-metadata- same as insnapshot-create. This flag is incompatible with--print-xml.
snapshot-create-as examples
Full external snapshot:
Disk only external 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:
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:
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:
Edit snapshot nm and clone it:
snapshot-info
snapshot-info domain {snapshot | --current}
Output basic information about a named <snapshot>, or the current snapshot with --current.
snapshot-info examples
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
--parentis specified, add a column to the output table giving the name of the parent of each snapshot. If--rootsis specified, the list will be filtered to just snapshots that have no parents. If--treeis specified, the output will be in a tree format, listing just snapshot names. These three options are mutually exclusive. If--nameis specified only the snapshot name is printed. This option is mutually exclusive with--tree. - If
--fromis provided, filter the list to snapshots which are children of the given snapshot; or if--currentis provided, start at the current snapshot. When used in isolation or with--parent, the list is limited to direct children unless--descendantsis also present. When used with--tree, the use of--descendantsis implied. This option is not compatible with--roots. Note that the starting point of--fromor--currentis not included in the list unless the--treeoption is also present. - If
--leavesis specified, the list will be filtered to just snapshots that have no children. Likewise, if--no-leavesis 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
--metadatais specified, the list will be filtered to just snapshots that involve libvirt metadata, and thus would preventundefineof a persistent domain, or be lost on destroy of a transient domain. Likewise, if--no-metadatais specified, the list will be filtered to just snapshots that exist without the need for libvirt metadata. - If
--inactiveis specified, the list will be filtered to snapshots that were taken when the domain was shut off. If--activeis 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-onlyis 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
--internalis specified, the list will be filtered to snapshots that use internal storage of existing disk images. If--externalis specified, the list will be filtered to snapshots that use external files for disk images or memory state.
snapshot-list examples
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-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
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
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.
Delete name2 and its children (name3):
Delete only 1519723398: