- 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 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 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
- 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.
-
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.
-
-
-
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 `__ 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
+ ```` or an unambiguous ```` of
+ one of the `disk devices `__ 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 `__ 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:
+
+::
+
+
+ Completion of updates after OS install
+
+
+
+
+
+
+will result in XML similar to this from ``virDomainCheckpointGetXMLDesc()``:
+
+::
+
+
+ 1525889631
+ Completion of updates after OS install
+
+ 1525111885
+
+ 1525889631
+
+
+
+
+
+ fedora
+ 93a5c045-6457-2c09-e56c-927cdf34e178
+ 1048576
+ ...
+
+
+
+
+
+
+
+
+
+
+
+ ...
+
+
+
+
+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``.