mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 13:45:38 +00:00
docs: checkpoint: 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:
parent
7b2163c8bf
commit
459a60823e
@ -1,198 +0,0 @@
|
||||
<?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. Most disk
|
||||
checkpoints are created in conjunction with a backup
|
||||
via <code>virDomainBackupBegin()</code>, although a future API
|
||||
addition of <code>virDomainSnapshotCreateXML2()</code> will also
|
||||
make this possible when creating external snapshots; however,
|
||||
libvirt also exposes enough support to create disk checkpoints
|
||||
independently from a backup operation
|
||||
via <code>virDomainCheckpointCreateXML()</code> <span class="since">since
|
||||
5.6.0</span>. Likewise, the creation of checkpoints when
|
||||
external snapshots exist is currently forbidden, although future
|
||||
work will make it possible to integrate these two concepts.
|
||||
</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>
|
162
docs/formatcheckpoint.rst
Normal file
162
docs/formatcheckpoint.rst
Normal file
@ -0,0 +1,162 @@
|
||||
Checkpoint XML format
|
||||
=====================
|
||||
|
||||
.. contents::
|
||||
|
||||
Checkpoint XML
|
||||
--------------
|
||||
|
||||
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 `domain
|
||||
state capture <kbase/domainstatecapture.html>`__ for a comparison between APIs).
|
||||
|
||||
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. Most disk checkpoints are created in
|
||||
conjunction with a backup via ``virDomainBackupBegin()``, although a future API
|
||||
addition of ``virDomainSnapshotCreateXML2()`` will also make this possible when
|
||||
creating external snapshots; however, libvirt also exposes enough support to
|
||||
create disk checkpoints independently from a backup operation via
|
||||
``virDomainCheckpointCreateXML()`` since 5.6.0. Likewise, the creation of
|
||||
checkpoints when external snapshots exist is currently forbidden, although
|
||||
future work will make it possible to integrate these two concepts.
|
||||
|
||||
Attributes of libvirt checkpoints are stored as child elements of the
|
||||
``domaincheckpoint`` element. At checkpoint creation time, normally only the
|
||||
``name``, ``description``, and ``disks`` elements are settable. The rest of the
|
||||
fields are ignored on creation and will be filled in by libvirt in for
|
||||
informational purposes by ``virDomainCheckpointGetXMLDesc()``. However, when
|
||||
redefining a checkpoint, with the ``VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE`` flag
|
||||
of ``virDomainCheckpointCreateXML()``, all of the XML fields described here are
|
||||
relevant on input, even the fields that are normally described as readonly for
|
||||
output.
|
||||
|
||||
The top-level ``domaincheckpoint`` element may contain the following elements:
|
||||
|
||||
``name``
|
||||
The optional name for this checkpoint. If the name is omitted, libvirt will
|
||||
create a name based on the time of the creation.
|
||||
|
||||
``description``
|
||||
An optional human-readable description of the checkpoint. If the description
|
||||
is omitted when initially creating the checkpoint, then this field will be
|
||||
empty.
|
||||
|
||||
``disks``
|
||||
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 ``checkpoint='no'`` will participate.
|
||||
On output, this is the checkpoint state of each of the domain's disks.
|
||||
|
||||
``disk``
|
||||
This sub-element describes the checkpoint properties of a specific disk
|
||||
with the following attributes:
|
||||
|
||||
``name``
|
||||
A mandatory attribute which must match either the
|
||||
``<target dev='name'/>`` or an unambiguous ``<source file='name'/>`` of
|
||||
one of the `disk devices <formatdomain.html#elementsDisks>`__ specified
|
||||
for the domain at the time of the checkpoint.
|
||||
|
||||
``checkpoint``
|
||||
An optional attribute; possible values are ``no`` when the disk does
|
||||
not participate in this checkpoint; or ``bitmap`` if the disk will
|
||||
track all changes since the creation of this checkpoint via a bitmap.
|
||||
|
||||
``bitmap``
|
||||
The attribute ``bitmap`` is only valid if ``checkpoint='bitmap'``; it
|
||||
describes the name of the tracking bitmap (defaulting to the checkpoint
|
||||
name).
|
||||
|
||||
``size``
|
||||
The attribute ``size`` is ignored on input; on output, it is only
|
||||
present if the ``VIR_DOMAIN_CHECKPOINT_XML_SIZE`` flag was used to
|
||||
perform a dynamic query of the estimated size in bytes of the changes
|
||||
made since the checkpoint was created.
|
||||
|
||||
``creationTime``
|
||||
A readonly representation of the time this checkpoint was created. The time
|
||||
is specified in seconds since the Epoch, UTC (i.e. Unix time).
|
||||
|
||||
``parent``
|
||||
Readonly, present if this checkpoint has a parent. The parent name is given
|
||||
by the sub-element ``name``. The parent relationship allows tracking a list
|
||||
of related checkpoints.
|
||||
|
||||
``domain``
|
||||
A readonly representation of the inactive `domain
|
||||
configuration <formatdomain.html>`__ at the time the checkpoint was created.
|
||||
This element may be omitted for output brevity by supplying the
|
||||
``VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN`` flag, but the resulting XML is no
|
||||
longer viable for use with the ``VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE`` flag
|
||||
of ``virDomainCheckpointCreateXML()``. The domain will have
|
||||
security-sensitive information omitted unless the flag
|
||||
``VIR_DOMAIN_CHECKPOINT_XML_SECURE`` is provided on a read-write connection.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
Using this XML to create a checkpoint of just vda on a qemu domain with two
|
||||
disks and a prior checkpoint:
|
||||
|
||||
::
|
||||
|
||||
<domaincheckpoint>
|
||||
<description>Completion of updates after OS install</description>
|
||||
<disks>
|
||||
<disk name='vda' checkpoint='bitmap'/>
|
||||
<disk name='vdb' checkpoint='no'/>
|
||||
</disks>
|
||||
</domaincheckpoint>
|
||||
|
||||
will result in XML similar to this from ``virDomainCheckpointGetXMLDesc()``:
|
||||
|
||||
::
|
||||
|
||||
<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>
|
||||
|
||||
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
|
||||
``1525889631``.
|
Loading…
Reference in New Issue
Block a user