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 bysnapshot-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, thexmlfile
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, anddumpxml
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:
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
--memspec
option can be used to control whether a checkpoint is internal or external. The--memspec
flag is mandatory, followed by amemspec
of 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.--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 formdisk[,snapshot=type][,driver=type][,file=name]
. Adiskspec
must be provided for disks backed by block devices as libvirt doesn't auto-generate file names for those. To include a literal comma indisk
or infile=name
, escape it with a second comma. A literal--diskspec
must precede eachdiskspec
unless all three of domain, name, and description are also present. For example, a diskspec ofvda,snapshot=external,file=/path/to,,new
results 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
--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 preventundefine
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
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: