mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-08-28 11:31:16 +00:00
Now that various new API have been added or are coming soon, it is worth a landing page that gives an overview of capturing various pieces of guest state, and which APIs are best suited to which tasks. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
197 lines
8.6 KiB
XML
197 lines
8.6 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<body>
|
|
<h1>Checkpoint XML format</h1>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<h2><a id="CheckpointAttributes">Checkpoint XML</a></h2>
|
|
|
|
<p>
|
|
One method of capturing domain disk backups is via the use of
|
|
incremental backups. Right now, incremental backups are only
|
|
supported for the QEMU hypervisor when using qcow2 disks at the
|
|
active layer; if other disk formats are in use, capturing disk
|
|
backups requires different libvirt APIs
|
|
(see <a href="kbase/domainstatecapture.html">domain state
|
|
capture</a> for a comparison between APIs).
|
|
</p>
|
|
<p>
|
|
Libvirt is able to facilitate incremental backups by tracking
|
|
disk checkpoints, which are points in time against which it is
|
|
easy to compute which portion of the disk has changed. Given a
|
|
full backup (a backup created from the creation of the disk to a
|
|
given point in time), coupled with the creation of a disk
|
|
checkpoint at that time, and an incremental backup (a backup
|
|
created from just the dirty portion of the disk between the
|
|
first checkpoint and the second backup operation), it is
|
|
possible to do an offline reconstruction of the state of the
|
|
disk at the time of the second backup without having to copy as
|
|
much data as a second full backup would require. Future API
|
|
additions will make it possible to create checkpoints in
|
|
conjunction with a backup
|
|
via <code>virDomainBackupBegin()</code> or with an external
|
|
snapshot via <code>virDomainSnapshotCreateXML2</code>; but for
|
|
now, libvirt exposes enough support to create disk checkpoints
|
|
independently from a backup operation
|
|
via <code>virDomainCheckpointCreateXML()</code> <span class="since">since
|
|
5.6.0</span>.
|
|
</p>
|
|
<p>
|
|
Attributes of libvirt checkpoints are stored as child elements
|
|
of the <code>domaincheckpoint</code> element. At checkpoint
|
|
creation time, normally only
|
|
the <code>name</code>, <code>description</code>,
|
|
and <code>disks</code> elements are settable. The rest of the
|
|
fields are ignored on creation and will be filled in by libvirt
|
|
in for informational purposes
|
|
by <code>virDomainCheckpointGetXMLDesc()</code>. However, when
|
|
redefining a checkpoint, with
|
|
the <code>VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE</code> flag
|
|
of <code>virDomainCheckpointCreateXML()</code>, all of the XML
|
|
fields described here are relevant on input, even the fields
|
|
that are normally described as readonly for output.
|
|
</p>
|
|
<p>
|
|
The top-level <code>domaincheckpoint</code> element may contain
|
|
the following elements:
|
|
</p>
|
|
<dl>
|
|
<dt><code>name</code></dt>
|
|
<dd>The optional name for this checkpoint. If the name is
|
|
omitted, libvirt will create a name based on the time of the
|
|
creation.
|
|
</dd>
|
|
<dt><code>description</code></dt>
|
|
<dd>An optional human-readable description of the checkpoint.
|
|
If the description is omitted when initially creating the
|
|
checkpoint, then this field will be empty.
|
|
</dd>
|
|
<dt><code>disks</code></dt>
|
|
<dd>On input, this is an optional listing of specific
|
|
instructions for disk checkpoints; it is needed when making a
|
|
checkpoint on only a subset of the disks associated with a
|
|
domain. In particular, since QEMU checkpoints require qcow2
|
|
disks, this element may be needed on input for excluding guest
|
|
disks that are not in qcow2 format. If the entire element was
|
|
omitted on input, then all disks participate in the
|
|
checkpoint, otherwise, only the disks explicitly listed which
|
|
do not also use <code>checkpoint='no'</code> will
|
|
participate. On output, this is the checkpoint state of each
|
|
of the domain's disks.
|
|
<dl>
|
|
<dt><code>disk</code></dt>
|
|
<dd>This sub-element describes the checkpoint properties of
|
|
a specific disk with the following attributes:
|
|
<dl>
|
|
<dt><code>name</code></dt>
|
|
<dd>A mandatory attribute which must match either
|
|
the <code><target dev='name'/></code> or an
|
|
unambiguous <code><source file='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>checkpoint</code></dt>
|
|
<dd>An optional attribute; possible values
|
|
are <code>no</code> when the disk does not participate
|
|
in this checkpoint; or <code>bitmap</code> if the disk
|
|
will track all changes since the creation of this
|
|
checkpoint via a bitmap.</dd>
|
|
<dt><code>bitmap</code></dt>
|
|
<dd>The attribute <code>bitmap</code> is only valid
|
|
if <code>checkpoint='bitmap'</code>; it describes the
|
|
name of the tracking bitmap (defaulting to the
|
|
checkpoint name).</dd>
|
|
<dt><code>size</code></dt>
|
|
<dd>The attribute <code>size</code> is ignored on input;
|
|
on output, it is only present if
|
|
the <code>VIR_DOMAIN_CHECKPOINT_XML_SIZE</code> flag
|
|
was used to perform a dynamic query of the estimated
|
|
size in bytes of the changes made since the checkpoint
|
|
was created.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>creationTime</code></dt>
|
|
<dd>A readonly representation of the time this checkpoint was
|
|
created. The time is specified in seconds since the Epoch,
|
|
UTC (i.e. Unix time).
|
|
</dd>
|
|
<dt><code>parent</code></dt>
|
|
<dd>Readonly, present if this checkpoint has a parent. The
|
|
parent name is given by the sub-element <code>name</code>. The
|
|
parent relationship allows tracking a list of related checkpoints.
|
|
</dd>
|
|
<dt><code>domain</code></dt>
|
|
<dd>A readonly representation of the
|
|
inactive <a href="formatdomain.html">domain configuration</a>
|
|
at the time the checkpoint was created. This element may be
|
|
omitted for output brevity by supplying
|
|
the <code>VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN</code> flag, but
|
|
the resulting XML is no longer viable for use with
|
|
the <code>VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE</code> flag
|
|
of <code>virDomainCheckpointCreateXML()</code>. The domain
|
|
will have security-sensitive information omitted unless the
|
|
flag <code>VIR_DOMAIN_CHECKPOINT_XML_SECURE</code> is provided
|
|
on a read-write connection.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2><a id="example">Examples</a></h2>
|
|
|
|
<p>Using this XML to create a checkpoint of just vda on a qemu
|
|
domain with two disks and a prior checkpoint:</p>
|
|
<pre>
|
|
<domaincheckpoint>
|
|
<description>Completion of updates after OS install</description>
|
|
<disks>
|
|
<disk name='vda' checkpoint='bitmap'/>
|
|
<disk name='vdb' checkpoint='no'/>
|
|
</disks>
|
|
</domaincheckpoint></pre>
|
|
|
|
<p>will result in XML similar to this from
|
|
<code>virDomainCheckpointGetXMLDesc()</code>:</p>
|
|
<pre>
|
|
<domaincheckpoint>
|
|
<name>1525889631</name>
|
|
<description>Completion of updates after OS install</description>
|
|
<parent>
|
|
<name>1525111885</name>
|
|
</parent>
|
|
<creationTime>1525889631</creationTime>
|
|
<disks>
|
|
<disk name='vda' checkpoint='bitmap' bitmap='1525889631'/>
|
|
<disk name='vdb' checkpoint='no'/>
|
|
</disks>
|
|
<domain type='qemu'>
|
|
<name>fedora</name>
|
|
<uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
|
|
<memory>1048576</memory>
|
|
...
|
|
<devices>
|
|
<disk type='file' device='disk'>
|
|
<driver name='qemu' type='qcow2'/>
|
|
<source file='/path/to/file1'/>
|
|
<target dev='vda' bus='virtio'/>
|
|
</disk>
|
|
<disk type='file' device='disk' snapshot='external'>
|
|
<driver name='qemu' type='raw'/>
|
|
<source file='/path/to/file2'/>
|
|
<target dev='vdb' bus='virtio'/>
|
|
</disk>
|
|
...
|
|
</devices>
|
|
</domain>
|
|
</domaincheckpoint></pre>
|
|
|
|
<p>With that checkpoint created, the qcow2 image is now tracking
|
|
all changes that occur in the image since the checkpoint via
|
|
the persistent bitmap named <code>1525889631</code>.
|
|
</p>
|
|
</body>
|
|
</html>
|