mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-26 23:55:23 +00:00
1f29f3da06
Commit 61b070cf20 cleaned up a number of cases where the <dt>
element was used to document symbols, but the symbol itself was
not inside a <code> element.
To make sure we don't end up having to clean up again a few
months from now, introduce a syntax-check rule that can spot
such mistakes.
All existing exceptions are marked as such, with either file
or line granularity depending on the case.
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> <!-- exempt from syntax-check -->
|
|
<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> <!-- exempt from syntax-check -->
|
|
<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> <!-- exempt from syntax-check -->
|
|
<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>
|