mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 05:35:25 +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:
Peter Krempa
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',
|
||||
'formatnwfilter',
|
||||
'formatsecret',
|
||||
'formatsnapshot',
|
||||
'formatstoragecaps',
|
||||
'formatstorageencryption',
|
||||
'goals',
|
||||
@ -99,6 +98,7 @@ docs_rst_files = [
|
||||
'formatbackup',
|
||||
'formatcheckpoint',
|
||||
'formatdomain',
|
||||
'formatsnapshot',
|
||||
'formatstorage',
|
||||
'glib-adoption',
|
||||
'hacking',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user