mirror of https://gitee.com/openkylin/libvirt.git
349 lines
16 KiB
XML
349 lines
16 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<body>
|
|
<h1>Snapshot XML format</h1>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<h2><a id="SnapshotAttributes">Snapshot XML</a></h2>
|
|
|
|
<p>
|
|
Snapshots are one form
|
|
of <a href="kbase/domainstatecapture.html">domain state
|
|
capture</a>. 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>full system</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>Full system snapshots are created
|
|
by <code>virDomainSnapshotCreateXML()</code> with no flags, while
|
|
disk snapshots are created by the same function with
|
|
the <code>VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY</code>
|
|
flag. Regardless of the flags provided, restoration of the
|
|
snapshot is handled 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 on input, even the fields that are
|
|
normally described as readonly for output.
|
|
</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. For now, the creation of external snapshots
|
|
when checkpoints exist is forbidden, although future work will
|
|
make it possible to integrate these two concepts.
|
|
</p>
|
|
<p>
|
|
The top-level <code>domainsnapshot</code> element may contain
|
|
the following elements:
|
|
</p>
|
|
<dl>
|
|
<dt><code>name</code></dt>
|
|
<dd>The optional name for this snapshot. If the name is
|
|
omitted, libvirt will create a name based on the time of the
|
|
creation.
|
|
</dd>
|
|
<dt><code>description</code></dt>
|
|
<dd>An optional 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 full system snapshots, this field is
|
|
ignored on input and omitted on output (a full system snapshot
|
|
implies that all disks participate in the snapshot process).
|
|
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> (recommended) 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.
|
|
<p/>
|
|
The <code>source</code> element also may contain the
|
|
<code>seclabel</code> element (described in the
|
|
<a href="formatdomain.html#seclabel">domain XML documentation</a>)
|
|
which can be used to override the domain security labeling policy
|
|
for <code>source</code>.
|
|
</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>
|
|
<dt><code>seclabel</code></dt>
|
|
</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>A readonly representation of the time this snapshot was
|
|
created. The time is specified in seconds since the Epoch,
|
|
UTC (i.e. Unix time).
|
|
</dd>
|
|
<dt><code>state</code></dt>
|
|
<dd>A readonly representation of the state of the domain at the
|
|
time this snapshot was taken. If a full system snapshot was
|
|
created, 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 this state, unless overridden
|
|
by <code>virDomainRevertToSnapshot()</code> flags to revert to
|
|
a running or paused state. 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.
|
|
</dd>
|
|
<dt><code>parent</code></dt>
|
|
<dd>Readonly, present only if this snapshot has a parent. The
|
|
parent name is given by the sub-element <code>name</code>. The
|
|
parent relationship allows tracking a tree of related snapshots.
|
|
</dd>
|
|
<dt><code>domain</code></dt>
|
|
<dd>A readonly representation of 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>). The domain will have
|
|
security-sensitive information omitted
|
|
unless the flag <code>VIR_DOMAIN_SNAPSHOT_XML_SECURE</code> is
|
|
provided on a read-write connection.
|
|
</dd>
|
|
<dt><code>cookie</code></dt>
|
|
<dd>An optional readonly representation of a save image cookie
|
|
containing additional data libvirt may need to properly
|
|
restore a domain from an active snapshot when such data cannot
|
|
be stored directly in the <code>domain</code> to maintain
|
|
compatibility with older libvirt or hypervisor.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2><a id="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='vda'>
|
|
<source file='/path/to/new'/>
|
|
</disk>
|
|
<disk name='vdb' snapshot='no'/>
|
|
<disk name='vdc'>
|
|
<source file='/path/to/newc'>
|
|
<seclabel model='dac' relabel='no'/>
|
|
</source>
|
|
</disk>
|
|
</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>
|