On 7/2/20 9:40 AM, Peter Krempa wrote:
Switch to the new format for easier extension.
Signed-off-by: Peter Krempa
---
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
Again, I'm not strong in .rst, but the conversion seems sane.
Reviewed-by: Eric Blake
+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.
Not for this patch (which is just a reformat, not editing), but how
close are we to getting to these future additions (the notion of
atomically creating a checkpoint alongside the snapshot creation, as
well as all the work you did to enable checkpoints and snapshots together)?
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org
Switch to the new format for easier extension.
Signed-off-by: Peter Krempa
---
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..00
--- a/docs/formatcheckpoint.html.in
+++ /dev/null
@@ -1,198 +0,0 @@
-
-
-http://www.w3.org/1999/xhtml";>
-
-Checkpoint XML format
-
-
-
-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 checkpo