[PATCH 13/24] docs: backup: Convert XML documentation to RST

Peter Krempa pkrempa at redhat.com
Thu Jul 2 14:39:59 UTC 2020


Switch to the new format for easier extension.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/formatbackup.html.in | 191 --------------------------------------
 docs/formatbackup.rst     | 149 +++++++++++++++++++++++++++++
 2 files changed, 149 insertions(+), 191 deletions(-)
 delete mode 100644 docs/formatbackup.html.in
 create mode 100644 docs/formatbackup.rst

diff --git a/docs/formatbackup.html.in b/docs/formatbackup.html.in
deleted file mode 100644
index 9e69d8f7d3..0000000000
--- a/docs/formatbackup.html.in
+++ /dev/null
@@ -1,191 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Backup XML format</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="BackupAttributes">Backup XML</a></h2>
-
-    <p>
-      Creating a backup, whether full or incremental, is done
-      via <code>virDomainBackupBegin()</code>, which takes an XML
-      description of the actions to perform, as well as an optional
-      second XML document <a href="formatcheckpoint.html">describing a
-      checkpoint</a> to create at the same point in time. See
-      also <a href="kbase/domainstatecapture.html">a comparison</a> between
-      the various state capture APIs.
-    </p>
-    <p>
-      There are two general modes for backups: a push mode (where the
-      hypervisor writes out the data to the destination file, which
-      may be local or remote), and a pull mode (where the hypervisor
-      creates an NBD server that a third-party client can then read as
-      needed, and which requires the use of temporary storage,
-      typically local, until the backup is complete).
-    </p>
-    <p>
-      The instructions for beginning a backup job are provided as
-      attributes and elements of the
-      top-level <code>domainbackup</code> element. This element
-      includes an optional attribute <code>mode</code> which can be
-      either "push" or "pull" (default
-      push). <code>virDomainBackupGetXMLDesc()</code> can be used to
-      see the actual values selected for elements omitted during
-      creation (for example, learning which port the NBD server is
-      using in the pull model or what file names libvirt generated
-      when none were supplied). The following child elements and attributes
-      are supported:
-    </p>
-    <dl>
-      <dt><code>incremental</code></dt>
-      <dd>An optional element giving the name of an existing
-        checkpoint of the domain, which will be used to make this
-        backup an incremental one. In the push model, only changes
-        since the named checkpoint are written to the destination. In
-        the pull model, the NBD server uses the
-        NBD_OPT_SET_META_CONTEXT extension to advertise to the client
-        which portions of the export contain changes since the named
-        checkpoint. If omitted, a full backup is performed.
-      </dd>
-      <dt><code>server</code></dt>
-      <dd>Present only for a pull mode backup. Contains the same
-        attributes as
-        the <a href="formatdomain.html#elementsDisks"><code>protocol</code>
-        element of a disk</a> attached via NBD in the domain (such as
-        transport, socket, name, port, or tls), necessary to set up an
-        NBD server that exposes the content of each disk at the time
-        the backup is started.
-      </dd>
-      <dt><code>disks</code></dt>
-      <dd>An optional listing of instructions for disks participating
-        in the backup (if omitted, all disks participate and libvirt
-        attempts to generate filenames by appending the current
-        timestamp as a suffix). If the entire element was omitted on
-        input, then all disks participate in the backup, otherwise,
-        only the disks explicitly listed which do not also
-        use <code>backup='no'</code> will participate. On output, this
-        is the state of each of the domain's disk in relation to the
-        backup operation.
-        <dl>
-          <dt><code>disk</code></dt>
-          <dd>This sub-element describes the backup properties of a
-            specific disk, with the following attributes and child
-            elements:
-            <dl>
-              <dt><code>name</code></dt>
-              <dd>A mandatory attribute which must match
-                the <code><target dev='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>backup</code></dt>
-              <dd>Setting this attribute to <code>yes</code>(default) specifies
-                that the disk should take part in the backup and using
-                <code>no</code> excludes the disk from the backup.</dd>
-              <dt><code>exportname</code></dt>
-              <dd>Allows modification of the NBD export name for the given disk.
-                By default equal to disk target.
-                Valid only for pull mode backups.</dd>
-              <dt><code>exportbitmap</code></dt>
-              <dd>Allows modification of the name of the bitmap describing dirty
-                blocks for an incremental backup exported via NBD export name
-                for the given disk.
-                Valid only for pull mode backups.</dd>
-              <dt><code>type</code></dt>
-              <dd>A mandatory attribute to describe the type of the
-                disk, except when <code>backup='no'</code> is
-                used. Valid values include <code>file</code>, or
-                <code>block</code>.
-                Similar to a disk declaration for a domain, the choice of type
-                controls what additional sub-elements are needed to describe
-                the destination.</dd>
-              <dt><code>target</code></dt>
-              <dd>Valid only for push mode backups, this is the
-                primary sub-element that describes the file name of
-                the backup destination, similar to
-                the <code>source</code> sub-element of a domain
-                disk. An optional sub-element <code>driver</code> can
-                also be used, with an attribute <code>type</code> to
-                specify a destination format different from
-                qcow2. See documentation for <code>scratch</code> below for
-                additional configuration.</dd>
-              <dt><code>scratch</code></dt>
-              <dd>Valid only for pull mode backups, this is the
-                primary sub-element that describes the file name of
-                the local scratch file to be used in facilitating the
-                backup, and is similar to the <code>source</code>
-                sub-element of a domain disk. Currently only <code>file</code>
-                and <code>block</code> scratch storage is supported. The
-                <code>file</code> scratch file is created and deleted by
-                libvirt in the given location. A <code>block</code> scratch
-                device must exist prior to starting the backup and is formatted.
-                The block device must have enough space for the corresponding
-                disk data including format overhead.
-
-                If <code>VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL</code> flag is
-                used the file for a scratch of <code>file</code> type must
-                exist with the correct format and size to hold the copy and is
-                used without modification. The file is not deleted after the
-                backup but the contents of the file don't make sense outside
-                of the backup. The same applies for the block device which
-                must be formatted appropriately.
-
-                Similarly to the domain
-                <a href="formatdomain.html#elementsDisks"><code>disk</code></a>
-                definition <code>scratch</code> and <code>target</code> can
-                contain <code>seclabel</code> and/or <code>encryption</code>
-                subelements to configure the corresponding properties.
-              </dd>
-            </dl>
-          </dd>
-        </dl>
-      </dd>
-    </dl>
-
-    <h2><a id="example">Examples</a></h2>
-
-    <p>Use <code>virDomainBackupBegin()</code> to perform a full
-      backup using push mode. The example lets libvirt pick the
-      destination and format for 'vda', fully specifies that we want a
-      raw backup of 'vdb', and omits 'vdc' from the operation.
-    </p>
-    <pre>
-<domainbackup>
-  <disks>
-    <disk name='vda' backup='yes'/>
-    <disk name='vdb' type='file'>
-      <target file='/path/to/vdb.backup'/>
-      <driver type='raw'/>
-    </disk>
-    <disk name='vdc' backup='no'/>
-  </disks>
-</domainbackup>
-    </pre>
-
-    <p>If the previous full backup also passed a parameter describing
-      <a href="formatcheckpoint.html">checkpoint XML</a> that resulted
-      in a checkpoint named <code>1525889631</code>, we can make
-      another call to <code>virDomainBackupBegin()</code> to perform
-      an incremental backup of just the data changed since that
-      checkpoint, this time using the following XML to start a pull
-      model export of the 'vda' and 'vdb' disks, where a third-party
-      NBD client connecting to '/path/to/server' completes the backup
-      (omitting 'vdc' from the explicit list has the same effect as
-      the backup='no' from the previous example):
-    </p>
-    <pre>
-<domainbackup mode="pull">
-  <incremental>1525889631</incremental>
-  <server transport="unix" socket="/path/to/server"/>
-  <disks>
-    <disk name='vda' backup='yes' type='file'>
-      <scratch file='/path/to/file1.scratch'/>
-    </disk>
-  </disks>
-</domainbackup>
-    </pre>
-  </body>
-</html>
diff --git a/docs/formatbackup.rst b/docs/formatbackup.rst
new file mode 100644
index 0000000000..66583f562b
--- /dev/null
+++ b/docs/formatbackup.rst
@@ -0,0 +1,149 @@
+Backup XML format
+=================
+
+.. contents::
+
+Backup XML
+----------
+
+Creating a backup, whether full or incremental, is done via
+``virDomainBackupBegin()``, which takes an XML description of the actions to
+perform, as well as an optional second XML document `describing a
+checkpoint <formatcheckpoint.html>`__ to create at the same point in time. See
+also `a comparison <kbase/domainstatecapture.html>`__ between the various state
+capture APIs.
+
+There are two general modes for backups: a push mode (where the hypervisor
+writes out the data to the destination file, which may be local or remote), and
+a pull mode (where the hypervisor creates an NBD server that a third-party
+client can then read as needed, and which requires the use of temporary storage,
+typically local, until the backup is complete).
+
+The instructions for beginning a backup job are provided as attributes and
+elements of the top-level ``domainbackup`` element. This element includes an
+optional attribute ``mode`` which can be either "push" or "pull" (default push).
+``virDomainBackupGetXMLDesc()`` can be used to see the actual values selected
+for elements omitted during creation (for example, learning which port the NBD
+server is using in the pull model or what file names libvirt generated when none
+were supplied). The following child elements and attributes are supported:
+
+``incremental``
+   An optional element giving the name of an existing checkpoint of the domain,
+   which will be used to make this backup an incremental one. In the push model,
+   only changes since the named checkpoint are written to the destination. In
+   the pull model, the NBD server uses the NBD_OPT_SET_META_CONTEXT extension to
+   advertise to the client which portions of the export contain changes since
+   the named checkpoint. If omitted, a full backup is performed.
+
+``server``
+   Present only for a pull mode backup. Contains the same attributes as the
+   ```protocol`` element of a disk <formatdomain.html#elementsDisks>`__ attached
+   via NBD in the domain (such as transport, socket, name, port, or tls),
+   necessary to set up an NBD server that exposes the content of each disk at
+   the time the backup is started.
+
+``disks``
+   An optional listing of instructions for disks participating in the backup (if
+   omitted, all disks participate and libvirt attempts to generate filenames by
+   appending the current timestamp as a suffix). If the entire element was
+   omitted on input, then all disks participate in the backup, otherwise, only
+   the disks explicitly listed which do not also use ``backup='no'`` will
+   participate. On output, this is the state of each of the domain's disk in
+   relation to the backup operation.
+
+   ``disk``
+      This sub-element describes the backup properties of a specific disk, with
+      the following attributes and child elements:
+
+      ``name``
+         A mandatory attribute which must match the ``<target dev='name'/>`` of
+         one of the `disk devices <formatdomain.html#elementsDisks>`__ specified
+         for the domain at the time of the checkpoint.
+
+      ``backup``
+         Setting this attribute to ``yes``\ (default) specifies that the disk
+         should take part in the backup and using ``no`` excludes the disk from
+         the backup.
+
+      ``exportname``
+         Allows modification of the NBD export name for the given disk. By
+         default equal to disk target. Valid only for pull mode backups.
+
+      ``exportbitmap``
+         Allows modification of the name of the bitmap describing dirty blocks
+         for an incremental backup exported via NBD export name for the given
+         disk. Valid only for pull mode backups.
+
+      ``type``
+         A mandatory attribute to describe the type of the disk, except when
+         ``backup='no'`` is used. Valid values include ``file``, or ``block``.
+         Similar to a disk declaration for a domain, the choice of type controls
+         what additional sub-elements are needed to describe the destination.
+
+      ``target``
+         Valid only for push mode backups, this is the primary sub-element that
+         describes the file name of the backup destination, similar to the
+         ``source`` sub-element of a domain disk. An optional sub-element
+         ``driver`` can also be used, with an attribute ``type`` to specify a
+         destination format different from qcow2. See documentation for
+         ``scratch`` below for additional configuration.
+
+      ``scratch``
+         Valid only for pull mode backups, this is the primary sub-element that
+         describes the file name of the local scratch file to be used in
+         facilitating the backup, and is similar to the ``source`` sub-element
+         of a domain disk. Currently only ``file`` and ``block`` scratch storage
+         is supported. The ``file`` scratch file is created and deleted by
+         libvirt in the given location. A ``block`` scratch device must exist
+         prior to starting the backup and is formatted. The block device must
+         have enough space for the corresponding disk data including format
+         overhead. If ``VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL`` flag is used
+         the file for a scratch of ``file`` type must exist with the correct
+         format and size to hold the copy and is used without modification. The
+         file is not deleted after the backup but the contents of the file don't
+         make sense outside of the backup. The same applies for the block device
+         which must be formatted appropriately. Similarly to the domain
+         ```disk`` <formatdomain.html#elementsDisks>`__ definition ``scratch``
+         and ``target`` can contain ``seclabel`` and/or ``encryption``
+         subelements to configure the corresponding properties.
+
+Examples
+--------
+
+Use ``virDomainBackupBegin()`` to perform a full backup using push mode. The
+example lets libvirt pick the destination and format for 'vda', fully specifies
+that we want a raw backup of 'vdb', and omits 'vdc' from the operation.
+
+::
+
+   <domainbackup>
+     <disks>
+       <disk name='vda' backup='yes'/>
+       <disk name='vdb' type='file'>
+         <target file='/path/to/vdb.backup'/>
+         <driver type='raw'/>
+       </disk>
+       <disk name='vdc' backup='no'/>
+     </disks>
+   </domainbackup>
+
+If the previous full backup also passed a parameter describing `checkpoint
+XML <formatcheckpoint.html>`__ that resulted in a checkpoint named
+``1525889631``, we can make another call to ``virDomainBackupBegin()`` to
+perform an incremental backup of just the data changed since that checkpoint,
+this time using the following XML to start a pull model export of the 'vda' and
+'vdb' disks, where a third-party NBD client connecting to '/path/to/server'
+completes the backup (omitting 'vdc' from the explicit list has the same effect
+as the backup='no' from the previous example):
+
+::
+
+   <domainbackup mode="pull">
+     <incremental>1525889631</incremental>
+     <server transport="unix" socket="/path/to/server"/>
+     <disks>
+       <disk name='vda' backup='yes' type='file'>
+         <scratch file='/path/to/file1.scratch'/>
+       </disk>
+     </disks>
+   </domainbackup>
-- 
2.26.2




More information about the libvir-list mailing list