mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-25 15:15:25 +00:00
fb2236f9f7
This reverts commit 1f29f3da06.
Assuming <dt> is always used to document symbols is way too
broad, requiring far too many exemptions to be marked to
avoid syntax check rules.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
325 lines
15 KiB
XML
325 lines
15 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<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>memory state (or 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
|
|
memory 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 (memory) 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>, <code>description</code>,
|
|
and <code>disks</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>memory</code></dt>
|
|
<dd>On input, this is an optional request for how to handle VM
|
|
memory state. For an offline domain or a disk-only snapshot,
|
|
attribute <code>snapshot</code> must be <code>no</code>, since
|
|
there is no VM state saved; otherwise, the attribute can
|
|
be <code>internal</code> if the memory state is piggy-backed with
|
|
other internal disk state, or <code>external</code> along with
|
|
a second attribute <code>file</code> giving the absolute path
|
|
of the file holding the VM memory state. <span class="since">Since
|
|
1.0.1</span>
|
|
</dd>
|
|
<dt><code>disks</code></dt>
|
|
<dd>On input, this is an optional listing of specific
|
|
instructions for disk snapshots; it is needed when making a
|
|
snapshot of only a subset of the disks associated with a
|
|
domain, or when overriding the domain defaults for how to
|
|
snapshot each disk, or for providing specific control over
|
|
what file name is created in an external snapshot. On output,
|
|
this is fully populated to show the state of each disk in the
|
|
snapshot, including any properties that were generated by the
|
|
hypervisor defaults. For system checkpoints, this field is
|
|
ignored on input and omitted on output (a system checkpoint
|
|
implies that all disks participate in the snapshot process,
|
|
and since the current implementation only does internal system
|
|
checkpoints, there are no extra details to add); a future
|
|
release may allow the use of <code>disks</code> with a system
|
|
checkpoint. This element has a list of <code>disk</code>
|
|
sub-elements, describing anywhere from zero to all of the
|
|
disks associated with the domain. <span class="since">Since
|
|
0.9.5</span>
|
|
<dl>
|
|
<dt><code>disk</code></dt>
|
|
<dd>This sub-element describes the snapshot properties of a
|
|
specific disk. The attribute <code>name</code> is
|
|
mandatory, and must match either the <code><target
|
|
dev='name'/></code> or an unambiguous <code><source
|
|
file='name'/></code> of one of
|
|
the <a href="formatdomain.html#elementsDisks">disk
|
|
devices</a> specified for the domain at the time of the
|
|
snapshot. The attribute <code>snapshot</code> is
|
|
optional, and the possible values are the same as the
|
|
<code>snapshot</code> attribute for
|
|
<a href="formatdomain.html#elementsDisks">disk devices</a>
|
|
(<code>no</code>, <code>internal</code>,
|
|
or <code>external</code>). Some hypervisors like ESX
|
|
require that if specified, the snapshot mode must not
|
|
override any snapshot mode attached to the corresponding
|
|
domain disk, while others like qemu allow this field to
|
|
override the domain default.
|
|
|
|
<dl>
|
|
<dt><code>source</code></dt>
|
|
<dd>If the snapshot mode is external (whether specified
|
|
or inherited), then there is an optional sub-element
|
|
<code>source</code>, with an attribute <code>file</code>
|
|
giving the name of the new file.
|
|
If <code>source</code> is not
|
|
given and the disk is backed by a local image file (not
|
|
a block device or remote storage), a file name is
|
|
generated that consists of the existing file name
|
|
with anything after the trailing dot replaced by the
|
|
snapshot name. Remember that with external
|
|
snapshots, the original file name becomes the read-only
|
|
snapshot, and the new file name contains the read-write
|
|
delta of all disk changes since the snapshot.
|
|
</dd>
|
|
<dt><code>driver</code></dt>
|
|
<dd>An optional sub-element <code>driver</code>,
|
|
with an attribute <code>type</code> giving the driver type (such
|
|
as qcow2), of the new file created by the external
|
|
snapshot of the new file.
|
|
</dd>
|
|
</dl>
|
|
|
|
<span class="since">Since 1.2.2</span> the <code>disk</code> element
|
|
supports an optional attribute <code>type</code> if the
|
|
<code>snapshot</code> attribute is set to <code>external</code>.
|
|
This attribute specifies the snapshot target storage type and allows
|
|
to overwrite the default <code>file</code> type. The <code>type</code>
|
|
attribute along with the format of the <code>source</code>
|
|
sub-element is identical to the <code>source</code> element used in
|
|
domain disk definitions. See the
|
|
<a href="formatdomain.html#elementsDisks">disk devices</a> section
|
|
documentation for further information.
|
|
|
|
Libvirt currently supports the <code>type</code> element in the qemu
|
|
driver and supported values are <code>file</code>, <code>block</code>
|
|
and <code>network</code> with a protocol of <code>gluster</code>
|
|
<span class="since">(since 1.2.2)</span>.
|
|
</dd>
|
|
</dl>
|
|
</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 memory 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 to create a disk snapshot of just vda on a qemu
|
|
domain with two disks:</p>
|
|
<pre>
|
|
<domainsnapshot>
|
|
<description>Snapshot of OS install and updates</description>
|
|
<disks>
|
|
<disk name='/path/to/old'>
|
|
<source file='/path/to/new'/>
|
|
</disk>
|
|
<disk name='vdb' snapshot='no'/>
|
|
</disks>
|
|
</domainsnapshot></pre>
|
|
|
|
<p>will result in XML similar to this from
|
|
<code>virDomainSnapshotGetXMLDesc()</code>:</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>
|
|
<memory snapshot='no'/>
|
|
<disks>
|
|
<disk name='vda' snapshot='external'>
|
|
<driver type='qcow2'/>
|
|
<b><source file='/path/to/new'/></b>
|
|
</disk>
|
|
<disk name='vdb' snapshot='no'/>
|
|
</disks>
|
|
<domain>
|
|
<name>fedora</name>
|
|
<uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
|
|
<memory>1048576</memory>
|
|
...
|
|
<devices>
|
|
<disk type='file' device='disk'>
|
|
<driver name='qemu' type='raw'/>
|
|
<b><source file='/path/to/old'/></b>
|
|
<target dev='vda' bus='virtio'/>
|
|
</disk>
|
|
<disk type='file' device='disk' snapshot='external'>
|
|
<driver name='qemu' type='raw'/>
|
|
<source file='/path/to/old2'/>
|
|
<target dev='vdb' bus='virtio'/>
|
|
</disk>
|
|
...
|
|
</devices>
|
|
</domain>
|
|
</domainsnapshot></pre>
|
|
|
|
<p>With that snapshot created, <code>/path/to/old</code> is the
|
|
read-only backing file to the new active
|
|
file <code>/path/to/new</code>. The <code><domain></code>
|
|
element within the snapshot xml records the state of the domain
|
|
just before the snapshot; a call
|
|
to <code>virDomainGetXMLDesc()</code> will show that the domain
|
|
has been changed to reflect the snapshot:
|
|
</p>
|
|
<pre>
|
|
<domain>
|
|
<name>fedora</name>
|
|
<uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
|
|
<memory>1048576</memory>
|
|
...
|
|
<devices>
|
|
<disk type='file' device='disk'>
|
|
<driver name='qemu' type='qcow2'/>
|
|
<b><source file='/path/to/new'/></b>
|
|
<target dev='vda' bus='virtio'/>
|
|
</disk>
|
|
<disk type='file' device='disk' snapshot='external'>
|
|
<driver name='qemu' type='raw'/>
|
|
<source file='/path/to/old2'/>
|
|
<target dev='vdb' bus='virtio'/>
|
|
</disk>
|
|
...
|
|
</devices>
|
|
</domain></pre>
|
|
</body>
|
|
</html>
|