Switch to the new format for easier extension. Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/formatcheckpoint.html.in | 198 ---------------------------------- docs/formatcheckpoint.rst | 162 ++++++++++++++++++++++++++++ 2 files changed, 162 insertions(+), 198 deletions(-) delete mode 100644 docs/formatcheckpoint.html.in create mode 100644 docs/formatcheckpoint.rst diff --git a/docs/formatcheckpoint.html.in b/docs/formatcheckpoint.html.in deleted file mode 100644 index ee56194523..0000000000 --- a/docs/formatcheckpoint.html.in +++ /dev/null @@ -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> diff --git a/docs/formatcheckpoint.rst b/docs/formatcheckpoint.rst new file mode 100644 index 0000000000..e45745390a --- /dev/null +++ b/docs/formatcheckpoint.rst @@ -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``. -- 2.26.2
