formatsnapshot.html.in

<html>
  <body>
    <h1>Snapshot XML format</h1>

    <ul id="toc"></ul>

    <h2><a name="SnapshotAttributes">Snapshot XML</a></h2>

    <p>
      There are several types of snapshots:
    </p>
    <dl>
      <dt>disk snapshot</dt>
      <dd>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).</dd>
      <dt>VM state</dt>
      <dd>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.</dd>
      <dt>system checkpoint</dt>
      <dd>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).</dd>
    </dl>

    <p>
      Libvirt can manage all three types of snapshots.  For now, VM
      state snapshots are created only by
      the <code>virDomainSave()</code>, <code>virDomainSaveFlags</code>,
      and <code>virDomainManagedSave()</code> functions, and restored
      via the <code>virDomainRestore()</code>,
      <code>virDomainRestoreFlags()</code>, <code>virDomainCreate()</code>,
      and <code>virDomainCreateWithFlags()</code> 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 <code>virDomainSaveImageGetXMLDesc()</code> to work with
      those files.
    </p>
    <p>System checkpoints are created
      by <code>virDomainSnapshotCreateXML()</code> with no flags, and
      disk snapshots are created by the same function with
      the <code>VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY</code> flag; in
      both cases, they are restored by
      the <code>virDomainRevertToSnapshot()</code> function.  For
      these types of snapshots, libvirt tracks each snapshot as a
      separate <code>virDomainSnapshotPtr</code> object, and maintains
      a tree relationship of which snapshots descended from an earlier
      point in time.
    </p>

    <p>
      Attributes of libvirt snapshots are stored as child elements of
      the <code>domainsnapshot</code> element.  At snapshot creation
      time, normally only the <code>name</code>
      and <code>description</code> elements are settable; the rest of
      the fields are ignored on creation, and will be filled in by
      libvirt in for informational purposes
      by <code>virDomainSnapshotGetXMLDesc()</code>.  However, when
      redefining a snapshot (<span class="since">since 0.9.5</span>),
      with the <code>VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE</code> flag
      of <code>virDomainSnapshotCreateXML()</code>, all of the XML
      described here is relevant.
    </p>
    <p>
      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.
    </p>
    <p>
      The top-level <code>domainsnapshot</code> element may contain
      the following elements:
    </p>
    <dl>
      <dt><code>name</code></dt>
      <dd>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.
      </dd>
      <dt><code>description</code></dt>
      <dd>A human-readable description of the snapshot.  If the
        description is omitted when initially creating the snapshot,
        then this field will be empty.
      </dd>
      <dt><code>creationTime</code></dt>
      <dd>The time this snapshot was created.  The time is specified
        in seconds since the Epoch, UTC (i.e. Unix time).  Readonly.
      </dd>
      <dt><code>state</code></dt>
      <dd>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 <code>virDomainRevertToSnapshot()</code>.  Additionally,
        this field can be the value "disk-snapshot"
        (<span class="since">since 0.9.5</span>) when it represents
        only a disk snapshot (no VM state), and reverting to this
        snapshot will default to an inactive guest.  Readonly.
      </dd>
      <dt><code>parent</code></dt>
      <dd>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.
      </dd>
      <dt><code>domain</code></dt>
      <dd>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
        <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
        in <code>virDomainRevertToSnapshot()</code>.  Newer versions
        of libvirt (<span class="since">since 0.9.5</span>) store the entire
        inactive <a href="formatdomain.html">domain configuration</a>
        at the time of the snapshot (<span class="since">since
        0.9.5</span>).  Readonly.
      </dd>
    </dl>

    <h2><a name="example">Examples</a></h2>

    <p>Using this XML on creation:</p>
    <pre>
&lt;domainsnapshot&gt;
  &lt;description&gt;Snapshot of OS install and updates&lt;/description&gt;
&lt;/domainsnapshot&gt;</pre>

    <p>will result in XML similar to this from
    virDomainSnapshotGetXMLDesc:</p>
    <pre>
&lt;domainsnapshot&gt;
  &lt;name&gt;1270477159&lt;/name&gt;
  &lt;description&gt;Snapshot of OS install and updates&lt;/description&gt;
  &lt;state&gt;running&lt;/state&gt;
  &lt;creationTime&gt;1270477159&lt;/creationTime&gt;
  &lt;parent&gt;
    &lt;name&gt;bare-os-install&lt;/name&gt;
  &lt;/parent&gt;
  &lt;domain&gt;
    &lt;name&gt;fedora&lt;/name&gt;
    &lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt;
    &lt;memory&gt;1048576&lt;/memory&gt;
    ...
    &lt;/devices&gt;
  &lt;/domain&gt;
&lt;/domainsnapshot&gt;</pre>
  </body>
</html>