9:39 a.m.
Switch to the new format for easier extension.
Signed-off-by: Peter Krempa <pkrempa(a)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