mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-10-12 09:09:17 +00:00
5b30b08d66
In order to distinguish disk snapshots from system checkpoints, a new state value that is only valid for snapshots is helpful. * include/libvirt/libvirt.h.in (VIR_DOMAIN_LAST): New placeholder. * src/conf/domain_conf.h (virDomainSnapshotState): New enum mapping. (VIR_DOMAIN_DISK_SNAPSHOT): New internal enum value. * src/conf/domain_conf.c (virDomainState): Use placeholder. (virDomainSnapshotState): Extend mapping by one for use in snapshot. (virDomainSnapshotDefParseString, virDomainSnapshotDefFormat): Handle new state. (virDomainObjSetState, virDomainStateReasonToString) (virDomainStateReasonFromString): Avoid compiler warnings. * tools/virsh.c (vshDomainState, vshDomainStateReasonToString): Likewise. * src/libvirt_private.syms (domain_conf.h): Export new functions. * docs/schemas/domainsnapshot.rng: Tighten state definition. * docs/formatsnapshot.html.in: Document it. * tests/domainsnapshotxml2xmlout/disk_snapshot.xml: New test.
175 lines
7.8 KiB
HTML
175 lines
7.8 KiB
HTML
<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>
|
|
<domainsnapshot>
|
|
<description>Snapshot of OS install and updates</description>
|
|
</domainsnapshot></pre>
|
|
|
|
<p>will result in XML similar to this from
|
|
virDomainSnapshotGetXMLDesc:</p>
|
|
<pre>
|
|
<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></pre>
|
|
</body>
|
|
</html>
|