mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-09-09 01:04:59 +00:00
docs: formatsnapshot: Convert to 'rst'
Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
parent
c30df02ca3
commit
33a751fdc4
@ -1,352 +0,0 @@
|
|||||||
<?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.
|
|
||||||
|
|
||||||
Optionally <code>metadata_cache</code> sub-element can be used
|
|
||||||
with same semantics as the identically named subelement of the
|
|
||||||
domain definition disk's driver.
|
|
||||||
</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>
|
|
297
docs/formatsnapshot.rst
Normal file
297
docs/formatsnapshot.rst
Normal file
@ -0,0 +1,297 @@
|
|||||||
|
.. role:: since
|
||||||
|
|
||||||
|
===================
|
||||||
|
Snapshot XML format
|
||||||
|
===================
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Snapshot XML
|
||||||
|
------------
|
||||||
|
|
||||||
|
Snapshots are one form of `domain state
|
||||||
|
capture <kbase/domainstatecapture.html>`__. There are several types of
|
||||||
|
snapshots:
|
||||||
|
|
||||||
|
disk snapshot
|
||||||
|
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).
|
||||||
|
memory state (or VM state)
|
||||||
|
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.
|
||||||
|
full system
|
||||||
|
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).
|
||||||
|
|
||||||
|
Libvirt can manage all three types of snapshots. For now, VM state (memory)
|
||||||
|
snapshots are created only by the ``virDomainSave()``, ``virDomainSaveFlags``,
|
||||||
|
and ``virDomainManagedSave()`` functions, and restored via the
|
||||||
|
``virDomainRestore()``, ``virDomainRestoreFlags()``, ``virDomainCreate()``, and
|
||||||
|
``virDomainCreateWithFlags()`` 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
|
||||||
|
``virDomainSaveImageGetXMLDesc()`` to work with those files.
|
||||||
|
|
||||||
|
Full system snapshots are created by ``virDomainSnapshotCreateXML()`` with no
|
||||||
|
flags, while disk snapshots are created by the same function with the
|
||||||
|
``VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY`` flag. Regardless of the flags provided,
|
||||||
|
restoration of the snapshot is handled by the ``virDomainRevertToSnapshot()``
|
||||||
|
function. For these types of snapshots, libvirt tracks each snapshot as a
|
||||||
|
separate ``virDomainSnapshotPtr`` object, and maintains a tree relationship of
|
||||||
|
which snapshots descended from an earlier point in time.
|
||||||
|
|
||||||
|
Attributes of libvirt snapshots are stored as child elements of the
|
||||||
|
``domainsnapshot`` element. At snapshot creation time, normally only the
|
||||||
|
``name``, ``description``, and ``disks`` elements are settable; the rest of the
|
||||||
|
fields are ignored on creation, and will be filled in by libvirt in for
|
||||||
|
informational purposes by ``virDomainSnapshotGetXMLDesc()``. However, when
|
||||||
|
redefining a snapshot ( :since:`since 0.9.5` ), with the
|
||||||
|
``VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE`` flag of
|
||||||
|
``virDomainSnapshotCreateXML()``, all of the XML described here is relevant on
|
||||||
|
input, even the fields that are normally described as readonly for output.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
The top-level ``domainsnapshot`` element may contain the following elements:
|
||||||
|
|
||||||
|
``name``
|
||||||
|
|
||||||
|
The optional name for this snapshot. If the name is omitted, libvirt will
|
||||||
|
create a name based on the time of the creation.
|
||||||
|
|
||||||
|
``description``
|
||||||
|
|
||||||
|
An optional human-readable description of the snapshot. If the description
|
||||||
|
is omitted when initially creating the snapshot, then this field will be
|
||||||
|
empty.
|
||||||
|
|
||||||
|
``memory``
|
||||||
|
|
||||||
|
On input, this is an optional request for how to handle VM memory state. For
|
||||||
|
an offline domain or a disk-only snapshot, attribute ``snapshot`` must be
|
||||||
|
``no``, since there is no VM state saved; otherwise, the attribute can be
|
||||||
|
``internal`` if the memory state is piggy-backed with other internal disk
|
||||||
|
state, or ``external`` along with a second attribute ``file`` giving the
|
||||||
|
absolute path of the file holding the VM memory state. :since:`Since 1.0.1`
|
||||||
|
|
||||||
|
``disks``
|
||||||
|
|
||||||
|
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 ``disk`` sub-elements, describing anywhere from zero to all of the disks
|
||||||
|
associated with the domain. :since:`Since 0.9.5`
|
||||||
|
|
||||||
|
``disk``
|
||||||
|
|
||||||
|
This sub-element describes the snapshot properties of a specific disk.
|
||||||
|
The attribute ``name`` is mandatory, and must match either the ``<target
|
||||||
|
dev='name'/>`` (recommended) or an unambiguous ``<source file='name'/>``
|
||||||
|
of one of the `disk devices <formatdomain.html#elementsDisks>`__
|
||||||
|
specified for the domain at the time of the snapshot. The attribute
|
||||||
|
``snapshot`` is optional, and the possible values are the same as the
|
||||||
|
``snapshot`` attribute for `disk devices
|
||||||
|
<formatdomain.html#elementsDisks>`__ (``no``, ``internal``, or
|
||||||
|
``external``). 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.
|
||||||
|
|
||||||
|
``source``
|
||||||
|
|
||||||
|
If the snapshot mode is external (whether specified or inherited),
|
||||||
|
then there is an optional sub-element ``source``, with an attribute
|
||||||
|
``file`` giving the name of the new file. If ``source`` 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.
|
||||||
|
|
||||||
|
The ``source`` element also may contain the ``seclabel`` element
|
||||||
|
(described in the `domain XML documentation
|
||||||
|
<formatdomain.html#seclabel>`__) which can be used to override the
|
||||||
|
domain security labeling policy for ``source``.
|
||||||
|
|
||||||
|
``driver``
|
||||||
|
|
||||||
|
An optional sub-element ``driver``, with an attribute ``type`` giving
|
||||||
|
the driver type (such as qcow2), of the new file created by the
|
||||||
|
external snapshot of the new file. Optionally ``metadata_cache``
|
||||||
|
sub-element can be used with same semantics as the identically named
|
||||||
|
subelement of the domain definition disk's driver.
|
||||||
|
|
||||||
|
``seclabel``
|
||||||
|
|
||||||
|
:since:`Since 1.2.2` the ``disk`` element supports an optional attribute
|
||||||
|
``type`` if the ``snapshot`` attribute is set to ``external``. This
|
||||||
|
attribute specifies the snapshot target storage type and allows to
|
||||||
|
overwrite the default ``file`` type. The ``type`` attribute along with
|
||||||
|
the format of the ``source`` sub-element is identical to the ``source``
|
||||||
|
element used in domain disk definitions. See the `disk devices
|
||||||
|
<formatdomain.html#elementsDisks>`__ section documentation for further
|
||||||
|
information. Libvirt currently supports the ``type`` element in the qemu
|
||||||
|
driver and supported values are ``file``, ``block`` and ``network`` with
|
||||||
|
a protocol of ``gluster`` :since:`(since 1.2.2)` .
|
||||||
|
|
||||||
|
``creationTime``
|
||||||
|
|
||||||
|
A readonly representation of the time this snapshot was created. The time is
|
||||||
|
specified in seconds since the Epoch, UTC (i.e. Unix time).
|
||||||
|
|
||||||
|
``state``
|
||||||
|
|
||||||
|
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 ``virDomainRevertToSnapshot()`` flags to revert to a running or paused
|
||||||
|
state. Additionally, this field can be the value "disk-snapshot" (
|
||||||
|
:since:`since 0.9.5`) when it represents only a disk snapshot (no VM memory
|
||||||
|
state), and reverting to this snapshot will default to an inactive guest.
|
||||||
|
|
||||||
|
``parent``
|
||||||
|
|
||||||
|
Readonly, present only if this snapshot has a parent. The parent name is
|
||||||
|
given by the sub-element ``name``. The parent relationship allows tracking a
|
||||||
|
tree of related snapshots.
|
||||||
|
|
||||||
|
``domain``
|
||||||
|
|
||||||
|
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 ``VIR_DOMAIN_SNAPSHOT_REVERT_FORCE`` flag in
|
||||||
|
``virDomainRevertToSnapshot()``. Newer versions of libvirt ( :since:`since
|
||||||
|
0.9.5` ) store the entire inactive `domain configuration
|
||||||
|
<formatdomain.html>`__ at the time of the snapshot ( :since:`since 0.9.5` ).
|
||||||
|
The domain will have security-sensitive information omitted unless the flag
|
||||||
|
``VIR_DOMAIN_SNAPSHOT_XML_SECURE`` is provided on a read-write connection.
|
||||||
|
|
||||||
|
``cookie``
|
||||||
|
|
||||||
|
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 ``domain`` to
|
||||||
|
maintain compatibility with older libvirt or hypervisor.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Using this XML to create a disk snapshot of just vda on a qemu domain with two
|
||||||
|
disks:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
<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>
|
||||||
|
|
||||||
|
will result in XML similar to this from ``virDomainSnapshotGetXMLDesc()``:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
<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'/>
|
||||||
|
<source file='/path/to/new'/>
|
||||||
|
</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'/>
|
||||||
|
<source file='/path/to/old'/>
|
||||||
|
<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>
|
||||||
|
|
||||||
|
With that snapshot created, ``/path/to/old`` is the read-only backing file to
|
||||||
|
the new active file ``/path/to/new``. The ``<domain>`` element within the
|
||||||
|
snapshot xml records the state of the domain just before the snapshot; a call to
|
||||||
|
``virDomainGetXMLDesc()`` will show that the domain has been changed to reflect
|
||||||
|
the snapshot:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
<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'/>
|
||||||
|
<source file='/path/to/new'/>
|
||||||
|
<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>
|
@ -51,7 +51,6 @@ docs_html_in_files = [
|
|||||||
'formatnode',
|
'formatnode',
|
||||||
'formatnwfilter',
|
'formatnwfilter',
|
||||||
'formatsecret',
|
'formatsecret',
|
||||||
'formatsnapshot',
|
|
||||||
'formatstoragecaps',
|
'formatstoragecaps',
|
||||||
'formatstorageencryption',
|
'formatstorageencryption',
|
||||||
'goals',
|
'goals',
|
||||||
@ -99,6 +98,7 @@ docs_rst_files = [
|
|||||||
'formatbackup',
|
'formatbackup',
|
||||||
'formatcheckpoint',
|
'formatcheckpoint',
|
||||||
'formatdomain',
|
'formatdomain',
|
||||||
|
'formatsnapshot',
|
||||||
'formatstorage',
|
'formatstorage',
|
||||||
'glib-adoption',
|
'glib-adoption',
|
||||||
'hacking',
|
'hacking',
|
||||||
|
Loading…
Reference in New Issue
Block a user