[PATCH 16/24] docs: checkpoint: Convert XML documentation to RST
Peter Krempa
pkrempa at redhat.com
Thu Jul 2 14:40:02 UTC 2020
Switch to the new format for easier extension.
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatcheckpoint.html.in | 198 ----------------------------------
docs/formatcheckpoint.rst | 162 ++++++++++++++++++++++++++++
2 files changed, 162 insertions(+), 198 deletions(-)
delete mode 100644 docs/formatcheckpoint.html.in
create mode 100644 docs/formatcheckpoint.rst
diff --git a/docs/formatcheckpoint.html.in b/docs/formatcheckpoint.html.in
deleted file mode 100644
index ee56194523..0000000000
--- a/docs/formatcheckpoint.html.in
+++ /dev/null
@@ -1,198 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Checkpoint XML format</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="CheckpointAttributes">Checkpoint XML</a></h2>
-
- <p>
- One method of capturing domain disk backups is via the use of
- incremental backups. Right now, incremental backups are only
- supported for the QEMU hypervisor when using qcow2 disks at the
- active layer; if other disk formats are in use, capturing disk
- backups requires different libvirt APIs
- (see <a href="kbase/domainstatecapture.html">domain state
- capture</a> for a comparison between APIs).
- </p>
- <p>
- Libvirt is able to facilitate incremental backups by tracking
- disk checkpoints, which are points in time against which it is
- easy to compute which portion of the disk has changed. Given a
- full backup (a backup created from the creation of the disk to a
- given point in time), coupled with the creation of a disk
- checkpoint at that time, and an incremental backup (a backup
- created from just the dirty portion of the disk between the
- first checkpoint and the second backup operation), it is
- possible to do an offline reconstruction of the state of the
- disk at the time of the second backup without having to copy as
- much data as a second full backup would require. Most disk
- checkpoints are created in conjunction with a backup
- via <code>virDomainBackupBegin()</code>, although a future API
- addition of <code>virDomainSnapshotCreateXML2()</code> will also
- make this possible when creating external snapshots; however,
- libvirt also exposes enough support to create disk checkpoints
- independently from a backup operation
- via <code>virDomainCheckpointCreateXML()</code> <span class="since">since
- 5.6.0</span>. Likewise, the creation of checkpoints when
- external snapshots exist is currently forbidden, although future
- work will make it possible to integrate these two concepts.
- </p>
- <p>
- Attributes of libvirt checkpoints are stored as child elements
- of the <code>domaincheckpoint</code> element. At checkpoint
- 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>virDomainCheckpointGetXMLDesc()</code>. However, when
- redefining a checkpoint, with
- the <code>VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE</code> flag
- of <code>virDomainCheckpointCreateXML()</code>, all of the XML
- fields described here are relevant on input, even the fields
- that are normally described as readonly for output.
- </p>
- <p>
- The top-level <code>domaincheckpoint</code> element may contain
- the following elements:
- </p>
- <dl>
- <dt><code>name</code></dt>
- <dd>The optional name for this checkpoint. 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 checkpoint.
- If the description is omitted when initially creating the
- checkpoint, then this field will be empty.
- </dd>
- <dt><code>disks</code></dt>
- <dd>On input, this is an optional listing of specific
- instructions for disk checkpoints; it is needed when making a
- checkpoint on only a subset of the disks associated with a
- domain. In particular, since QEMU checkpoints require qcow2
- disks, this element may be needed on input for excluding guest
- disks that are not in qcow2 format. If the entire element was
- omitted on input, then all disks participate in the
- checkpoint, otherwise, only the disks explicitly listed which
- do not also use <code>checkpoint='no'</code> will
- participate. On output, this is the checkpoint state of each
- of the domain's disks.
- <dl>
- <dt><code>disk</code></dt>
- <dd>This sub-element describes the checkpoint properties of
- a specific disk with the following attributes:
- <dl>
- <dt><code>name</code></dt>
- <dd>A mandatory attribute which must match either
- the <code><target dev='name'/></code> 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 checkpoint.</dd>
- <dt><code>checkpoint</code></dt>
- <dd>An optional attribute; possible values
- are <code>no</code> when the disk does not participate
- in this checkpoint; or <code>bitmap</code> if the disk
- will track all changes since the creation of this
- checkpoint via a bitmap.</dd>
- <dt><code>bitmap</code></dt>
- <dd>The attribute <code>bitmap</code> is only valid
- if <code>checkpoint='bitmap'</code>; it describes the
- name of the tracking bitmap (defaulting to the
- checkpoint name).</dd>
- <dt><code>size</code></dt>
- <dd>The attribute <code>size</code> is ignored on input;
- on output, it is only present if
- the <code>VIR_DOMAIN_CHECKPOINT_XML_SIZE</code> flag
- was used to perform a dynamic query of the estimated
- size in bytes of the changes made since the checkpoint
- was created.</dd>
- </dl>
- </dd>
- </dl>
- </dd>
- <dt><code>creationTime</code></dt>
- <dd>A readonly representation of the time this checkpoint was
- created. The time is specified in seconds since the Epoch,
- UTC (i.e. Unix time).
- </dd>
- <dt><code>parent</code></dt>
- <dd>Readonly, present if this checkpoint has a parent. The
- parent name is given by the sub-element <code>name</code>. The
- parent relationship allows tracking a list of related checkpoints.
- </dd>
- <dt><code>domain</code></dt>
- <dd>A readonly representation of the
- inactive <a href="formatdomain.html">domain configuration</a>
- at the time the checkpoint was created. This element may be
- omitted for output brevity by supplying
- the <code>VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN</code> flag, but
- the resulting XML is no longer viable for use with
- the <code>VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE</code> flag
- of <code>virDomainCheckpointCreateXML()</code>. The domain
- will have security-sensitive information omitted unless the
- flag <code>VIR_DOMAIN_CHECKPOINT_XML_SECURE</code> is provided
- on a read-write connection.
- </dd>
- </dl>
-
- <h2><a id="example">Examples</a></h2>
-
- <p>Using this XML to create a checkpoint of just vda on a qemu
- domain with two disks and a prior checkpoint:</p>
- <pre>
-<domaincheckpoint>
- <description>Completion of updates after OS install</description>
- <disks>
- <disk name='vda' checkpoint='bitmap'/>
- <disk name='vdb' checkpoint='no'/>
- </disks>
-</domaincheckpoint></pre>
-
- <p>will result in XML similar to this from
- <code>virDomainCheckpointGetXMLDesc()</code>:</p>
- <pre>
-<domaincheckpoint>
- <name>1525889631</name>
- <description>Completion of updates after OS install</description>
- <parent>
- <name>1525111885</name>
- </parent>
- <creationTime>1525889631</creationTime>
- <disks>
- <disk name='vda' checkpoint='bitmap' bitmap='1525889631'/>
- <disk name='vdb' checkpoint='no'/>
- </disks>
- <domain type='qemu'>
- <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/file1'/>
- <target dev='vda' bus='virtio'/>
- </disk>
- <disk type='file' device='disk' snapshot='external'>
- <driver name='qemu' type='raw'/>
- <source file='/path/to/file2'/>
- <target dev='vdb' bus='virtio'/>
- </disk>
- ...
- </devices>
- </domain>
-</domaincheckpoint></pre>
-
- <p>With that checkpoint created, the qcow2 image is now tracking
- all changes that occur in the image since the checkpoint via
- the persistent bitmap named <code>1525889631</code>.
- </p>
- </body>
-</html>
diff --git a/docs/formatcheckpoint.rst b/docs/formatcheckpoint.rst
new file mode 100644
index 0000000000..e45745390a
--- /dev/null
+++ b/docs/formatcheckpoint.rst
@@ -0,0 +1,162 @@
+Checkpoint XML format
+=====================
+
+.. contents::
+
+Checkpoint XML
+--------------
+
+One method of capturing domain disk backups is via the use of incremental
+backups. Right now, incremental backups are only supported for the QEMU
+hypervisor when using qcow2 disks at the active layer; if other disk formats are
+in use, capturing disk backups requires different libvirt APIs (see `domain
+state capture <kbase/domainstatecapture.html>`__ for a comparison between APIs).
+
+Libvirt is able to facilitate incremental backups by tracking disk checkpoints,
+which are points in time against which it is easy to compute which portion of
+the disk has changed. Given a full backup (a backup created from the creation of
+the disk to a given point in time), coupled with the creation of a disk
+checkpoint at that time, and an incremental backup (a backup created from just
+the dirty portion of the disk between the first checkpoint and the second backup
+operation), it is possible to do an offline reconstruction of the state of the
+disk at the time of the second backup without having to copy as much data as a
+second full backup would require. Most disk checkpoints are created in
+conjunction with a backup via ``virDomainBackupBegin()``, although a future API
+addition of ``virDomainSnapshotCreateXML2()`` will also make this possible when
+creating external snapshots; however, libvirt also exposes enough support to
+create disk checkpoints independently from a backup operation via
+``virDomainCheckpointCreateXML()`` since 5.6.0. Likewise, the creation of
+checkpoints when external snapshots exist is currently forbidden, although
+future work will make it possible to integrate these two concepts.
+
+Attributes of libvirt checkpoints are stored as child elements of the
+``domaincheckpoint`` element. At checkpoint 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 ``virDomainCheckpointGetXMLDesc()``. However, when
+redefining a checkpoint, with the ``VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE`` flag
+of ``virDomainCheckpointCreateXML()``, all of the XML fields described here are
+relevant on input, even the fields that are normally described as readonly for
+output.
+
+The top-level ``domaincheckpoint`` element may contain the following elements:
+
+``name``
+ The optional name for this checkpoint. 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 checkpoint. If the description
+ is omitted when initially creating the checkpoint, then this field will be
+ empty.
+
+``disks``
+ On input, this is an optional listing of specific instructions for disk
+ checkpoints; it is needed when making a checkpoint on only a subset of the
+ disks associated with a domain. In particular, since QEMU checkpoints require
+ qcow2 disks, this element may be needed on input for excluding guest disks
+ that are not in qcow2 format. If the entire element was omitted on input,
+ then all disks participate in the checkpoint, otherwise, only the disks
+ explicitly listed which do not also use ``checkpoint='no'`` will participate.
+ On output, this is the checkpoint state of each of the domain's disks.
+
+ ``disk``
+ This sub-element describes the checkpoint properties of a specific disk
+ with the following attributes:
+
+ ``name``
+ A mandatory attribute which must match either the
+ ``<target dev='name'/>`` or an unambiguous ``<source file='name'/>`` of
+ one of the `disk devices <formatdomain.html#elementsDisks>`__ specified
+ for the domain at the time of the checkpoint.
+
+ ``checkpoint``
+ An optional attribute; possible values are ``no`` when the disk does
+ not participate in this checkpoint; or ``bitmap`` if the disk will
+ track all changes since the creation of this checkpoint via a bitmap.
+
+ ``bitmap``
+ The attribute ``bitmap`` is only valid if ``checkpoint='bitmap'``; it
+ describes the name of the tracking bitmap (defaulting to the checkpoint
+ name).
+
+ ``size``
+ The attribute ``size`` is ignored on input; on output, it is only
+ present if the ``VIR_DOMAIN_CHECKPOINT_XML_SIZE`` flag was used to
+ perform a dynamic query of the estimated size in bytes of the changes
+ made since the checkpoint was created.
+
+``creationTime``
+ A readonly representation of the time this checkpoint was created. The time
+ is specified in seconds since the Epoch, UTC (i.e. Unix time).
+
+``parent``
+ Readonly, present if this checkpoint has a parent. The parent name is given
+ by the sub-element ``name``. The parent relationship allows tracking a list
+ of related checkpoints.
+
+``domain``
+ A readonly representation of the inactive `domain
+ configuration <formatdomain.html>`__ at the time the checkpoint was created.
+ This element may be omitted for output brevity by supplying the
+ ``VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN`` flag, but the resulting XML is no
+ longer viable for use with the ``VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE`` flag
+ of ``virDomainCheckpointCreateXML()``. The domain will have
+ security-sensitive information omitted unless the flag
+ ``VIR_DOMAIN_CHECKPOINT_XML_SECURE`` is provided on a read-write connection.
+
+Examples
+--------
+
+Using this XML to create a checkpoint of just vda on a qemu domain with two
+disks and a prior checkpoint:
+
+::
+
+ <domaincheckpoint>
+ <description>Completion of updates after OS install</description>
+ <disks>
+ <disk name='vda' checkpoint='bitmap'/>
+ <disk name='vdb' checkpoint='no'/>
+ </disks>
+ </domaincheckpoint>
+
+will result in XML similar to this from ``virDomainCheckpointGetXMLDesc()``:
+
+::
+
+ <domaincheckpoint>
+ <name>1525889631</name>
+ <description>Completion of updates after OS install</description>
+ <parent>
+ <name>1525111885</name>
+ </parent>
+ <creationTime>1525889631</creationTime>
+ <disks>
+ <disk name='vda' checkpoint='bitmap' bitmap='1525889631'/>
+ <disk name='vdb' checkpoint='no'/>
+ </disks>
+ <domain type='qemu'>
+ <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/file1'/>
+ <target dev='vda' bus='virtio'/>
+ </disk>
+ <disk type='file' device='disk' snapshot='external'>
+ <driver name='qemu' type='raw'/>
+ <source file='/path/to/file2'/>
+ <target dev='vdb' bus='virtio'/>
+ </disk>
+ ...
+ </devices>
+ </domain>
+ </domaincheckpoint>
+
+With that checkpoint created, the qcow2 image is now tracking all changes that
+occur in the image since the checkpoint via the persistent bitmap named
+``1525889631``.
--
2.26.2
More information about the libvir-list
mailing list