9:59 a.m.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatsnapshot.html.in | 352 ------------------------------------
docs/formatsnapshot.rst | 297 ++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 298 insertions(+), 353 deletions(-)
delete mode 100644 docs/formatsnapshot.html.in
create mode 100644 docs/formatsnapshot.rst
diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in
deleted file mode 100644
index e481284aa8..0000000000
--- a/docs/formatsnapshot.html.in
+++ /dev/null
@@ -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>
diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst
new file mode 100644
index 0000000000..0ad397316c
--- /dev/null
+++ b/docs/formatsnapshot.rst
@@ -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>
diff --git a/docs/meson.build b/docs/meson.build
index 3caaa76735..adb7ac091e 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -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',
--
2.35.1