Snapshot XML format

Snapshot XML

There are several types of snapshots:

disk snapshot: Contents of disks (whether a subset or all disks associated with the domain) are saved at a given point of time, and can be restored back to that state. On a running guest, a disk snapshot is likely to be only crash-consistent rather than clean (that is, it represents the state of the disk on a sudden power outage, and may need fsck or journal replays to be made consistent); on an inactive guest, a disk snapshot is clean if the disks were clean when the guest was last shut down. Disk snapshots exist in two forms: internal (file formats such as qcow2 track both the snapshot and changes since the snapshot in a single file) and external (the snapshot is one file, and the changes since the snapshot are in another file).
VM state: Tracks only the state of RAM and all other resources in use by the VM. If the disks are unmodified between the time a VM state snapshot is taken and restored, then the guest will resume in a consistent state; but if the disks are modified externally in the meantime, this is likely to lead to data corruption.
system checkpoint: A combination of disk snapshots for all disks as well as VM state, which can be used to resume the guest from where it left off with symptoms similar to hibernation (that is, TCP connections in the guest may have timed out, but no files or processes are lost).

Libvirt can manage all three types of snapshots. For now, VM state snapshots are created only by the virDomainSave(), virDomainSaveFlags, and virDomainManagedSave() functions, and restored via the virDomainRestore(), virDomainRestoreFlags(), virDomainCreate(), and virDomainCreateWithFlags() functions (as well as via domain autostart). With managed snapshots, libvirt tracks all information internally; with save images, the user tracks the snapshot file, but libvirt provides functions such as virDomainSaveImageGetXMLDesc() to work with those files.

System checkpoints are created by virDomainSnapshotCreateXML() with no flags, and disk snapshots are created by the same function with the VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY flag; in both cases, they are restored by the virDomainRevertToSnapshot() function. For these types of snapshots, libvirt tracks each snapshot as a separate virDomainSnapshotPtr object, and maintains a tree relationship of which snapshots descended from an earlier point in time.

Attributes of libvirt snapshots are stored as child elements of the domainsnapshot element. At snapshot creation time, normally only the name and description elements are settable; the rest of the fields are ignored on creation, and will be filled in by libvirt in for informational purposes by virDomainSnapshotGetXMLDesc(). However, when redefining a snapshot (since 0.9.5), with the VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE flag of virDomainSnapshotCreateXML(), all of the XML described here is relevant.

Snapshots are maintained in a hierarchy. A domain can have a current snapshot, which is the most recent snapshot compared to the current state of the domain (although a domain might have snapshots without a current snapshot, if snapshots have been deleted in the meantime). Creating or reverting to a snapshot sets that snapshot as current, and the prior current snapshot is the parent of the new snapshot. Branches in the hierarchy can be formed by reverting to a snapshot with a child, then creating another snapshot.

The top-level domainsnapshot element may contain the following elements:

name: The name for this snapshot. If the name is specified when initially creating the snapshot, then the snapshot will have that particular name. If the name is omitted when initially creating the snapshot, then libvirt will make up a name for the snapshot, based on the time when it was created.
description: A human-readable description of the snapshot. If the description is omitted when initially creating the snapshot, then this field will be empty.
creationTime: The time this snapshot was created. The time is specified in seconds since the Epoch, UTC (i.e. Unix time). Readonly.
state: The state of the domain at the time this snapshot was taken. If the snapshot was created as a system checkpoint, then this is the state of the domain at that time; when the domain is reverted to this snapshot, the domain's state will default to whatever is in this field unless additional flags are passed to virDomainRevertToSnapshot(). Additionally, this field can be the value "disk-snapshot" (since 0.9.5) when it represents only a disk snapshot (no VM state), and reverting to this snapshot will default to an inactive guest. Readonly.
parent: The parent of this snapshot. If present, this element contains exactly one child element, name. This specifies the name of the parent snapshot of this snapshot, and is used to represent trees of snapshots. Readonly.
domain: The domain that this snapshot was taken against. Older versions of libvirt stored only a single child element, uuid; reverting to a snapshot like this is risky if the current state of the domain differs from the state that the domain was created in, and requires the use of the VIR_DOMAIN_SNAPSHOT_REVERT_FORCE flag in virDomainRevertToSnapshot(). Newer versions of libvirt (since 0.9.5) store the entire inactive domain configuration at the time of the snapshot (since 0.9.5). Readonly.

Examples

Using this XML on creation:

<domainsnapshot>
  <description>Snapshot of OS install and updates</description>
</domainsnapshot>

will result in XML similar to this from virDomainSnapshotGetXMLDesc:

<domainsnapshot>
  <name>1270477159</name>
  <description>Snapshot of OS install and updates</description>
  <state>running</state>
  <creationTime>1270477159</creationTime>
  <parent>
    <name>bare-os-install</name>
  </parent>
  <domain>
    <name>fedora</name>
    <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
    <memory>1048576</memory>
    ...
    </devices>
  </domain>
</domainsnapshot>