External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 13:45:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: formatsnapshot: Convert to 'rst'

Browse Source 
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
Peter Krempa 2022-03-04 15:55:40 +01:00
parent c30df02ca3
commit 33a751fdc4
3 changed files with 298 additions and 353 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

352
docs/formatsnapshot.html.in
View File

@ -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>&lt;target
dev='name'/&gt;</code> (recommended) or an unambiguous
<code>&lt;source file='name'/&gt;</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>
&lt;domainsnapshot&gt;
&lt;description&gt;Snapshot of OS install and updates&lt;/description&gt;
&lt;disks&gt;
&lt;disk name='vda'&gt;
&lt;source file='/path/to/new'/&gt;
&lt;/disk&gt;
&lt;disk name='vdb' snapshot='no'/&gt;
&lt;disk name='vdc'&gt;
&lt;source file='/path/to/newc'&gt;
&lt;seclabel model='dac' relabel='no'/&gt;
&lt;/source&gt;
&lt;/disk&gt;
&lt;/disks&gt;
&lt;/domainsnapshot&gt;</pre>
<p>will result in XML similar to this from
<code>virDomainSnapshotGetXMLDesc()</code>:</p>
<pre>
&lt;domainsnapshot&gt;
&lt;name&gt;1270477159&lt;/name&gt;
&lt;description&gt;Snapshot of OS install and updates&lt;/description&gt;
&lt;state&gt;running&lt;/state&gt;
&lt;creationTime&gt;1270477159&lt;/creationTime&gt;
&lt;parent&gt;
&lt;name&gt;bare-os-install&lt;/name&gt;
&lt;/parent&gt;
&lt;memory snapshot='no'/&gt;
&lt;disks&gt;
&lt;disk name='vda' snapshot='external'&gt;
&lt;driver type='qcow2'/&gt;
<b>&lt;source file='/path/to/new'/&gt;</b>
&lt;/disk&gt;
&lt;disk name='vdb' snapshot='no'/&gt;
&lt;/disks&gt;
&lt;domain&gt;
&lt;name&gt;fedora&lt;/name&gt;
&lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt;
&lt;memory&gt;1048576&lt;/memory&gt;
...
&lt;devices&gt;
&lt;disk type='file' device='disk'&gt;
&lt;driver name='qemu' type='raw'/&gt;
<b>&lt;source file='/path/to/old'/&gt;</b>
&lt;target dev='vda' bus='virtio'/&gt;
&lt;/disk&gt;
&lt;disk type='file' device='disk' snapshot='external'&gt;
&lt;driver name='qemu' type='raw'/&gt;
&lt;source file='/path/to/old2'/&gt;
&lt;target dev='vdb' bus='virtio'/&gt;
&lt;/disk&gt;
...
&lt;/devices&gt;
&lt;/domain&gt;
&lt;/domainsnapshot&gt;</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>&lt;domain&gt;</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>
&lt;domain&gt;
&lt;name&gt;fedora&lt;/name&gt;
&lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt;
&lt;memory&gt;1048576&lt;/memory&gt;
...
&lt;devices&gt;
&lt;disk type='file' device='disk'&gt;
&lt;driver name='qemu' type='qcow2'/&gt;
<b>&lt;source file='/path/to/new'/&gt;</b>
&lt;target dev='vda' bus='virtio'/&gt;
&lt;/disk&gt;
&lt;disk type='file' device='disk' snapshot='external'&gt;
&lt;driver name='qemu' type='raw'/&gt;
&lt;source file='/path/to/old2'/&gt;
&lt;target dev='vdb' bus='virtio'/&gt;
&lt;/disk&gt;
...
&lt;/devices&gt;
&lt;/domain&gt;</pre>
</body>
</html>

297
docs/formatsnapshot.rst Normal file
View 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>

2
docs/meson.build
View File

@ -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',