2019-08-22 01:42:41 +00:00
|
|
|
<?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
|
2020-03-19 17:59:20 +00:00
|
|
|
also <a href="kbase/domainstatecapture.html">a comparison</a> between
|
2019-08-22 01:42:41 +00:00
|
|
|
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>
|
2019-12-20 10:37:40 +00:00
|
|
|
<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>
|
2019-08-22 01:42:41 +00:00
|
|
|
<dt><code>type</code></dt>
|
|
|
|
|
<dd>A mandatory attribute to describe the type of the
|
|
|
|
|
disk, except when <code>backup='no'</code> is
|
2020-04-09 14:19:59 +00:00
|
|
|
used. Valid values include <code>file</code>, or
|
|
|
|
|
<code>block</code>.
|
2019-08-22 01:42:41 +00:00
|
|
|
Similar to a disk declaration for a domain, the choice of type
|
|
|
|
|
controls what additional sub-elements are needed to describe
|
2020-04-09 14:19:59 +00:00
|
|
|
the destination.</dd>
|
2019-08-22 01:42:41 +00:00
|
|
|
<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
|
2020-04-09 13:50:40 +00:00
|
|
|
qcow2. See documentation for <code>scratch</code> below for
|
|
|
|
|
additional configuration.</dd>
|
2019-08-22 01:42:41 +00:00
|
|
|
<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
|
2020-04-09 13:50:40 +00:00
|
|
|
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>
|
2019-08-22 01:42:41 +00:00
|
|
|
</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>
|
