mirror of https://gitee.com/openkylin/libvirt.git
docs: backup: Convert XML documentation to RST
Switch to the new format for easier extension. Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
Peter Krempa
parent
981222b682
commit
3927880e9a
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
Loading…
Reference in New Issue