mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-09 15:00:07 +00:00
a7db0b757d
Add the appropriate entries into the schema to allow encryption of the backup or scratch image. Since we use blockdev internals for everything no changes to the code are actually necessary. https://bugzilla.redhat.com/show_bug.cgi?id=1811906 Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
192 lines
9.1 KiB
XML
192 lines
9.1 KiB
XML
<?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>
|