10:56 p.m.
This is a subset of v9 of incremental backup, fixing most of the
review comments that Peter gave on v8.5. The qemu portions in
patch 11 and 12 could probably still use some cleanups to address
feedback in v8 and v8.5; and I also intend to post a followup
series for the backup APIs on Monday to form the full backup-v9
tag.
Here's a comparison of these patches to v8.5:
- rebase on top of master, and on top of my series '[0/8] more
snapshot improvements':
https://www.redhat.com/archives/libvir-list/2019-July/msg00224.html
- add interlock error between snapshots and checkpoints: until we
finish the design of how those two will interact, it's easier to
ensure we don't let the user get into a weird state that we will
then be stuck with supporting down the road
- avoid some technical debt; Peter pointed out several places to
improve, and I've done a lot of those (there's probably still more
that can be done, but at least 1-10 feel more polished)
- Rework the notion of a current checkpoint. We are stuck with a
domain having a single current snapshot, and my implementation for
qemu happens to use a single current checkpoint, but Peter pointed
out that other hypervisors might have multiple current snapshots.
As such, I deleted the API virDomainSnapshotCurrent (which could
only report just one) and instead replaced it with new filter
flags for virDomainListAllSnapshots
- With a current checkpoint being exposed in the XML, there were lots
of simplifications to virsh (no longer possible to change which
checkpoint is current by abuse of redefine)
- With current checkpoint in the public XML, there is no longer a need
for a PARSE_INTERNAL or FORMAT_INTERNAL flag
- Add testsuite coverage of the test_driver checkpoint implementation
(which in turn allowed me to fine-tune several of the other patches
based on what it turned up) (see patch 10)
- Fix several typos/grammars/copy-paste leftovers
- defer virDomainCheckpointIsCurrent to a later patch (see patch 13);
we may decide we don't need the API and that parsing XML frrom
virDomainCheckpointGetXMLDesc is sufficient
001/13:[0068] [FC] 'backup: Document new XML for checkpoints'
002/13:[0186] [FC] 'backup: Introduce virDomainCheckpoint APIs'
003/13:[0021] [FC] 'backup: Document nuances between different state capture
APIs'
004/13:[0099] [FC] 'backup: Parse and output checkpoint XML'
005/13:[0070] [FC] 'backup: Allow for lists of checkpoint objects'
006/13:[----] [--] 'backup: Add new domain:checkpoint access control'
007/13:[0072] [FC] 'backup: Implement checkpoint APIs for remote driver'
008/13:[0527] [FC] 'backup: Implement virsh support for checkpoints'
009/13:[0097] [FC] 'backup: test: Implement metadata tracking for checkpoint
APIs'
010/13:[down] 'backup: Add virsh-checkpoints test'
011/13:[0132] [FC] 'backup: qemu: Implement metadata tracking for checkpoint
APIs'
012/13:[----] [-C] 'backup: Wire up qemu checkpoint commands over QMP'
013/13:[down] 'backup: Add virDomainCheckpointIsCurrent API'
Eric Blake (13):
backup: Document new XML for checkpoints
backup: Introduce virDomainCheckpoint APIs
backup: Document nuances between different state capture APIs
backup: Parse and output checkpoint XML
backup: Allow for lists of checkpoint objects
backup: Add new domain:checkpoint access control
backup: Implement checkpoint APIs for remote driver
backup: Implement virsh support for checkpoints
backup: test: Implement metadata tracking for checkpoint APIs
backup: Add virsh-checkpoints test
backup: qemu: Implement metadata tracking for checkpoint APIs
backup: Wire up qemu checkpoint commands over QMP
backup: Add virDomainCheckpointIsCurrent API
include/libvirt/libvirt-domain-checkpoint.h | 147 ++
include/libvirt/libvirt-domain.h | 6 +
include/libvirt/libvirt.h | 5 +-
src/access/viraccessperm.h | 6 +
src/conf/checkpoint_conf.h | 93 ++
src/conf/domain_conf.h | 2 +
src/conf/virconftypes.h | 9 +
src/conf/virdomaincheckpointobjlist.h | 74 +
src/conf/virdomainmomentobjlist.h | 5 +-
src/conf/virdomainobjlist.h | 7 +-
src/driver-hypervisor.h | 43 +
src/qemu/qemu_block.h | 3 +
src/qemu/qemu_conf.h | 2 +
src/qemu/qemu_domain.h | 15 +
tools/virsh-checkpoint.h | 26 +
tools/virsh-completer.h | 4 +
tools/virsh-util.h | 3 +
tools/virsh.h | 1 +
docs/Makefile.am | 3 +
docs/apibuild.py | 2 +
docs/docs.html.in | 9 +-
docs/domainstatecapture.html.in | 314 +++++
docs/format.html.in | 1 +
docs/formatcheckpoint.html.in | 220 +++
docs/formatsnapshot.html.in | 6 +-
docs/index.html.in | 3 +-
docs/schemas/domaincheckpoint.rng | 95 ++
libvirt.spec.in | 2 +
mingw-libvirt.spec.in | 4 +
po/POTFILES | 3 +
src/Makefile.am | 2 +
src/access/viraccessperm.c | 3 +-
src/conf/Makefile.inc.am | 4 +
src/conf/checkpoint_conf.c | 630 +++++++++
src/conf/domain_conf.c | 6 +
src/conf/virdomaincheckpointobjlist.c | 232 ++++
src/conf/virdomainmomentobjlist.c | 2 +-
src/conf/virdomainobjlist.c | 11 +
src/libvirt-domain-checkpoint.c | 624 +++++++++
src/libvirt-domain.c | 19 +-
src/libvirt_private.syms | 26 +
src/libvirt_public.syms | 17 +
src/qemu/qemu_block.c | 12 +
src/qemu/qemu_conf.c | 5 +
src/qemu/qemu_domain.c | 182 +++
src/qemu/qemu_driver.c | 787 +++++++++++
src/remote/remote_daemon_dispatch.c | 20 +
src/remote/remote_driver.c | 25 +-
src/remote/remote_protocol.x | 139 +-
src/remote_protocol-structs | 77 ++
src/rpc/gendispatch.pl | 32 +-
src/test/test_driver.c | 415 ++++++
tests/Makefile.am | 12 +-
tests/qemudomaincheckpointxml2xmlin/empty.xml | 1 +
.../qemudomaincheckpointxml2xmlin/sample.xml | 7 +
tests/qemudomaincheckpointxml2xmlin/size.xml | 4 +
.../qemudomaincheckpointxml2xmlout/empty.xml | 8 +
.../internal-active-invalid.xml | 53 +
.../internal-inactive-invalid.xml | 53 +
.../redefine.xml | 64 +
.../qemudomaincheckpointxml2xmlout/sample.xml | 13 +
tests/qemudomaincheckpointxml2xmlout/size.xml | 12 +
tests/qemudomaincheckpointxml2xmltest.c | 213 +++
tests/virschematest.c | 2 +
tests/virsh-checkpoint | 181 +++
tests/virsh-snapshot | 12 +-
tools/Makefile.am | 1 +
tools/virsh-checkpoint.c | 1215 +++++++++++++++++
tools/virsh-completer.c | 51 +
tools/virsh-domain-monitor.c | 23 +
tools/virsh-domain.c | 7 +
tools/virsh-util.c | 11 +
tools/virsh.c | 2 +
tools/virsh.pod | 221 ++-
74 files changed, 6508 insertions(+), 41 deletions(-)
create mode 100644 include/libvirt/libvirt-domain-checkpoint.h
create mode 100644 src/conf/checkpoint_conf.h
create mode 100644 src/conf/virdomaincheckpointobjlist.h
create mode 100644 tools/virsh-checkpoint.h
create mode 100644 docs/domainstatecapture.html.in
create mode 100644 docs/formatcheckpoint.html.in
create mode 100644 docs/schemas/domaincheckpoint.rng
create mode 100644 src/conf/checkpoint_conf.c
create mode 100644 src/conf/virdomaincheckpointobjlist.c
create mode 100644 src/libvirt-domain-checkpoint.c
create mode 100644 tests/qemudomaincheckpointxml2xmlin/empty.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlin/sample.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlin/size.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/empty.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/internal-active-invalid.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/internal-inactive-invalid.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/redefine.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/sample.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/size.xml
create mode 100644 tests/qemudomaincheckpointxml2xmltest.c
create mode 100755 tests/virsh-checkpoint
create mode 100644 tools/virsh-checkpoint.c
--
2.20.1
10:56 p.m.
New subject: [libvirt] [PATCH v9 01/13] backup: Document new XML for checkpoints
Prepare for new checkpoint APIs by describing the XML that will
represent a checkpoint. The checkpoint XML is modeled heavily after
virDomainSnapshotPtr. See the docs for more details.
Add testsuite coverage for some minimal uses of the XML (bare minimum,
the sample from html, and a full dumpxml). Although use of the
REDEFINE flag will require the <domain> subelement to be present, it
is easier for most of the tests to provide counterpart output produced
with the NO_DOMAIN flag (particularly since synthesizing a valid
<domain> during testing is not trivial).
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
docs/docs.html.in | 3 +-
docs/format.html.in | 1 +
docs/formatcheckpoint.html.in | 218 ++++++++++++++++++
docs/formatsnapshot.html.in | 4 +-
docs/index.html.in | 3 +-
docs/schemas/domaincheckpoint.rng | 95 ++++++++
libvirt.spec.in | 1 +
mingw-libvirt.spec.in | 2 +
tests/Makefile.am | 2 +
tests/qemudomaincheckpointxml2xmlin/empty.xml | 1 +
.../qemudomaincheckpointxml2xmlin/sample.xml | 7 +
tests/qemudomaincheckpointxml2xmlin/size.xml | 4 +
.../qemudomaincheckpointxml2xmlout/empty.xml | 8 +
.../redefine.xml | 64 +++++
.../qemudomaincheckpointxml2xmlout/sample.xml | 13 ++
tests/qemudomaincheckpointxml2xmlout/size.xml | 12 +
tests/virschematest.c | 2 +
17 files changed, 437 insertions(+), 3 deletions(-)
create mode 100644 docs/formatcheckpoint.html.in
create mode 100644 docs/schemas/domaincheckpoint.rng
create mode 100644 tests/qemudomaincheckpointxml2xmlin/empty.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlin/sample.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlin/size.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/empty.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/redefine.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/sample.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/size.xml
diff --git a/docs/docs.html.in b/docs/docs.html.in
index c8674e1457..55cbab5f15 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -81,7 +81,8 @@
<a href="formatstoragecaps.html">storage pool
capabilities</a>,
<a href="formatnode.html">node devices</a>,
<a href="formatsecret.html">secrets</a>,
- <a href="formatsnapshot.html">snapshots</a></dd>
+ <a href="formatsnapshot.html">snapshots</a>,
+ <a
href="formatcheckpoint.html">checkpoints</a></dd>
<dt><a href="uri.html">URI format</a></dt>
<dd>The URI formats used for connecting to libvirt</dd>
diff --git a/docs/format.html.in b/docs/format.html.in
index 640a9957ee..20f9ef3348 100644
--- a/docs/format.html.in
+++ b/docs/format.html.in
@@ -25,6 +25,7 @@
<li><a href="formatnode.html">Node
devices</a></li>
<li><a href="formatsecret.html">Secrets</a></li>
<li><a
href="formatsnapshot.html">Snapshots</a></li>
+ <li><a
href="formatcheckpoint.html">Checkpoints</a></li>
</ul>
<h2>Command line validation</h2>
diff --git a/docs/formatcheckpoint.html.in b/docs/formatcheckpoint.html.in
new file mode 100644
index 0000000000..ef5f8a826b
--- /dev/null
+++ b/docs/formatcheckpoint.html.in
@@ -0,0 +1,218 @@
+<?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.
+ </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>.
+ </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>
+ A checkpoint is marked current if the hypervisor is actively
+ updating the checkpoint as guest operations modify the disk
+ after the point where the checkpoint was created. When tracking
+ multiple checkpoints, a hypervisor may choose to either have all
+ relevant checkpoints be current (a guest write updates the
+ associated tracking for each checkpoint), or to have a single
+ checkpoint be current (older checkpoints stop tracking changes
+ when a newer one is created, and describing all changes since an
+ older checkpoint then involves libvirt automatically combining
+ the changes from the chain of checkpoints from the current back
+ to the checkpoint in question; the QEMU hypervisor uses this
+ method). Checkpoints are maintained in a hierarchy to facilitate
+ hypervisors that use this latter method, where libvirt
+ automatically updates the parent-child relationship as well as
+ which checkpoint is current when creating or deleting
+ checkpoints. For now, the creation of checkpoints is not
+ possible when external snapshots exist, but this may be added in
+ the future.
+ </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>An optional readonly representation of the parent of this
+ checkpoint. If present, this element contains exactly one
+ child element, <code>name</code>.
+ </dd>
+ <dt><code>current</code></dt>
+ <dd>A readonly integer, 1 if this checkpoint is current (that
+ is, actively tracking guest changes) or 0 if the checkpoint is
+ inactive because a child checkpoint is now tracking changes.
+ </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/formatsnapshot.html.in b/docs/formatsnapshot.html.in
index 92cc566467..2bfb69cf49 100644
--- a/docs/formatsnapshot.html.in
+++ b/docs/formatsnapshot.html.in
@@ -91,7 +91,9 @@
sets that snapshot as current, and the prior current snapshot is
the parent of the new snapshot. Branches in the hierarchy can
be formed by reverting to a snapshot with a child, then creating
- another snapshot.
+ another snapshot. For now, the creation of external snapshots
+ when checkpoints exist is forbidden, although future work will
+ make it possible to integrate these two concepts.
</p>
<p>
The top-level <code>domainsnapshot</code> element may contain
diff --git a/docs/index.html.in b/docs/index.html.in
index 2bd647f8dd..7d0ab650e3 100644
--- a/docs/index.html.in
+++ b/docs/index.html.in
@@ -58,7 +58,8 @@
<a href="formatstoragecaps.html">storage pool
capabilities</a>,
<a href="formatnode.html">node devices</a>,
<a href="formatsecret.html">secrets</a>,
- <a href="formatsnapshot.html">snapshots</a></dd>
+ <a href="formatsnapshot.html">snapshots</a>,
+ <a
href="formatcheckpoint.html">checkpoints</a></dd>
<dt><a
href="http://wiki.libvirt.org">Wiki</a></dt>
<dd>Read further community contributed content</dd>
</dl>
diff --git a/docs/schemas/domaincheckpoint.rng b/docs/schemas/domaincheckpoint.rng
new file mode 100644
index 0000000000..ceb5436aa3
--- /dev/null
+++ b/docs/schemas/domaincheckpoint.rng
@@ -0,0 +1,95 @@
+<?xml version="1.0"?>
+<!-- A Relax NG schema for the libvirt domain checkpoint properties XML format -->
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+ <start>
+ <ref name='domaincheckpoint'/>
+ </start>
+
+ <include href='domaincommon.rng'/>
+
+ <define name='domaincheckpoint'>
+ <element name='domaincheckpoint'>
+ <interleave>
+ <optional>
+ <element name='name'>
+ <text/>
+ </element>
+ </optional>
+ <optional>
+ <element name='description'>
+ <text/>
+ </element>
+ </optional>
+ <optional>
+ <element name='creationTime'>
+ <text/>
+ </element>
+ </optional>
+ <optional>
+ <element name='current'>
+ <choice>
+ <value>0</value>
+ <value>1</value>
+ </choice>
+ </element>
+ </optional>
+ <optional>
+ <element name='disks'>
+ <oneOrMore>
+ <ref name='diskcheckpoint'/>
+ </oneOrMore>
+ </element>
+ </optional>
+ <optional>
+ <!-- Nested grammar ensures that any of our overrides of
+ storagecommon/domaincommon defines do not conflict
+ with any domain.rng overrides. -->
+ <grammar>
+ <include href='domain.rng'/>
+ </grammar>
+ </optional>
+ <optional>
+ <element name='parent'>
+ <element name='name'>
+ <text/>
+ </element>
+ </element>
+ </optional>
+ </interleave>
+ </element>
+ </define>
+
+ <define name='diskcheckpoint'>
+ <element name='disk'>
+ <attribute name='name'>
+ <choice>
+ <ref name='diskTarget'/>
+ <ref name='absFilePath'/>
+ </choice>
+ </attribute>
+ <choice>
+ <attribute name='checkpoint'>
+ <value>no</value>
+ </attribute>
+ <group>
+ <optional>
+ <attribute name='checkpoint'>
+ <value>bitmap</value>
+ </attribute>
+ </optional>
+ <optional>
+ <attribute name='bitmap'>
+ <text/>
+ </attribute>
+ </optional>
+ <optional>
+ <attribute name='size'>
+ <ref name="unsignedLong"/>
+ </attribute>
+ </optional>
+ </group>
+ </choice>
+ </element>
+ </define>
+
+</grammar>
diff --git a/libvirt.spec.in b/libvirt.spec.in
index d54f58f1d4..dece22688d 100644
--- a/libvirt.spec.in
+++ b/libvirt.spec.in
@@ -1780,6 +1780,7 @@ exit 0
%{_datadir}/libvirt/schemas/cputypes.rng
%{_datadir}/libvirt/schemas/domain.rng
%{_datadir}/libvirt/schemas/domaincaps.rng
+%{_datadir}/libvirt/schemas/domaincheckpoint.rng
%{_datadir}/libvirt/schemas/domaincommon.rng
%{_datadir}/libvirt/schemas/domainsnapshot.rng
%{_datadir}/libvirt/schemas/interface.rng
diff --git a/mingw-libvirt.spec.in b/mingw-libvirt.spec.in
index ad6d6e952e..df89d9f8b3 100644
--- a/mingw-libvirt.spec.in
+++ b/mingw-libvirt.spec.in
@@ -232,6 +232,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh
%{mingw32_datadir}/libvirt/schemas/cputypes.rng
%{mingw32_datadir}/libvirt/schemas/domain.rng
%{mingw32_datadir}/libvirt/schemas/domaincaps.rng
+%{mingw32_datadir}/libvirt/schemas/domaincheckpoint.rng
%{mingw32_datadir}/libvirt/schemas/domaincommon.rng
%{mingw32_datadir}/libvirt/schemas/domainsnapshot.rng
%{mingw32_datadir}/libvirt/schemas/interface.rng
@@ -321,6 +322,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh
%{mingw64_datadir}/libvirt/schemas/cputypes.rng
%{mingw64_datadir}/libvirt/schemas/domain.rng
%{mingw64_datadir}/libvirt/schemas/domaincaps.rng
+%{mingw64_datadir}/libvirt/schemas/domaincheckpoint.rng
%{mingw64_datadir}/libvirt/schemas/domaincommon.rng
%{mingw64_datadir}/libvirt/schemas/domainsnapshot.rng
%{mingw64_datadir}/libvirt/schemas/interface.rng
diff --git a/tests/Makefile.am b/tests/Makefile.am
index e57d0da58a..66c6ad911e 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -110,6 +110,8 @@ EXTRA_DIST = \
qemublocktestdata \
qemucapabilitiesdata \
qemucaps2xmloutdata \
+ qemudomaincheckpointxml2xmlin \
+ qemudomaincheckpointxml2xmlout \
qemudomainsnapshotxml2xmlin \
qemudomainsnapshotxml2xmlout \
qemuhotplugtestcpus \
diff --git a/tests/qemudomaincheckpointxml2xmlin/empty.xml
b/tests/qemudomaincheckpointxml2xmlin/empty.xml
new file mode 100644
index 0000000000..dc36449142
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlin/empty.xml
@@ -0,0 +1 @@
+<domaincheckpoint/>
diff --git a/tests/qemudomaincheckpointxml2xmlin/sample.xml
b/tests/qemudomaincheckpointxml2xmlin/sample.xml
new file mode 100644
index 0000000000..70ed964e1e
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlin/sample.xml
@@ -0,0 +1,7 @@
+<domaincheckpoint>
+ <description>Completion of updates after OS install</description>
+ <disks>
+ <disk name='vda' checkpoint='bitmap'/>
+ <disk name='vdb' checkpoint='no'/>
+ </disks>
+</domaincheckpoint>
diff --git a/tests/qemudomaincheckpointxml2xmlin/size.xml
b/tests/qemudomaincheckpointxml2xmlin/size.xml
new file mode 100644
index 0000000000..99ce84c7a0
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlin/size.xml
@@ -0,0 +1,4 @@
+<domaincheckpoint>
+ <name>c2</name>
+ <description>something fun</description>
+</domaincheckpoint>
diff --git a/tests/qemudomaincheckpointxml2xmlout/empty.xml
b/tests/qemudomaincheckpointxml2xmlout/empty.xml
new file mode 100644
index 0000000000..ff49bef17f
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlout/empty.xml
@@ -0,0 +1,8 @@
+<domaincheckpoint>
+ <name>1525889631</name>
+ <creationTime>1525889631</creationTime>
+ <current>0</current>
+ <disks>
+ <disk name='vda' checkpoint='bitmap'
bitmap='1525889631'/>
+ </disks>
+</domaincheckpoint>
diff --git a/tests/qemudomaincheckpointxml2xmlout/redefine.xml
b/tests/qemudomaincheckpointxml2xmlout/redefine.xml
new file mode 100644
index 0000000000..44310c2e1d
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlout/redefine.xml
@@ -0,0 +1,64 @@
+<domaincheckpoint>
+ <name>c1</name>
+ <creationTime>1553647812</creationTime>
+ <current>1</current>
+ <disks>
+ <disk name='hda' checkpoint='no'/>
+ <disk name='hdc' checkpoint='no'/>
+ <disk name='vda' checkpoint='bitmap' bitmap='c1'/>
+ <disk name='vdb' checkpoint='bitmap' bitmap='c1'/>
+ </disks>
+ <domain type='qemu'>
+ <name>QEMUGuest1</name>
+ <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+ <memory unit='KiB'>219136</memory>
+ <currentMemory unit='KiB'>219136</currentMemory>
+ <vcpu placement='static'>1</vcpu>
+ <os>
+ <type arch='i686' machine='pc'>hvm</type>
+ <boot dev='hd'/>
+ </os>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <emulator>/usr/bin/qemu-system-i686</emulator>
+ <disk type='block' device='disk'>
+ <driver name='qemu' type='raw'/>
+ <source dev='/dev/HostVG/QEMUGuest1'/>
+ <target dev='hda' bus='ide'/>
+ <address type='drive' controller='0' bus='0'
target='0' unit='0'/>
+ </disk>
+ <disk type='block' device='cdrom'>
+ <driver name='qemu' type='raw'/>
+ <source dev='/dev/HostVG/QEMUGuest2'/>
+ <target dev='hdc' bus='ide'/>
+ <readonly/>
+ <address type='drive' controller='0' bus='1'
target='0' unit='0'/>
+ </disk>
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2'/>
+ <source file='/tmp/data.img'/>
+ <target dev='vda' bus='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x03' function='0x0'/>
+ </disk>
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2'/>
+ <source file='/tmp/logs.img'/>
+ <target dev='vdb' bus='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x04' function='0x0'/>
+ </disk>
+ <controller type='usb' index='0'>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x01' function='0x2'/>
+ </controller>
+ <controller type='ide' index='0'>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x01' function='0x1'/>
+ </controller>
+ <controller type='pci' index='0' model='pci-root'/>
+ <input type='mouse' bus='ps2'/>
+ <input type='keyboard' bus='ps2'/>
+ <memballoon model='none'/>
+ </devices>
+ </domain>
+</domaincheckpoint>
diff --git a/tests/qemudomaincheckpointxml2xmlout/sample.xml
b/tests/qemudomaincheckpointxml2xmlout/sample.xml
new file mode 100644
index 0000000000..913c26d2b9
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlout/sample.xml
@@ -0,0 +1,13 @@
+<domaincheckpoint>
+ <name>1525889631</name>
+ <description>Completion of updates after OS install</description>
+ <parent>
+ <name>1525111885</name>
+ </parent>
+ <creationTime>1525889631</creationTime>
+ <current>0</current>
+ <disks>
+ <disk name='vda' checkpoint='bitmap'
bitmap='1525889631'/>
+ <disk name='vdb' checkpoint='no'/>
+ </disks>
+</domaincheckpoint>
diff --git a/tests/qemudomaincheckpointxml2xmlout/size.xml
b/tests/qemudomaincheckpointxml2xmlout/size.xml
new file mode 100644
index 0000000000..17d884983d
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlout/size.xml
@@ -0,0 +1,12 @@
+<domaincheckpoint>
+ <name>c2</name>
+ <description>something fun</description>
+ <parent>
+ <name>1525111885</name>
+ </parent>
+ <creationTime>1553648510</creationTime>
+ <current>1</current>
+ <disks>
+ <disk name='vda' checkpoint='bitmap' bitmap='c2'
size='1048576'/>
+ </disks>
+</domaincheckpoint>
diff --git a/tests/virschematest.c b/tests/virschematest.c
index b7c2f7cfaa..8f5101df21 100644
--- a/tests/virschematest.c
+++ b/tests/virschematest.c
@@ -222,6 +222,8 @@ mymain(void)
"genericxml2xmloutdata", "xlconfigdata",
"libxlxml2domconfigdata",
"qemuhotplugtestdomains");
DO_TEST_DIR("domaincaps.rng", "domaincapsschemadata");
+ DO_TEST_DIR("domaincheckpoint.rng",
"qemudomaincheckpointxml2xmlin",
+ "qemudomaincheckpointxml2xmlout");
DO_TEST_DIR("domainsnapshot.rng", "qemudomainsnapshotxml2xmlin",
"qemudomainsnapshotxml2xmlout");
DO_TEST_DIR("interface.rng", "interfaceschemadata");
--
2.20.1
6:23 a.m.
New subject: [libvirt] [PATCH v9 01/13] backup: Document new XML for checkpoints
On Sat, Jul 06, 2019 at 22:56:01 -0500, Eric Blake wrote:
Prepare for new checkpoint APIs by describing the XML that will
represent a checkpoint. The checkpoint XML is modeled heavily after
virDomainSnapshotPtr. See the docs for more details.
Add testsuite coverage for some minimal uses of the XML (bare minimum,
the sample from html, and a full dumpxml). Although use of the
REDEFINE flag will require the <domain> subelement to be present, it
is easier for most of the tests to provide counterpart output produced
with the NO_DOMAIN flag (particularly since synthesizing a valid
<domain> during testing is not trivial).
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
[...]
diff --git a/docs/formatcheckpoint.html.in
b/docs/formatcheckpoint.html.in
new file mode 100644
index 0000000000..ef5f8a826b
--- /dev/null
+++ b/docs/formatcheckpoint.html.in
@@ -0,0 +1,218 @@
+<?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.
Perhaps add a 'since' to note that all of this was added starting from
5.6.
+ </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>.
So it will not happen in this release? Otherwise I don't see a point in
documenting it.
+ </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>
+ A checkpoint is marked current if the hypervisor is actively
+ updating the checkpoint as guest operations modify the disk
+ after the point where the checkpoint was created. When tracking
+ multiple checkpoints, a hypervisor may choose to either have all
+ relevant checkpoints be current (a guest write updates thea
So to reiterate. By definition all checkpoint should be "current",
because they must be actively updated to be able to track the difference
from the point when they were created until now.
The fact whether it includes update to a bitmap and which bitmaps are
updated does not seem to be relevant for outside users.
In fact we may even opt to change how this is done or perhaps convert
one layout of bitmaps into a different one if we insist.
Thus I'm saying it again. "current" property seems to be wrong in
conjunction with checkpoints.
+ associated tracking for each checkpoint), or to have a single
+ checkpoint be current (older checkpoints stop tracking changes
NACK, internal detail. Don't document it. Also I'll object to this later
in detail.
+ when a newer one is created, and describing all changes since
an
+ older checkpoint then involves libvirt automatically combining
+ the changes from the chain of checkpoints from the current back
+ to the checkpoint in question; the QEMU hypervisor uses this
+ method). Checkpoints are maintained in a hierarchy to facilitate
Nope. All of the above seem to be internal stuff.
+ hypervisors that use this latter method, where libvirt
+ automatically updates the parent-child relationship as well as
+ which checkpoint is current when creating or deleting
+ checkpoints. For now, the creation of checkpoints is not
+ possible when external snapshots exist, but this may be added in
+ the future.
+ </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>An optional readonly representation of the parent of this
+ checkpoint. If present, this element contains exactly one
+ child element, <code>name</code>.
This reads weird and does not seem to say much.
+ </dd>
+ <dt><code>current</code></dt>
+ <dd>A readonly integer, 1 if this checkpoint is current (that
+ is, actively tracking guest changes) or 0 if the checkpoint is
+ inactive because a child checkpoint is now tracking changes.
+ </dd>
See below in the schema. The contents of this element are wrong.
+ <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/formatsnapshot.html.in b/docs/formatsnapshot.html.in
index 92cc566467..2bfb69cf49 100644
--- a/docs/formatsnapshot.html.in
+++ b/docs/formatsnapshot.html.in
@@ -91,7 +91,9 @@
sets that snapshot as current, and the prior current snapshot is
the parent of the new snapshot. Branches in the hierarchy can
be formed by reverting to a snapshot with a child, then creating
- another snapshot.
+ another snapshot. For now, the creation of external snapshots
+ when checkpoints exist is forbidden, although future work will
+ make it possible to integrate these two concepts.
</p>
<p>
The top-level <code>domainsnapshot</code> element may contain
I'd slightly prefer if the snapshot-interlock stuff is in a separate
patch.
[...]
diff --git a/docs/schemas/domaincheckpoint.rng
b/docs/schemas/domaincheckpoint.rng
new file mode 100644
index 0000000000..ceb5436aa3
--- /dev/null
+++ b/docs/schemas/domaincheckpoint.rng
@@ -0,0 +1,95 @@
+<?xml version="1.0"?>
+<!-- A Relax NG schema for the libvirt domain checkpoint properties XML format
-->
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+ <start>
+ <ref name='domaincheckpoint'/>
+ </start>
+
+ <include href='domaincommon.rng'/>
+
+ <define name='domaincheckpoint'>
+ <element name='domaincheckpoint'>
+ <interleave>
+ <optional>
+ <element name='name'>
+ <text/>
This should be something more sensible than '<text/>' we have plenty of
types for names which exclude newlines and '/'.
+ </element>
+ </optional>
+ <optional>
+ <element name='description'>
+ <text/>
+ </element>
+ </optional>
+ <optional>
+ <element name='creationTime'>
+ <text/>
This is supposed to be a number.
+ </element>
+ </optional>
+ <optional>
+ <element name='current'>
+ <choice>
+ <value>0</value>
+ <value>1</value>
This looks weird. I see 3 options to make it better:
1) put it as an attribute of 'domaincheckpoint' (and use
'yes'/'no' as
values)
2) encode it as presence of the element
3) at least use 'yes'/'no' as values.
+ </choice>
+ </element>
+ </optional>
+ <optional>
+ <element name='disks'>
+ <oneOrMore>
+ <ref name='diskcheckpoint'/>
+ </oneOrMore>
+ </element>
+ </optional>
+ <optional>
+ <!-- Nested grammar ensures that any of our overrides of
+ storagecommon/domaincommon defines do not conflict
+ with any domain.rng overrides. -->
+ <grammar>
+ <include href='domain.rng'/>
+ </grammar>
+ </optional>
+ <optional>
+ <element name='parent'>
+ <element name='name'>
+ <text/>
Again, this is a 'name'
+ </element>
+ </element>
+ </optional>
+ </interleave>
+ </element>
+ </define>
+
+ <define name='diskcheckpoint'>
+ <element name='disk'>
+ <attribute name='name'>
+ <choice>
+ <ref name='diskTarget'/>
+ <ref name='absFilePath'/>
+ </choice>
+ </attribute>
+ <choice>
+ <attribute name='checkpoint'>
+ <value>no</value>
+ </attribute>
+ <group>
+ <optional>
+ <attribute name='checkpoint'>
+ <value>bitmap</value>
+ </attribute>
+ </optional>
+ <optional>
+ <attribute name='bitmap'>
+ <text/>
This is also a 'name'
+ </attribute>
+ </optional>
+ <optional>
+ <attribute name='size'>
+ <ref name="unsignedLong"/>
+ </attribute>
+ </optional>
+ </group>
+ </choice>
+ </element>
+ </define>
+
+</grammar>
ACK if you sanitize the schema and avoid documenting internals in the
public docs. I think that also the bitmap name field should be
documented as internal.
1:33 p.m.
New subject: [libvirt] [PATCH v9 01/13] backup: Document new XML for checkpoints
On 7/8/19 6:23 AM, Peter Krempa wrote:
On Sat, Jul 06, 2019 at 22:56:01 -0500, Eric Blake wrote:
> Prepare for new checkpoint APIs by describing the XML that will
> represent a checkpoint. The checkpoint XML is modeled heavily after
> virDomainSnapshotPtr. See the docs for more details.
>
> Add testsuite coverage for some minimal uses of the XML (bare minimum,
> the sample from html, and a full dumpxml). Although use of the
> REDEFINE flag will require the <domain> subelement to be present, it
> is easier for most of the tests to provide counterpart output produced
> with the NO_DOMAIN flag (particularly since synthesizing a valid
> <domain> during testing is not trivial).
>
> Signed-off-by: Eric Blake <eblake(a)redhat.com>
> ---
[...]
> + <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.
Perhaps add a 'since' to note that all of this was added starting from
5.6.
Yes.
> + </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>.
So it will not happen in this release? Otherwise I don't see a point in
documenting it.
virDomainBackupBegin still has a fighting chance of making it into 5.6;
virDomainSnapshotCreateXML2 is further down the road. My most recent
post of 'backup-v9' for backup additions tweak this paragraph yet again
when virDomainBackupBegin is added:
https://www.redhat.com/archives/libvir-list/2019-July/msg00330.html
> + <p>
> + A checkpoint is marked current if the hypervisor is actively
> + updating the checkpoint as guest operations modify the disk
> + after the point where the checkpoint was created. When tracking
> + multiple checkpoints, a hypervisor may choose to either have all
> + relevant checkpoints be current (a guest write updates thea
So to reiterate. By definition all checkpoint should be "current",
because they must be actively updated to be able to track the difference
from the point when they were created until now.
The fact whether it includes update to a bitmap and which bitmaps are
updated does not seem to be relevant for outside users.
In fact we may even opt to change how this is done or perhaps convert
one layout of bitmaps into a different one if we insist.
Thus I'm saying it again. "current" property seems to be wrong in
conjunction with checkpoints.
Updating this thread based on an IRC conversation (I'm not pasting the
entire conversation, but hitting the key points, so Peter may still want
to chime in):
There's two ways to do differential backups in qemu: either make all
checkpoints use an active bitmap (no parent relationship is needed, all
checkpoints would appear as roots), or change which bitmap is active on
a per-disk basis when a newer checkpoint touches that disk (checkpoints
need a parent relationship in order to reconstruct which bitmaps to
merge together when performing a differential backup). But where things
get interesting is if a user performs a checkpoint/incremental backup of
only a subset of the domain's disks.
So, consider a domain with three disks, A, B, and C, and where we have
two users interested in different incremental backup goals: user 1 only
cares about backups of disk A and B, user 2 only cares about backups of
disk B and C. Over time, we have user 1 create chk1.1, user 2 creates
chk2.1, user 1 creates chk1.2, user 2 creates chk2.2.
chk1.1 => A.chk1.1, B.chk1.1
chk2.1 => B.chk2.1, C.chk2.1
chk1.2 => A.chk1.2, B.chk1.2
chk2.2 => B.chk2.2, C.chk2.2
then what happens when user 1 wants to do what they think is an
incremental backup starting from chk1.2 or a differential backup
starting from chk1.1. If we always leave bitmaps active, then we don't
need to track any parent relationships; the incremental or differential
backup is trivial: use the single bitmap recorded in the checkpoint
being used as the starting point. However, disk B has a lot of overhead
with every guest write potentially updating 4 bitmaps.
Or, we can take the approach that Checkpoints are always created with
the parent object being the most-recent previously-created checkpoint
(this has to be tracked somewhere, but not necessarily exposed through
the XML nor through specialized API - even though the specialized API
was how the Snapshot was implemented), AND with the notion that every
disk has at most one active bitmap, but the active bitmap might not be
in the most-recent checkpoint. When a checkpoint is created, it's
parent is assigned to be the most-recent existing checkpoint, and for
every disk in the new checkpoint, any earlier checkpoint (possibly
further back than the parent) touching the same disk has that earlier
bitmap disabled.
Or using the above figure for reference, the act of creating chk1.2
touches only disks A and B, but sets chk2.1 as the immediate parent
(even though it covers a different set of disks). Furthermore, in
addition to creating new bitmaps for disk A and B, it disables A.chk1.1
(found in the grandparent checkpoint) and B.chk2.1 (in the parent, since
B.chk1.1 is already disabled). Then, after chk2.2 is created, and the
user requests chk1.2 as the point of reference for a backup operation,
the user is requesting an incremental backup of disk A (can use bitmap
A.chk1.2 in isolation) at the same time as a differential backup of
disk B (the merge of bitmaps B.chk.1.2 and B.chk2.2). Thus, both the
act of creating a checkpoint and the act of starting a backup operation
have to concern themselves with performing a per-disk search along the
checkpoint chain from the current checkpoint back through ancestors
(creation chases until the chain ends, backup chases until the
point-of-reference checkpoint). What's more, a checkpoint being current
is orthogonal to whether a bitmap is active, so we really never do have
more than one current checkpoint, and the documentation attempt here is
wrong (current is not about which bitmaps are active, but about which
checkpoint becomes the parent when a new checkpoint is added).
However, one observation we made on IRC was the following: when
snapshots were first created, we needed a way to recreate the libvirt
metadata, and the list APIs listed snapshots in an arbitrary order. That
meant that when using the REDEFINE flag, you needed to pass in a second
flag CURRENT to mark which snapshot being redefined was to become the
domain's current snapshot (and thus the implicit parent of any future
snapshot) - and as a result of that API, a side-effect was that you
could arbitrarily change the current snapshot ('virsh snapshot-current'
is rather gross, but shows this abuse). Also, snapshots have a revert
operation, which changes the current snapshot and makes it very easy to
have a current snapshot which is not a leaf node. On the other hand,
with checkpoints and our current interlock against mixing with snapshot
revert, the current node is always a leaf node, and if you perform your
listing of all checkpoints with the recently introduced TOPOLOGICAL
flag, then it is just as easy to state that when using REDEFINE in the
same order, the last checkpoint thus redefined becomes the current node.
It may still be possible to create multiple child checkpoints to a
single parent once we work out how to enable revert-to-snapshots
combined with checkpoints. And when that happens, we may need to add a
CHECKPOINT_CURRENT flag for use with REDEFINE at that time, but it does
not have to be today. In other words, for as long as our checkpoint
chain is linear and the current node is the (one and only) leaf, we
don't need any API for managing a current checkpoint.
The IRC conversation also pointed out that before I push things, I _do_
also need to interlock such that the existence of checkpoints prevents
blockpull/blockcommit, in case libvirt is started with an external
backing chain of bitmaps created outside of libvirt, even though libvirt
itself will refuse to create such a chain.
> + associated tracking for each checkpoint), or to have a single
> + checkpoint be current (older checkpoints stop tracking changes
NACK, internal detail. Don't document it. Also I'll object to this later
in detail.
> + when a newer one is created, and describing all changes since an
> + older checkpoint then involves libvirt automatically combining
> + the changes from the chain of checkpoints from the current back
> + to the checkpoint in question; the QEMU hypervisor uses this
> + method). Checkpoints are maintained in a hierarchy to facilitate
Nope. All of the above seem to be internal stuff.
So for my next spin of this patch, my goal is to eliminate as much
public API/XML related to a current checkpoint as possible, and see if I
can implement it completely internally by using the one-and-only leaf
node as the current checkpoint.
> + </dd>
> + <dt><code>parent</code></dt>
> + <dd>An optional readonly representation of the parent of this
> + checkpoint. If present, this element contains exactly one
> + child element, <code>name</code>.
This reads weird and does not seem to say much.
Copying from snapshots. I kept the same XML for consistency:
<domaincheckpoint>
<parent>
<name>name_of_parent</name>
</parent>
...
even though if I were designing it from scratch, I would prefer:
<domaincheckpoint>
<parent>name_of_parent</parent>
...
But maybe I can tweak the wording in that paragraph (and its counterpart
in the snapshot docs) to be easier to understand.
> + </dd>
> + <dt><code>current</code></dt>
> + <dd>A readonly integer, 1 if this checkpoint is current (that
> + is, actively tracking guest changes) or 0 if the checkpoint is
> + inactive because a child checkpoint is now tracking changes.
> + </dd>
See below in the schema. The contents of this element are wrong.
If I can get by without any mention of current in the public XML
(perhaps by relying on the rule that as long as we have interlocks with
snapshots, we can't branch, and therefore there is at most one leaf
node, and simply define that the leaf node IS the current node), then
this goes away.
> +++ b/docs/formatsnapshot.html.in
> @@ -91,7 +91,9 @@
> sets that snapshot as current, and the prior current snapshot is
> the parent of the new snapshot. Branches in the hierarchy can
> be formed by reverting to a snapshot with a child, then creating
> - another snapshot.
> + another snapshot. For now, the creation of external snapshots
> + when checkpoints exist is forbidden, although future work will
> + make it possible to integrate these two concepts.
> </p>
> <p>
> The top-level <code>domainsnapshot</code> element may contain
I'd slightly prefer if the snapshot-interlock stuff is in a separate
patch.
Okay, I can split.
> + <define name='domaincheckpoint'>
> + <element name='domaincheckpoint'>
> + <interleave>
> + <optional>
> + <element name='name'>
> + <text/>
This should be something more sensible than '<text/>' we have plenty of
types for names which exclude newlines and '/'.
Copying from <domainsnapshot> but yes, that's not a good excuse, and
it's always easier to relax later than it is to restrict later. And
since we DO store the checkpoint name as a file (at least for qemu),
restricting the RNG up front makes it easier to prevent the use of '../'
as a name, since we're strictly validating RNG compliance.
> + </element>
> + </optional>
> + <optional>
> + <element name='description'>
> + <text/>
> + </element>
> + </optional>
> + <optional>
> + <element name='creationTime'>
> + <text/>
This is supposed to be a number.
Copying from <domainsnapshot>, but yes this can be improved.
> + </element>
> + </optional>
> + <optional>
> + <element name='current'>
> + <choice>
> + <value>0</value>
> + <value>1</value>
This looks weird. I see 3 options to make it better:
1) put it as an attribute of 'domaincheckpoint' (and use
'yes'/'no' as
values)
2) encode it as presence of the element
3) at least use 'yes'/'no' as values.
or 4) don't have it, after all (at least, not until we work out whether
integration with snapshot revert will require it).
ACK if you sanitize the schema and avoid documenting internals in the
public docs. I think that also the bitmap name field should be
documented as internal.
Makes sense - the field will still be in the RNG schema (for two
reasons: REDEFINE must document everything it will parse, and when not
using REDEFINE, it's still often easier to copy-and-paste an existing
checkpoint XML to form a new checkpoint XML, without having to worry
about scrubbing out the readonly fields that will be ignored in the new
checkpoint), but I can document it as ignored during creation and
read-only in output for which bitmap got created.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org
10:56 p.m.
New subject: [libvirt] [PATCH v9 02/13] backup: Introduce virDomainCheckpoint APIs
Introduce a bunch of new public APIs related to backup checkpoints.
Checkpoints are modeled heavily after virDomainSnapshotPtr (both
represent a point in time of the guest), although a snapshot exists
with the intent of rolling back to that state, while a checkpoint
exists to make it possible to create an incremental backup at a later
time. We may have a future hypervisor that can completely manage
checkpoints without libvirt metadata, but the first two planned
hypervisors (qemu and test) both always use libvirt for tracking
metadata relations between checkpoints, so for now, I've deferred
the counterpart of virDomainSnapshotHasMetadata for a separate
API addition at a later date if there is ever a need for it.
The following map shows the API relations to snapshots, with new APIs
on the right:
Operate on a domain object to create/redefine a child:
virDomainSnapshotCreateXML virDomainCheckpointCreateXML
Operate on a child object for lifetime management:
virDomainSnapshotDelete virDomainCheckpointDelete
virDomainSnapshotFree virDomainCheckpointFree
virDomainSnapshotRef virDomainCheckpointRef
Operate on a child object to learn more about it:
virDomainSnapshotGetXMLDesc virDomainCheckpointGetXMLDesc
virDomainSnapshotGetConnect virDomainCheckpointGetConnect
virDomainSnapshotGetDomain virDomainCheckpointGetDomain
virDomainSnapshotGetName virDomainCheckpiontGetName
virDomainSnapshotGetParent virDomainCheckpiontGetParent
virDomainSnapshotHasMetadata (deferred for later)
virDomainSnapshotIsCurrent (no counterpart, present in XML instead)
Operate on a domain object to list all children:
virDomainSnapshotNum (no counterparts, these are the old
virDomainSnapshotListNames racy interfaces)
virDomainSnapshotListAllSnapshots virDomainListAllCheckpoints
Operate on a child object to list descendents:
virDomainSnapshotNumChildren (no counterparts, these are the old
virDomainSnapshotListChildrenNames racy interfaces)
virDomainSnapshotListAllChildren virDomainCheckpointListAllChildren
Operate on a domain to locate a particular child:
virDomainSnapshotLookupByName virDomainCheckpointLookupByName
virDomainSnapshotCurrent (obtained by flag to ListAllCheckpoints)
virDomainHasCurrentSnapshot (no counterpart, old racy interface)
Operate on a snapshot to roll back to earlier state:
virDomainSnapshotRevert (no counterpart, instead checkpoints
are used in incremental backups via
XML to virDomainBackupBegin)
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
include/libvirt/libvirt-domain-checkpoint.h | 143 +++++
include/libvirt/libvirt-domain.h | 6 +
include/libvirt/libvirt.h | 5 +-
src/conf/virdomainmomentobjlist.h | 5 +-
src/driver-hypervisor.h | 38 ++
docs/Makefile.am | 3 +
docs/apibuild.py | 2 +
docs/docs.html.in | 1 +
libvirt.spec.in | 1 +
mingw-libvirt.spec.in | 2 +
po/POTFILES | 1 +
src/Makefile.am | 2 +
src/libvirt-domain-checkpoint.c | 586 ++++++++++++++++++++
src/libvirt-domain.c | 19 +-
src/libvirt_public.syms | 16 +
15 files changed, 821 insertions(+), 9 deletions(-)
create mode 100644 include/libvirt/libvirt-domain-checkpoint.h
create mode 100644 src/libvirt-domain-checkpoint.c
diff --git a/include/libvirt/libvirt-domain-checkpoint.h
b/include/libvirt/libvirt-domain-checkpoint.h
new file mode 100644
index 0000000000..b2d5c5758b
--- /dev/null
+++ b/include/libvirt/libvirt-domain-checkpoint.h
@@ -0,0 +1,143 @@
+/*
+ * libvirt-domain-checkpoint.h
+ * Summary: APIs for management of domain checkpoints
+ * Description: Provides APIs for the management of domain checkpoints
+ *
+ * Copyright (C) 2006-2019 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ */
+
+#ifndef LIBVIRT_DOMAIN_CHECKPOINT_H
+# define LIBVIRT_DOMAIN_CHECKPOINT_H
+
+# ifndef __VIR_LIBVIRT_H_INCLUDES__
+# error "Don't include this file directly, only use libvirt/libvirt.h"
+# endif
+
+/**
+ * virDomainCheckpoint:
+ *
+ * A virDomainCheckpoint is a private structure representing a checkpoint of
+ * a domain. A checkpoint is useful for tracking which portions of the
+ * domain disks have been altered since a point in time, but by itself does
+ * not allow reverting back to that point in time.
+ */
+typedef struct _virDomainCheckpoint virDomainCheckpoint;
+
+/**
+ * virDomainCheckpointPtr:
+ *
+ * A virDomainCheckpointPtr is pointer to a virDomainCheckpoint
+ * private structure, and is the type used to reference a domain
+ * checkpoint in the API.
+ */
+typedef virDomainCheckpoint *virDomainCheckpointPtr;
+
+const char *virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint);
+virDomainPtr virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint);
+virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint);
+
+typedef enum {
+ VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE = (1 << 0), /* Restore or alter
+ metadata */
+ VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA = (1 << 1), /* Make checkpoint
without
+ remembering it */
+ VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE = (1 << 2), /* use guest agent to
+ quiesce all mounted
+ file systems within
+ the domain */
+} virDomainCheckpointCreateFlags;
+
+/* Create a checkpoint using the current VM state. */
+virDomainCheckpointPtr virDomainCheckpointCreateXML(virDomainPtr domain,
+ const char *xmlDesc,
+ unsigned int flags);
+
+typedef enum {
+ VIR_DOMAIN_CHECKPOINT_XML_SECURE = (1 << 0), /* Include sensitive data */
+ VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN = (1 << 1), /* Suppress <domain>
+ subelement */
+ VIR_DOMAIN_CHECKPOINT_XML_SIZE = (1 << 2), /* Include dynamic
+ per-<disk> size */
+} virDomainCheckpointXMLFlags;
+
+/* Dump the XML of a checkpoint */
+char *virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
+ unsigned int flags);
+
+/**
+ * virDomainCheckpointListFlags:
+ *
+ * Flags valid for virDomainListAllCheckpoints() and
+ * virDomainCheckpointListAllChildren(). Note that the interpretation of
+ * flag (1<<0) depends on which function it is passed to; but serves
+ * to toggle the per-call default of whether the listing is shallow or
+ * recursive. Remaining bits come in groups; if all bits from a group
+ * are 0, then that group is not used to filter results. */
+typedef enum {
+ VIR_DOMAIN_CHECKPOINT_LIST_ROOTS = (1 << 0), /* Filter by checkpoints
+ with no parents, when
+ listing a domain */
+ VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS = (1 << 0), /* List all descendants,
+ not just children, when
+ listing a checkpoint */
+ VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL = (1 << 1), /* Ensure parents occur
+ before children in
+ the resulting list */
+
+ VIR_DOMAIN_CHECKPOINT_LIST_LEAVES = (1 << 2), /* Filter by checkpoints
+ with no children */
+ VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES = (1 << 3), /* Filter by checkpoints
+ that have children */
+ VIR_DOMAIN_CHECKPOINT_LIST_CURRENT = (1 << 4), /* Filter by checkpoints
+ that are current */
+ VIR_DOMAIN_CHECKPOINT_LIST_NO_CURRENT = (1 << 5), /* Filter by checkpoints
+ that are inactive */
+} virDomainCheckpointListFlags;
+
+/* Get all checkpoint objects for this domain */
+int virDomainListAllCheckpoints(virDomainPtr domain,
+ virDomainCheckpointPtr **checkpoints,
+ unsigned int flags);
+
+/* Get all checkpoint object children for this checkpoint */
+int virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
+ virDomainCheckpointPtr **children,
+ unsigned int flags);
+
+/* Get a handle to a named checkpoint */
+virDomainCheckpointPtr virDomainCheckpointLookupByName(virDomainPtr domain,
+ const char *name,
+ unsigned int flags);
+
+/* Get a handle to the parent checkpoint, if one exists */
+virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
+ unsigned int flags);
+
+/* Delete a checkpoint */
+typedef enum {
+ VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = (1 << 0), /* Also delete children
*/
+ VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata
*/
+ VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY = (1 << 2), /* Delete just children
*/
+} virDomainCheckpointDeleteFlags;
+
+int virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
+ unsigned int flags);
+
+int virDomainCheckpointRef(virDomainCheckpointPtr checkpoint);
+int virDomainCheckpointFree(virDomainCheckpointPtr checkpoint);
+
+#endif /* LIBVIRT_DOMAIN_CHECKPOINT_H */
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 2dbd74d4f3..f160ee88b5 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -1800,6 +1800,9 @@ typedef enum {
VIR_DOMAIN_UNDEFINE_NVRAM = (1 << 2), /* Also remove any
nvram file */
VIR_DOMAIN_UNDEFINE_KEEP_NVRAM = (1 << 3), /* Keep nvram file */
+ VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA = (1 << 4), /* If last use of domain,
+ then also remove any
+ checkpoint metadata */
/* Future undefine control flags should come here. */
} virDomainUndefineFlagsValues;
@@ -1838,6 +1841,9 @@ typedef enum {
VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT = 1 << 12,
VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT = 1 << 13,
+
+ VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT = 1 << 14,
+ VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT = 1 << 15,
} virConnectListAllDomainsFlags;
int virConnectListAllDomains (virConnectPtr conn,
diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h
index 13de151cb6..f93e3bfa85 100644
--- a/include/libvirt/libvirt.h
+++ b/include/libvirt/libvirt.h
@@ -34,10 +34,7 @@ extern "C" {
# include <libvirt/libvirt-common.h>
# include <libvirt/libvirt-host.h>
# include <libvirt/libvirt-domain.h>
-/* FIXME: Temporary hack until later patch creates new
- * libvirt-domain-checkpoint.h file */
-typedef struct _virDomainCheckpoint virDomainCheckpoint;
-typedef virDomainCheckpoint *virDomainCheckpointPtr;
+# include <libvirt/libvirt-domain-checkpoint.h>
# include <libvirt/libvirt-domain-snapshot.h>
# include <libvirt/libvirt-event.h>
# include <libvirt/libvirt-interface.h>
diff --git a/src/conf/virdomainmomentobjlist.h b/src/conf/virdomainmomentobjlist.h
index 7628df5e29..3402f6aa3a 100644
--- a/src/conf/virdomainmomentobjlist.h
+++ b/src/conf/virdomainmomentobjlist.h
@@ -70,8 +70,9 @@ virDomainMomentObjPtr virDomainMomentAssignDef(virDomainMomentObjListPtr
moments
virDomainMomentDefPtr def);
/* Various enum bits that map to public API filters. Note that the
- * values of the internal bits are not necessarily the same as the
- * public ones. */
+ * values of the internal bits are not the same as the public ones for
+ * snapshot, however, this list should be kept in sync with the public
+ * ones for checkpoint. */
typedef enum {
VIR_DOMAIN_MOMENT_LIST_ROOTS = (1 << 0),
VIR_DOMAIN_MOMENT_LIST_DESCENDANTS = (1 << 0),
diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h
index b15aaa36bc..c1632ae4c6 100644
--- a/src/driver-hypervisor.h
+++ b/src/driver-hypervisor.h
@@ -1327,6 +1327,37 @@ typedef int
int *nparams,
unsigned int flags);
+typedef virDomainCheckpointPtr
+(*virDrvDomainCheckpointCreateXML)(virDomainPtr domain,
+ const char *xmlDesc,
+ unsigned int flags);
+
+typedef char *
+(*virDrvDomainCheckpointGetXMLDesc)(virDomainCheckpointPtr checkpoint,
+ unsigned int flags);
+
+typedef int
+(*virDrvDomainListAllCheckpoints)(virDomainPtr domain,
+ virDomainCheckpointPtr **checkpoints,
+ unsigned int flags);
+
+typedef int
+(*virDrvDomainCheckpointListAllChildren)(virDomainCheckpointPtr checkpoint,
+ virDomainCheckpointPtr **children,
+ unsigned int flags);
+
+typedef virDomainCheckpointPtr
+(*virDrvDomainCheckpointLookupByName)(virDomainPtr domain,
+ const char *name,
+ unsigned int flags);
+
+typedef virDomainCheckpointPtr
+(*virDrvDomainCheckpointGetParent)(virDomainCheckpointPtr checkpoint,
+ unsigned int flags);
+
+typedef int
+(*virDrvDomainCheckpointDelete)(virDomainCheckpointPtr checkpoint,
+ unsigned int flags);
typedef struct _virHypervisorDriver virHypervisorDriver;
typedef virHypervisorDriver *virHypervisorDriverPtr;
@@ -1579,4 +1610,11 @@ struct _virHypervisorDriver {
virDrvConnectBaselineHypervisorCPU connectBaselineHypervisorCPU;
virDrvNodeGetSEVInfo nodeGetSEVInfo;
virDrvDomainGetLaunchSecurityInfo domainGetLaunchSecurityInfo;
+ virDrvDomainCheckpointCreateXML domainCheckpointCreateXML;
+ virDrvDomainCheckpointGetXMLDesc domainCheckpointGetXMLDesc;
+ virDrvDomainListAllCheckpoints domainListAllCheckpoints;
+ virDrvDomainCheckpointListAllChildren domainCheckpointListAllChildren;
+ virDrvDomainCheckpointLookupByName domainCheckpointLookupByName;
+ virDrvDomainCheckpointGetParent domainCheckpointGetParent;
+ virDrvDomainCheckpointDelete domainCheckpointDelete;
};
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 977be471ad..aaf26ae55a 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -22,6 +22,7 @@ DEVHELP_DIR=$(datadir)/gtk-doc/html/libvirt
modules = \
libvirt-common \
libvirt-domain \
+ libvirt-domain-checkpoint \
libvirt-domain-snapshot \
libvirt-event \
libvirt-host \
@@ -312,6 +313,7 @@ $(python_generated_files): $(APIBUILD_STAMP)
$(APIBUILD_STAMP): $(srcdir)/apibuild.py \
$(top_srcdir)/include/libvirt/libvirt.h \
$(top_srcdir)/include/libvirt/libvirt-common.h.in \
+ $(top_srcdir)/include/libvirt/libvirt-domain-checkpoint.h \
$(top_srcdir)/include/libvirt/libvirt-domain-snapshot.h \
$(top_srcdir)/include/libvirt/libvirt-domain.h \
$(top_srcdir)/include/libvirt/libvirt-event.h \
@@ -328,6 +330,7 @@ $(APIBUILD_STAMP): $(srcdir)/apibuild.py \
$(top_srcdir)/include/libvirt/libvirt-admin.h \
$(top_srcdir)/include/libvirt/virterror.h \
$(top_srcdir)/src/libvirt.c \
+ $(top_srcdir)/src/libvirt-domain-checkpoint.c \
$(top_srcdir)/src/libvirt-domain-snapshot.c \
$(top_srcdir)/src/libvirt-domain.c \
$(top_srcdir)/src/libvirt-host.c \
diff --git a/docs/apibuild.py b/docs/apibuild.py
index 9e04871220..dbdc1c95af 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -26,6 +26,7 @@ debugsym = None
included_files = {
"libvirt-common.h": "header with general libvirt API definitions",
"libvirt-domain.h": "header with general libvirt API definitions",
+ "libvirt-domain-checkpoint.h": "header with general libvirt API
definitions",
"libvirt-domain-snapshot.h": "header with general libvirt API
definitions",
"libvirt-event.h": "header with general libvirt API definitions",
"libvirt-host.h": "header with general libvirt API definitions",
@@ -39,6 +40,7 @@ included_files = {
"virterror.h": "header with error specific API definitions",
"libvirt.c": "Main interfaces for the libvirt library",
"libvirt-domain.c": "Domain interfaces for the libvirt library",
+ "libvirt-domain-checkpoint.c": "Domain checkpoint interfaces for the
libvirt library",
"libvirt-domain-snapshot.c": "Domain snapshot interfaces for the libvirt
library",
"libvirt-host.c": "Host interfaces for the libvirt library",
"libvirt-interface.c": "Interface interfaces for the libvirt
library",
diff --git a/docs/docs.html.in b/docs/docs.html.in
index 55cbab5f15..2d44e3ab2e 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -99,6 +99,7 @@
<dd>Reference manual for the C public API, split in
<a href="html/libvirt-libvirt-common.html">common</a>,
<a href="html/libvirt-libvirt-domain.html">domain</a>,
+ <a href="html/libvirt-libvirt-domain-checkpoint.html">domain
checkpoint</a>,
<a href="html/libvirt-libvirt-domain-snapshot.html">domain
snapshot</a>,
<a href="html/libvirt-virterror.html">error</a>,
<a href="html/libvirt-libvirt-event.html">event</a>,
diff --git a/libvirt.spec.in b/libvirt.spec.in
index dece22688d..ffadaf2d49 100644
--- a/libvirt.spec.in
+++ b/libvirt.spec.in
@@ -1840,6 +1840,7 @@ exit 0
%{_includedir}/libvirt/libvirt-admin.h
%{_includedir}/libvirt/libvirt-common.h
%{_includedir}/libvirt/libvirt-domain.h
+%{_includedir}/libvirt/libvirt-domain-checkpoint.h
%{_includedir}/libvirt/libvirt-domain-snapshot.h
%{_includedir}/libvirt/libvirt-event.h
%{_includedir}/libvirt/libvirt-host.h
diff --git a/mingw-libvirt.spec.in b/mingw-libvirt.spec.in
index df89d9f8b3..a20c4b7d74 100644
--- a/mingw-libvirt.spec.in
+++ b/mingw-libvirt.spec.in
@@ -264,6 +264,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh
%{mingw32_includedir}/libvirt/libvirt.h
%{mingw32_includedir}/libvirt/libvirt-common.h
%{mingw32_includedir}/libvirt/libvirt-domain.h
+%{mingw32_includedir}/libvirt/libvirt-domain-checkpoint.h
%{mingw32_includedir}/libvirt/libvirt-domain-snapshot.h
%{mingw32_includedir}/libvirt/libvirt-event.h
%{mingw32_includedir}/libvirt/libvirt-host.h
@@ -354,6 +355,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh
%{mingw64_includedir}/libvirt/libvirt.h
%{mingw64_includedir}/libvirt/libvirt-common.h
%{mingw64_includedir}/libvirt/libvirt-domain.h
+%{mingw64_includedir}/libvirt/libvirt-domain-checkpoint.h
%{mingw64_includedir}/libvirt/libvirt-domain-snapshot.h
%{mingw64_includedir}/libvirt/libvirt-event.h
%{mingw64_includedir}/libvirt/libvirt-host.h
diff --git a/po/POTFILES b/po/POTFILES
index 8017712ff4..21eea80329 100644
--- a/po/POTFILES
+++ b/po/POTFILES
@@ -69,6 +69,7 @@ src/interface/interface_backend_netcf.c
src/interface/interface_backend_udev.c
src/internal.h
src/libvirt-admin.c
+src/libvirt-domain-checkpoint.c
src/libvirt-domain-snapshot.c
src/libvirt-domain.c
src/libvirt-host.c
diff --git a/src/Makefile.am b/src/Makefile.am
index 0b562dc250..4a8cae11dc 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -167,6 +167,7 @@ DRIVER_SOURCES += \
$(DATATYPES_SOURCES) \
libvirt.c libvirt_internal.h \
libvirt-domain.c \
+ libvirt-domain-checkpoint.c \
libvirt-domain-snapshot.c \
libvirt-host.c \
libvirt-interface.c \
@@ -719,6 +720,7 @@ libvirt_setuid_rpc_client_la_SOURCES = \
datatypes.c \
libvirt.c \
libvirt-domain.c \
+ libvirt-domain-checkpoint.c \
libvirt-domain-snapshot.c \
libvirt-host.c \
libvirt-interface.c \
diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c
new file mode 100644
index 0000000000..ab82d8422b
--- /dev/null
+++ b/src/libvirt-domain-checkpoint.c
@@ -0,0 +1,586 @@
+/*
+ * libvirt-domain-checkpoint.c: entry points for virDomainCheckpointPtr APIs
+ *
+ * Copyright (C) 2006-2019 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ */
+
+#include <config.h>
+
+#include "datatypes.h"
+#include "virlog.h"
+
+VIR_LOG_INIT("libvirt.domain-checkpoint");
+
+#define VIR_FROM_THIS VIR_FROM_DOMAIN_CHECKPOINT
+
+/**
+ * virDomainCheckpointGetName:
+ * @checkpoint: a checkpoint object
+ *
+ * Get the public name for that checkpoint
+ *
+ * Returns a pointer to the name or NULL, the string need not be deallocated
+ * as its lifetime will be the same as the checkpoint object.
+ */
+const char *
+virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint)
+{
+ VIR_DEBUG("checkpoint=%p", checkpoint);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, NULL);
+
+ return checkpoint->name;
+}
+
+
+/**
+ * virDomainCheckpointGetDomain:
+ * @checkpoint: a checkpoint object
+ *
+ * Provides the domain pointer associated with a checkpoint. The
+ * reference counter on the domain is not increased by this
+ * call.
+ *
+ * Returns the domain or NULL.
+ */
+virDomainPtr
+virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint)
+{
+ VIR_DEBUG("checkpoint=%p", checkpoint);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, NULL);
+
+ return checkpoint->domain;
+}
+
+
+/**
+ * virDomainCheckpointGetConnect:
+ * @checkpoint: a checkpoint object
+ *
+ * Provides the connection pointer associated with a checkpoint. The
+ * reference counter on the connection is not increased by this
+ * call.
+ *
+ * Returns the connection or NULL.
+ */
+virConnectPtr
+virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
+{
+ VIR_DEBUG("checkpoint=%p", checkpoint);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, NULL);
+
+ return checkpoint->domain->conn;
+}
+
+
+/**
+ * virDomainCheckpointCreateXML:
+ * @domain: a domain object
+ * @xmlDesc: description of the checkpoint to create
+ * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags
+ *
+ * Create a new checkpoint using @xmlDesc, with a top-level
+ * <domaincheckpoint> element, on a running @domain. Note that @xmlDesc
+ * must validate against the <domaincheckpoint> XML schema.
+ *
+ * See <a href=formatcheckpoint.html#CheckpointAttributes">Checkpoint
XML</a>
+ * for more details on @xmlDesc. In particular, some hypervisors may require
+ * particular disk formats, such as qcow2, in order to support this
+ * command; where @xmlDesc can be used to limit the checkpoint to a working
+ * subset of the domain's disks.
+ *
+ * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, then this
+ * is a request to reinstate checkpoint metadata that was previously
+ * captured from virDomainCheckpointGetXMLDesc() before removing that
+ * metadata, rather than creating a new checkpoint. Note that while
+ * original creation can omit a number of elements from @xmlDesc (and
+ * libvirt will supply sane defaults based on the domain state at that
+ * point in time), a redefinition must supply more elements (as the
+ * domain may have changed in the meantime, so that libvirt no longer
+ * has a way to resupply correct defaults). Not all hypervisors support
+ * this flag.
+ *
+ * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA, then
+ * the domain's disk images are modified according to @xmlDesc, but
+ * libvirt does not track any metadata (similar to immediately calling
+ * virDomainCheckpointDelete() with
+ * VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY). This flag is
+ * incompatible with VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, and is
+ * not supported by all hypervisors.
+ *
+ * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE, then the
+ * libvirt will attempt to use guest agent to freeze and thaw all file
+ * systems in use within domain OS. However, if the guest agent is not
+ * present, an error is thrown. This flag is incompatible with
+ * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE.
+ *
+ * Returns an (opaque) new virDomainCheckpointPtr on success or NULL
+ * on failure.
+ */
+virDomainCheckpointPtr
+virDomainCheckpointCreateXML(virDomainPtr domain,
+ const char *xmlDesc,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+
+ VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=0x%x", xmlDesc, flags);
+
+ virResetLastError();
+
+ virCheckDomainReturn(domain, NULL);
+ conn = domain->conn;
+
+ virCheckNonNullArgGoto(xmlDesc, error);
+ virCheckReadOnlyGoto(conn->flags, error);
+
+ VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE,
+ VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA,
+ error);
+ VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE,
+ VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE,
+ error);
+
+ if (conn->driver->domainCheckpointCreateXML) {
+ virDomainCheckpointPtr ret;
+ ret = conn->driver->domainCheckpointCreateXML(domain, xmlDesc, flags);
+ if (!ret)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return NULL;
+}
+
+
+/**
+ * virDomainCheckpointGetXMLDesc:
+ * @checkpoint: a domain checkpoint object
+ * @flags: bitwise-OR of supported virDomainCheckpointXMLFlags
+ *
+ * Provide an XML description of the domain checkpoint.
+ *
+ * No security-sensitive data will be included unless @flags contains
+ * VIR_DOMAIN_CHECKPOINT_XML_SECURE; this flag is rejected on read-only
+ * connections.
+ *
+ * Normally, the XML description includes an element giving a full
+ * description of the domain at the time the checkpoint was created; to
+ * reduce parsing time, it will be suppressed when @flags contains
+ * VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN.
+ *
+ * By default, the XML description contains only static information that
+ * does not change over time. However, when @flags contains
+ * VIR_DOMAIN_CHECKPOINT_XML_SIZE, each <disk> listing adds an additional
+ * attribute that shows an estimate of the current size in bytes that
+ * have been dirtied between the time the checkpoint was created and the
+ * current point in time.
+ *
+ * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
+ * of error. The caller must free() the returned value.
+ */
+char *
+virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+ VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, NULL);
+ conn = checkpoint->domain->conn;
+
+ if ((conn->flags & VIR_CONNECT_RO) &&
+ (flags & VIR_DOMAIN_CHECKPOINT_XML_SECURE)) {
+ virReportError(VIR_ERR_OPERATION_DENIED, "%s",
+ _("virDomainCheckpointGetXMLDesc with secure flag"));
+ goto error;
+ }
+
+ if (conn->driver->domainCheckpointGetXMLDesc) {
+ char *ret;
+ ret = conn->driver->domainCheckpointGetXMLDesc(checkpoint, flags);
+ if (!ret)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return NULL;
+}
+
+
+/**
+ * virDomainListAllCheckpoints:
+ * @domain: a domain object
+ * @checkpoints: pointer to variable to store the array containing checkpoint
+ * object, or NULL if the list is not required (just returns
+ * number of checkpoints)
+ * @flags: bitwise-OR of supported virDomainCheckpoinListFlags
+ *
+ * Collect the list of domain checkpoints for the given domain and allocate
+ * an array to store those objects.
+ *
+ * If @flags contains VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL,
+ * @checkpoints is non-NULL, and no other connection is modifying
+ * checkpoints, then it is guaranteed that for any checkpoint in the
+ * resulting list, no checkpoints later in the list can be reached by
+ * a sequence of virDomainCheckpointGetParent() starting from that
+ * earlier checkpoint; otherwise, the order of checkpoints in the
+ * resulting list is unspecified.
+ *
+ * By default, this command covers all checkpoints. It is also
+ * possible to limit things to just checkpoints with no parents, when
+ * @flags includes VIR_DOMAIN_CHECKPOINT_LIST_ROOTS. Additional
+ * filters are provided in groups listed below. Within a group, bits
+ * are mutually exclusive, where all possible checkpoints are
+ * described by exactly one bit from the group. Some hypervisors might
+ * reject particular flags where it cannot make a distinction for
+ * filtering. If the set of filter flags selected forms an impossible
+ * combination, the hypervisor may return either 0 or an error.
+ *
+ * The first group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_LEAVES and
+ * VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES, to filter based on checkpoints that
+ * have no further children (a leaf checkpoint).
+ *
+ * The next group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_CURRENT and
+ * VIR_DOMAIN_CHECKPOINT_LIST_NO_CURRENT, to filter based on checkpoints
+ * that are currently being modified by guest activity vs. those that
+ * are no longer tracking changes but instead rely on automatic merging
+ * with child checkpoints when computing changes since the checkpoint.
+ *
+ * Returns the number of domain checkpoints found or -1 and sets @checkpoints
+ * to NULL in case of error. On success, the array stored into @checkpoints
+ * is guaranteed to have an extra allocated element set to NULL but not
+ * included in the return count, to make iteration easier. The caller is
+ * responsible for calling virDomainCheckpointFree() on each array element,
+ * then calling free() on @checkpoints.
+ */
+int
+virDomainListAllCheckpoints(virDomainPtr domain,
+ virDomainCheckpointPtr **checkpoints,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+
+ VIR_DOMAIN_DEBUG(domain, "checkpoints=%p, flags=0x%x", checkpoints,
flags);
+
+ virResetLastError();
+
+ if (checkpoints)
+ *checkpoints = NULL;
+
+ virCheckDomainReturn(domain, -1);
+ conn = domain->conn;
+
+ if (conn->driver->domainListAllCheckpoints) {
+ int ret = conn->driver->domainListAllCheckpoints(domain, checkpoints,
+ flags);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return -1;
+}
+
+
+/**
+ * virDomainCheckpointListAllChildren:
+ * @checkpoint: a domain checkpoint object
+ * @children: pointer to variable to store the array containing checkpoint
+ * objects or NULL if the list is not required (just returns
+ * number of checkpoints)
+ * @flags: bitwise-OR of supported virDomainCheckpointListFlags
+ *
+ * Collect the list of domain checkpoints that are children of the given
+ * checkpoint, and allocate an array to store those objects.
+ *
+ * If @flags contains VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL,
+ * @checkpoints is non-NULL, and no other connection is modifying
+ * checkpoints, then it is guaranteed that for any checkpoint in the
+ * resulting list, no checkpoints later in the list can be reached by
+ * a sequence of virDomainCheckpointGetParent() starting from that
+ * earlier checkpoint; otherwise, the order of checkpoints in the
+ * resulting list is unspecified.
+ *
+ * By default, this command covers only direct children. It is also
+ * possible to expand things to cover all descendants, when @flags
+ * includes VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS. Additional
+ * are provided via the remaining @flags values as documented in
+ * virDomainListAllCheckpoints(), with the exception that
+ * VIR_DOMAIN_CHECKPOINT_LIST_ROOTS is not supported (in fact,
+ * VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS has the same bit value but
+ * opposite semantics of widening rather than narrowing the listing).
+ *
+ * Returns the number of domain checkpoints found or -1 and sets @children to
+ * NULL in case of error. On success, the array stored into @children is
+ * guaranteed to have an extra allocated element set to NULL but not included
+ * in the return count, to make iteration easier. The caller is responsible
+ * for calling virDomainCheckpointFree() on each array element, then calling
+ * free() on @children.
+ */
+int
+virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
+ virDomainCheckpointPtr **children,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+
+ VIR_DEBUG("checkpoint=%p, children=%p, flags=0x%x",
+ checkpoint, children, flags);
+
+ virResetLastError();
+
+ if (children)
+ *children = NULL;
+
+ virCheckDomainCheckpointReturn(checkpoint, -1);
+ conn = checkpoint->domain->conn;
+
+ if (conn->driver->domainCheckpointListAllChildren) {
+ int ret = conn->driver->domainCheckpointListAllChildren(checkpoint,
+ children,
+ flags);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return -1;
+}
+
+
+/**
+ * virDomainCheckpointLookupByName:
+ * @domain: a domain object
+ * @name: name for the domain checkpoint
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Try to lookup a domain checkpoint based on its name.
+ *
+ * Returns a domain checkpoint object or NULL in case of failure. If the
+ * domain checkpoint cannot be found, then the VIR_ERR_NO_DOMAIN_CHECKPOINT
+ * error is raised.
+ */
+virDomainCheckpointPtr
+virDomainCheckpointLookupByName(virDomainPtr domain,
+ const char *name,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+
+ VIR_DOMAIN_DEBUG(domain, "name=%s, flags=0x%x", name, flags);
+
+ virResetLastError();
+
+ virCheckDomainReturn(domain, NULL);
+ conn = domain->conn;
+
+ virCheckNonNullArgGoto(name, error);
+
+ if (conn->driver->domainCheckpointLookupByName) {
+ virDomainCheckpointPtr checkpoint;
+ checkpoint = conn->driver->domainCheckpointLookupByName(domain, name,
+ flags);
+ if (!checkpoint)
+ goto error;
+ return checkpoint;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return NULL;
+}
+
+
+/**
+ * virDomainCheckpointGetParent:
+ * @checkpoint: a checkpoint object
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Get the parent checkpoint for @checkpoint, if any.
+ *
+ * virDomainCheckpointFree should be used to free the resources after the
+ * checkpoint object is no longer needed.
+ *
+ * Returns a domain checkpoint object or NULL in case of failure. If the
+ * given checkpoint is a root (no parent), then the VIR_ERR_NO_DOMAIN_CHECKPOINT
+ * error is raised.
+ */
+virDomainCheckpointPtr
+virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+
+ VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, NULL);
+ conn = checkpoint->domain->conn;
+
+ if (conn->driver->domainCheckpointGetParent) {
+ virDomainCheckpointPtr parent;
+ parent = conn->driver->domainCheckpointGetParent(checkpoint, flags);
+ if (!parent)
+ goto error;
+ return parent;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return NULL;
+}
+
+
+/**
+ * virDomainCheckpointDelete:
+ * @checkpoint: the checkpoint to remove
+ * @flags: bitwise-OR of supported virDomainCheckpointDeleteFlags
+ *
+ * Removes a checkpoint from the domain.
+ *
+ * When removing a checkpoint, the record of which portions of the
+ * disk were dirtied after the checkpoint will be merged into the
+ * record tracked by the parent checkpoint, if any. Likewise, if the
+ * checkpoint being deleted was a current checkpoint, the parent
+ * checkpoint becomes a current checkpoint again.
+ *
+ * If @flags includes VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN, then any
+ * descendant checkpoints are also deleted. If @flags includes
+ * VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY, then any descendant
+ * checkepoints are deleted, but this checkpoint remains. These two
+ * flags are mutually exclusive.
+ *
+ * If @flags includes VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY, then
+ * any checkpoint metadata tracked by libvirt is removed while keeping
+ * the checkpoint contents intact; if a hypervisor does not require
+ * any libvirt metadata to track checkpoints, then this flag is
+ * silently ignored.
+ *
+ * Returns 0 on success, -1 on error.
+ */
+int
+virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+
+ VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, -1);
+ conn = checkpoint->domain->conn;
+
+ virCheckReadOnlyGoto(conn->flags, error);
+
+ VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN,
+ VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY,
+ error);
+
+ if (conn->driver->domainCheckpointDelete) {
+ int ret = conn->driver->domainCheckpointDelete(checkpoint, flags);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return -1;
+}
+
+
+/**
+ * virDomainCheckpointRef:
+ * @checkpoint: the checkpoint to hold a reference on
+ *
+ * Increment the reference count on the checkpoint. For each
+ * additional call to this method, there shall be a corresponding
+ * call to virDomainCheckpointFree to release the reference count, once
+ * the caller no longer needs the reference to this object.
+ *
+ * This method is typically useful for applications where multiple
+ * threads are using a connection, and it is required that the
+ * connection and domain remain open until all threads have finished
+ * using the checkpoint. ie, each new thread using a checkpoint would
+ * increment the reference count.
+ *
+ * Returns 0 in case of success and -1 in case of failure.
+ */
+int
+virDomainCheckpointRef(virDomainCheckpointPtr checkpoint)
+{
+ VIR_DEBUG("checkpoint=%p, refs=%d", checkpoint,
+ checkpoint ? checkpoint->parent.u.s.refs : 0);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, -1);
+
+ virObjectRef(checkpoint);
+ return 0;
+}
+
+
+/**
+ * virDomainCheckpointFree:
+ * @checkpoint: a domain checkpoint object
+ *
+ * Free the domain checkpoint object. The checkpoint itself is not modified.
+ * The data structure is freed and should not be used thereafter.
+ *
+ * Returns 0 in case of success and -1 in case of failure.
+ */
+int
+virDomainCheckpointFree(virDomainCheckpointPtr checkpoint)
+{
+ VIR_DEBUG("checkpoint=%p", checkpoint);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, -1);
+
+ virObjectUnref(checkpoint);
+ return 0;
+}
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 3d12e7c125..2fe9bb8e91 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -6218,8 +6218,9 @@ virDomainDefineXMLFlags(virConnectPtr conn, const char *xml,
unsigned int flags)
*
* If the domain has a managed save image (see
* virDomainHasManagedSaveImage()), or if it is inactive and has any
- * snapshot metadata (see virDomainSnapshotNum()), then the undefine will
- * fail. See virDomainUndefineFlags() for more control.
+ * snapshot metadata (see virDomainSnapshotNum()) or checkpoint
+ * metadata (see virDomainListAllCheckpoints()), then the undefine
+ * will fail. See virDomainUndefineFlags() for more control.
*
* Returns 0 in case of success, -1 in case of error
*/
@@ -6276,6 +6277,16 @@ virDomainUndefine(virDomainPtr domain)
* support snapshots, but where snapshots do not use libvirt metadata,
* this flag has no effect.
*
+ * If the domain is inactive and has any checkpoint metadata (see
+ * virDomainListAllCheckpoints()), then including
+ * VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA in @flags will also remove
+ * that metadata. Omitting the flag will cause the undefine of an
+ * inactive domain with checkpoints to fail. Active domains will
+ * retain checkpoint metadata until the (now-transient) domain halts,
+ * regardless of whether this flag is present. On hypervisors that
+ * support checkpoints, but where checkpoints do not use libvirt
+ * metadata, this flag has no effect.
+ *
* If the domain has any nvram specified, the undefine process will fail
* unless VIR_DOMAIN_UNDEFINE_KEEP_NVRAM is specified, or if
* VIR_DOMAIN_UNDEFINE_NVRAM is specified to remove the nvram file.
@@ -6436,7 +6447,9 @@ virConnectListDefinedDomains(virConnectPtr conn, char **const
names,
* VIR_CONNECT_LIST_DOMAINS_NO_AUTOSTART, for filtering based on autostart;
* VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT and
* VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT, for filtering based on whether
- * a domain has snapshots.
+ * a domain has snapshots; VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT and
+ * VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT, for filtering based on whether
+ * a domain has checkpoints.
*
* Example of usage:
*
diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index 18500ec8b2..54256b6317 100644
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -836,4 +836,20 @@ LIBVIRT_5.5.0 {
virNetworkPortSetParameters;
} LIBVIRT_5.2.0;
+LIBVIRT_5.6.0 {
+ global:
+ virDomainCheckpointCreateXML;
+ virDomainCheckpointDelete;
+ virDomainCheckpointFree;
+ virDomainCheckpointGetConnect;
+ virDomainCheckpointGetDomain;
+ virDomainCheckpointGetName;
+ virDomainCheckpointGetParent;
+ virDomainCheckpointGetXMLDesc;
+ virDomainCheckpointListAllChildren;
+ virDomainCheckpointLookupByName;
+ virDomainCheckpointRef;
+ virDomainListAllCheckpoints;
+} LIBVIRT_5.5.0;
+
# .... define new API here using predicted next version number ....
--
2.20.1
6:23 a.m.
New subject: [libvirt] [PATCH v9 02/13] backup: Introduce virDomainCheckpoint APIs
On Sat, Jul 06, 2019 at 22:56:02 -0500, Eric Blake wrote:
Introduce a bunch of new public APIs related to backup checkpoints.
Checkpoints are modeled heavily after virDomainSnapshotPtr (both
represent a point in time of the guest), although a snapshot exists
with the intent of rolling back to that state, while a checkpoint
exists to make it possible to create an incremental backup at a later
time. We may have a future hypervisor that can completely manage
checkpoints without libvirt metadata, but the first two planned
hypervisors (qemu and test) both always use libvirt for tracking
metadata relations between checkpoints, so for now, I've deferred
the counterpart of virDomainSnapshotHasMetadata for a separate
API addition at a later date if there is ever a need for it.
The following map shows the API relations to snapshots, with new APIs
on the right:
Operate on a domain object to create/redefine a child:
virDomainSnapshotCreateXML virDomainCheckpointCreateXML
Operate on a child object for lifetime management:
virDomainSnapshotDelete virDomainCheckpointDelete
virDomainSnapshotFree virDomainCheckpointFree
virDomainSnapshotRef virDomainCheckpointRef
Operate on a child object to learn more about it:
virDomainSnapshotGetXMLDesc virDomainCheckpointGetXMLDesc
virDomainSnapshotGetConnect virDomainCheckpointGetConnect
virDomainSnapshotGetDomain virDomainCheckpointGetDomain
virDomainSnapshotGetName virDomainCheckpiontGetName
virDomainSnapshotGetParent virDomainCheckpiontGetParent
virDomainSnapshotHasMetadata (deferred for later)
virDomainSnapshotIsCurrent (no counterpart, present in XML instead)
Operate on a domain object to list all children:
virDomainSnapshotNum (no counterparts, these are the old
virDomainSnapshotListNames racy interfaces)
virDomainSnapshotListAllSnapshots virDomainListAllCheckpoints
Operate on a child object to list descendents:
virDomainSnapshotNumChildren (no counterparts, these are the old
virDomainSnapshotListChildrenNames racy interfaces)
virDomainSnapshotListAllChildren virDomainCheckpointListAllChildren
Operate on a domain to locate a particular child:
virDomainSnapshotLookupByName virDomainCheckpointLookupByName
virDomainSnapshotCurrent (obtained by flag to ListAllCheckpoints)
virDomainHasCurrentSnapshot (no counterpart, old racy interface)
Operate on a snapshot to roll back to earlier state:
virDomainSnapshotRevert (no counterpart, instead checkpoints
are used in incremental backups via
XML to virDomainBackupBegin)
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
include/libvirt/libvirt-domain-checkpoint.h | 143 +++++
include/libvirt/libvirt-domain.h | 6 +
include/libvirt/libvirt.h | 5 +-
src/conf/virdomainmomentobjlist.h | 5 +-
src/driver-hypervisor.h | 38 ++
docs/Makefile.am | 3 +
docs/apibuild.py | 2 +
docs/docs.html.in | 1 +
libvirt.spec.in | 1 +
mingw-libvirt.spec.in | 2 +
po/POTFILES | 1 +
src/Makefile.am | 2 +
src/libvirt-domain-checkpoint.c | 586 ++++++++++++++++++++
src/libvirt-domain.c | 19 +-
src/libvirt_public.syms | 16 +
15 files changed, 821 insertions(+), 9 deletions(-)
create mode 100644 include/libvirt/libvirt-domain-checkpoint.h
create mode 100644 src/libvirt-domain-checkpoint.c
diff --git a/include/libvirt/libvirt-domain-checkpoint.h
b/include/libvirt/libvirt-domain-checkpoint.h
new file mode 100644
index 0000000000..b2d5c5758b
--- /dev/null
+++ b/include/libvirt/libvirt-domain-checkpoint.h
@@ -0,0 +1,143 @@
[...]
+typedef enum {
+ VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE = (1 << 0), /* Restore or alter
+ metadata */
+ VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA = (1 << 1), /* Make checkpoint
without
+ remembering it */
[1]
+ VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE = (1 << 2), /*
use guest agent to
+ quiesce all mounted
+ file systems within
+ the domain */
+} virDomainCheckpointCreateFlags;
[...]
diff --git a/src/libvirt-domain-checkpoint.c
b/src/libvirt-domain-checkpoint.c
new file mode 100644
index 0000000000..ab82d8422b
--- /dev/null
+++ b/src/libvirt-domain-checkpoint.c
@@ -0,0 +1,586 @@
[...]
+/**
+ * virDomainCheckpointCreateXML:
+ * @domain: a domain object
+ * @xmlDesc: description of the checkpoint to create
+ * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags
+ *
+ * Create a new checkpoint using @xmlDesc, with a top-level
+ * <domaincheckpoint> element, on a running @domain. Note that @xmlDesc
+ * must validate against the <domaincheckpoint> XML schema.
+ *
+ * See <a href=formatcheckpoint.html#CheckpointAttributes">Checkpoint
XML</a>
+ * for more details on @xmlDesc. In particular, some hypervisors may require
+ * particular disk formats, such as qcow2, in order to support this
+ * command; where @xmlDesc can be used to limit the checkpoint to a working
+ * subset of the domain's disks.
+ *
+ * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, then this
+ * is a request to reinstate checkpoint metadata that was previously
+ * captured from virDomainCheckpointGetXMLDesc() before removing that
+ * metadata, rather than creating a new checkpoint. Note that while
+ * original creation can omit a number of elements from @xmlDesc (and
+ * libvirt will supply sane defaults based on the domain state at that
+ * point in time), a redefinition must supply more elements (as the
+ * domain may have changed in the meantime, so that libvirt no longer
+ * has a way to resupply correct defaults). Not all hypervisors support
+ * this flag.
+ *
+ * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA, then
+ * the domain's disk images are modified according to @xmlDesc, but
+ * libvirt does not track any metadata (similar to immediately calling
+ * virDomainCheckpointDelete() with
[1]
+ * VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY). This flag is
+ * incompatible with VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, and is
+ * not supported by all hypervisors.
+ *
+ * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE, then the
+ * libvirt will attempt to use guest agent to freeze and thaw all file
+ * systems in use within domain OS. However, if the guest agent is not
+ * present, an error is thrown. This flag is incompatible with
+ * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE.
+ *
+ * Returns an (opaque) new virDomainCheckpointPtr on success or NULL
+ * on failure.
+ */
+virDomainCheckpointPtr
+virDomainCheckpointCreateXML(virDomainPtr domain,
+ const char *xmlDesc,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+
+ VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=0x%x", xmlDesc, flags);
+
+ virResetLastError();
+
+ virCheckDomainReturn(domain, NULL);
+ conn = domain->conn;
+
+ virCheckNonNullArgGoto(xmlDesc, error);
+ virCheckReadOnlyGoto(conn->flags, error);
+
+ VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE,
+ VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA,
+ error);
+ VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE,
+ VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE,
+ error);
+
+ if (conn->driver->domainCheckpointCreateXML) {
+ virDomainCheckpointPtr ret;
+ ret = conn->driver->domainCheckpointCreateXML(domain, xmlDesc, flags);
+ if (!ret)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return NULL;
+}
[...]
ACK if and only if you remove the [1] 'NO_METADATA' checkpoint creation
flag and everything related to it.
Obviously there may be some fallout from "current".
10:38 a.m.
New subject: [libvirt] [PATCH v9 02/13] backup: Introduce virDomainCheckpoint APIs
On 7/6/19 11:56 PM, Eric Blake wrote:
Introduce a bunch of new public APIs related to backup checkpoints.
Checkpoints are modeled heavily after virDomainSnapshotPtr (both
represent a point in time of the guest), although a snapshot exists
with the intent of rolling back to that state, while a checkpoint
exists to make it possible to create an incremental backup at a later
time. We may have a future hypervisor that can completely manage
checkpoints without libvirt metadata, but the first two planned
hypervisors (qemu and test) both always use libvirt for tracking
metadata relations between checkpoints, so for now, I've deferred
the counterpart of virDomainSnapshotHasMetadata for a separate
API addition at a later date if there is ever a need for it.
...
+/**
+ * virDomainCheckpointCreateXML:
+ * @domain: a domain object
+ * @xmlDesc: description of the checkpoint to create
+ * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags
+ *
+ * Create a new checkpoint using @xmlDesc, with a top-level
+ * <domaincheckpoint> element, on a running @domain. Note that @xmlDesc
+ * must validate against the <domaincheckpoint> XML schema.
+ *
+ * See <a href=formatcheckpoint.html#CheckpointAttributes">Checkpoint
XML</a>
Missing a " after href=
- Cole
10:56 p.m.
New subject: [libvirt] [PATCH v9 03/13] backup: Document nuances between different state capture APIs
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(a)redhat.com>
Reviewed-by: John Ferlan <jferlan(a)redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
docs/docs.html.in | 5 +
docs/domainstatecapture.html.in | 314 ++++++++++++++++++++++++++++++++
docs/formatcheckpoint.html.in | 4 +-
docs/formatsnapshot.html.in | 2 +
4 files changed, 324 insertions(+), 1 deletion(-)
create mode 100644 docs/domainstatecapture.html.in
diff --git a/docs/docs.html.in b/docs/docs.html.in
index 2d44e3ab2e..a00b131466 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -124,6 +124,11 @@
<dt><a href="secureusage.html">Secure
usage</a></dt>
<dd>Secure usage of the libvirt APIs</dd>
+
+ <dt><a href="domainstatecapture.html">Domain state
+ capture</a></dt>
+ <dd>Comparison between different methods of capturing domain
+ state</dd>
</dl>
</div>
diff --git a/docs/domainstatecapture.html.in b/docs/domainstatecapture.html.in
new file mode 100644
index 0000000000..4f109180da
--- /dev/null
+++ b/docs/domainstatecapture.html.in
@@ -0,0 +1,314 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <body>
+
+ <h1>Domain state capture using Libvirt</h1>
+
+ <ul id="toc"></ul>
+
+ <p>
+ In order to aid application developers to choose which
+ operations best suit their needs, this page compares the
+ different means for capturing state related to a domain managed
+ by libvirt.
+ </p>
+
+ <p>
+ The information here is primarily geared towards capturing the
+ state of an active domain. Capturing the state of an inactive
+ domain essentially amounts to copying the contents of guest
+ disks, followed by a fresh boot with disks restored to that
+ state.
+ </p>
+
+ <h2><a id="definitions">State capture
trade-offs</a></h2>
+
+ <p>One of the features made possible with virtual machines is live
+ migration -- transferring all state related to the guest from
+ one host to another with minimal interruption to the guest's
+ activity. In this case, state includes domain memory (including
+ register and device contents), and domain storage (whether the
+ guest's view of the disks are backed by local storage on the
+ host, or by the hypervisor accessing shared storage over a
+ network). A clever observer will then note that if all state is
+ available for live migration, then there is nothing stopping a
+ user from saving some or all of that state at a given point of
+ time in order to be able to later rewind guest execution back to
+ the state it previously had. The astute reader will also realize
+ that state capture at any level requires that the data must be
+ stored and managed by some mechanism. This processing might fit
+ in a single file, or more likely require a chain of related
+ files, and may require synchronization with third-party tools
+ built around managing the amount of data resulting from
+ capturing the state of multiple guests that each use multiple
+ disks.
+ </p>
+
+ <p>
+ There are several libvirt APIs associated with capturing the
+ state of a guest, which can later be used to rewind that guest
+ to the conditions it was in earlier. The following is a list of
+ trade-offs and differences between the various facets that
+ affect capturing domain state for active domains:
+ </p>
+
+ <dl>
+ <dt>Duration</dt>
+ <dd>Capturing state can be a lengthy process, so while the
+ captured state ideally represents an atomic point in time
+ corresponding to something the guest was actually executing,
+ capturing state tends to focus on minimizing guest downtime
+ while performing the rest of the state capture in parallel
+ with guest execution. Some interfaces require up-front
+ preparation (the state captured is not complete until the API
+ ends, which may be some time after the command was first
+ started), while other interfaces track the state when the
+ command was first issued, regardless of the time spent in
+ capturing the rest of the state. Also, time spent in state
+ capture may be longer than the time required for live
+ migration, when state must be duplicated rather than shared.
+ </dd>
+
+ <dt>Amount of state</dt>
+ <dd>For an online guest, there is a choice between capturing the
+ guest's memory (all that is needed during live migration when
+ the storage is already shared between source and destination),
+ the guest's disk state (all that is needed if there are no
+ pending guest I/O transactions that would be lost without the
+ corresponding memory state), or both together. Reverting to
+ partial state may still be viable, but typically, booting from
+ captured disk state without corresponding memory is comparable
+ to rebooting a machine that had power cut before I/O could be
+ flushed. Guests may need to use proper journaling methods to
+ avoid problems when booting from partial state.
+ </dd>
+
+ <dt>Quiescing of data</dt>
+ <dd>Even if a guest has no pending I/O, capturing disk state may
+ catch the guest at a time when the contents of the disk are
+ inconsistent. Cooperating with the guest to perform data
+ quiescing is an optional step to ensure that captured disk
+ state is fully consistent without requiring additional memory
+ state, rather than just crash-consistent. But guest
+ cooperation may also have time constraints, where the guest
+ can rightfully panic if there is too much downtime while I/O
+ is frozen.
+ </dd>
+
+ <dt>Quantity of files</dt>
+ <dd>When capturing state, some approaches store all state within
+ the same file (internal), while others expand a chain of
+ related files that must be used together (external), for more
+ files that a management application must track.
+ </dd>
+
+ <dt>Impact to guest definition</dt>
+ <dd>Capturing state may require temporary changes to the guest
+ definition, such as associating new files into the domain
+ definition. While state capture should never impact the
+ running guest, a change to the domain's active XML may have
+ impact on other host operations being performed on the domain.
+ </dd>
+
+ <dt>Third-party integration</dt>
+ <dd>When capturing state, there are tradeoffs to how much of the
+ process must be done directly by the hypervisor, and how much
+ can be off-loaded to third-party software. Since capturing
+ state is not instantaneous, it is essential that any
+ third-party integration see consistent data even if the
+ running guest continues to modify that data after the point in
+ time of the capture.</dd>
+
+ <dt>Full vs. incremental</dt>
+ <dd>When periodically repeating the action of state capture, it
+ is useful to minimize the amount of state that must be
+ captured by exploiting the relation to a previous capture,
+ such as focusing only on the portions of the disk that the
+ guest has modified in the meantime. Some approaches are able
+ to take advantage of checkpoints to provide an incremental
+ backup, while others are only capable of a full backup even if
+ that means re-capturing unchanged portions of the disk.</dd>
+
+ <dt>Local vs. remote</dt>
+ <dd>Domains that completely use remote storage may only need
+ some mechanism to keep track of guest memory state while using
+ external means to manage storage. Still, hypervisor and guest
+ cooperation to ensure points in time when no I/O is in flight
+ across the network can be important for properly capturing
+ disk state.</dd>
+
+ <dt>Network latency</dt>
+ <dd>Whether it's domain storage or saving domain state into
+ remote storage, network latency has an impact on snapshot
+ data. Having dedicated network capacity, bandwidth, or quality
+ of service levels may play a role, as well as planning for how
+ much of the backup process needs to be local.</dd>
+ </dl>
+
+ <p>
+ An example of the various facets in action is migration of a
+ running guest. In order for the guest to be able to resume on
+ the destination at the same place it left off at the source, the
+ hypervisor has to get to a point where execution on the source
+ is stopped, the last remaining changes occurring since the
+ migration started are then transferred, and the guest is started
+ on the target. The management software thus must keep track of
+ the starting point and any changes since the starting
+ point. These last changes are often referred to as dirty page
+ tracking or dirty disk block bitmaps. At some point in time
+ during the migration, the management software must freeze the
+ source guest, transfer the dirty data, and then start the guest
+ on the target. This period of time must be minimal. To minimize
+ overall migration time, one is advised to use a dedicated
+ network connection with a high quality of service. Alternatively
+ saving the current state of the running guest can just be a
+ point in time type operation which doesn't require updating the
+ "last vestiges" of state prior to writing out the saved state
+ file. The state file is the point in time of whatever is current
+ and may contain incomplete data which if used to restart the
+ guest could cause confusion or problems because some operation
+ wasn't completed depending upon where in time the operation was
+ commenced.
+ </p>
+
+ <h2><a id="apis">State capture APIs</a></h2>
+ <p>With those definitions, the following libvirt APIs related to
+ state capture have these properties:</p>
+ <dl>
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainManagedSave"><code>virDomainManagedSave</code></a></dt>
+ <dd>This API saves guest memory, with libvirt managing all of
+ the saved state, then stops the guest. While stopped, the
+ disks can be copied by a third party. However, since any
+ subsequent restart of the guest by libvirt API will restore
+ the memory state (which typically only works if the disk state
+ is unchanged in the meantime), and since it is not possible to
+ get at the memory state that libvirt is managing, this is not
+ viable as a means for rolling back to earlier saved states,
+ but is rather more suited to situations such as suspending a
+ guest prior to rebooting the host in order to resume the guest
+ when the host is back up. This API also has a drawback of
+ potentially long guest downtime, and therefore does not lend
+ itself well to live backups.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainSave"><code>virDomainSave</code></a></dt>
+ <dd>This API is similar to virDomainManagedSave(), but moves the
+ burden on managing the stored memory state to the user. As
+ such, the user can now couple saved state with copies of the
+ disks to perform a revert to an arbitrary earlier saved state.
+ However, changing who manages the memory state does not change
+ the drawback of potentially long guest downtime when capturing
+ state.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain-snapshot.html#virDomainSnapshotCreateXML"><code>virDomainSnapshotCreateXML</code></a></dt>
+ <dd>This API wraps several approaches for capturing guest state,
+ with a general premise of creating a snapshot (where the
+ current guest resources are frozen in time and a new wrapper
+ layer is opened for tracking subsequent guest changes). It
+ can operate on both offline and running guests, can choose
+ whether to capture the state of memory, disk, or both when
+ used on a running guest, and can choose between internal and
+ external storage for captured state. However, it is geared
+ towards post-event captures (when capturing both memory and
+ disk state, the disk state is not captured until all memory
+ state has been collected first). Using QEMU as the
+ hypervisor, internal snapshots currently have lengthy downtime
+ that is incompatible with freezing guest I/O, but external
+ snapshots are quick. Since creating an external snapshot
+ changes which disk image resource is in use by the guest, this
+ API can be coupled with <a
href="html/libvirt-libvirt-domain.html#virDomainBlockCommit"><code>virDomainBlockCommit()</code></a>
to
+ restore things back to the guest using its original disk
+ image, where a third-party tool can read the backing file
+ prior to the live commit. See also
+ the <a href="formatsnapshot.html">XML details</a> used
with
+ this command.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainFSFreeze"><code>virDomainFSFreeze</code></a>,
<a
href="html/libvirt-libvit-domain.html#virDomainFSThaw"><code>virDomainFSThaw</code></a></dt>
+ <dd>This pair of APIs does not directly capture guest state, but
+ can be used to coordinate with a trusted live guest that state
+ capture is about to happen, and therefore guest I/O should be
+ quiesced so that the state capture is fully consistent, rather
+ than merely crash consistent. Some APIs are able to
+ automatically perform a freeze and thaw via a flags parameter,
+ rather than having to make separate calls to these
+ functions. Also, note that freezing guest I/O is only possible
+ with trusted guests running a guest agent, and that some
+ guests place maximum time limits on how long I/O can be
+ frozen.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainBlockCopy"><code>virDomainBlockCopy</code></a></dt>
+ <dd>This API wraps approaches for capturing the disk state of a
+ running guest, but does not track accompanying guest memory
+ state, and can only operate on one block device per job. To
+ get a consistent copy of multiple disks, multiple jobs must be
+ run in parallel, then the domain must be paused before ending
+ all of the jobs. The capture is consistent only at the end of
+ the operation with a choice for future guest changes to either
+ pivot to the new file or to resume to just using the original
+ file. The resulting backup file is thus the other file no
+ longer in use by the guest.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain-checkpoint.html#virDomainCheckpointCreateXML"><code>virDomainCheckpointCreateXML</code></a></dt>
+ <dd>This API does not actually capture guest state, rather it
+ makes it possible to track which portions of guest disks have
+ changed between a checkpoint and the current live execution of
+ the guest. However, while it is possible use this API to
+ create checkpoints in isolation, it is more typical to create
+ a checkpoint as a side-effect of starting a new incremental
+ backup with <code>virDomainBackupBegin()</code> or at the
+ creation of an external snapshot
+ with <code>virDomainSnapshotCreateXML2()</code>, since a
+ second incremental backup is most useful when using the
+ checkpoint created during the first. See also
+ the <a href="formatcheckpoint.html">XML details</a> used
with
+ this command.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainBackupBegin"><code>virDomainBackupBegin</code></a>,
<a
href="html/libvirt-libvit-domain.html#virDomainBackupEnd"><code>virDomainBackupEnd</code></a></dt>
+ <dd>This API wraps approaches for capturing the state of disks
+ of a running guest, but does not track accompanying guest
+ memory state. The capture is consistent to the start of the
+ operation, where the captured state is stored independently
+ from the disk image in use with the guest and where it can be
+ easily integrated with a third-party for capturing the disk
+ state. Since the backup operation is stored externally from
+ the guest resources, there is no need to commit data back in
+ at the completion of the operation. When coupled with
+ checkpoints, this can be used to capture incremental backups
+ instead of full.</dd>
+ </dl>
+
+ <h2><a id="examples">Examples</a></h2>
+ <p>The following two sequences both accomplish the task of
+ capturing the disk state of a running guest, then wrapping
+ things up so that the guest is still running with the same file
+ as its disk image as before the sequence of operations began.
+ The difference between the two sequences boils down to the
+ impact of an unexpected interruption made at any point in the
+ middle of the sequence: with such an interruption, the first
+ example leaves the guest tied to a temporary wrapper file rather
+ than the original disk, and requires manual clean up of the
+ domain definition; while the second example has no impact to the
+ domain definition.</p>
+
+ <p>1. Backup via temporary snapshot
+ <pre>
+virDomainFSFreeze()
+virDomainSnapshotCreateXML(VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY)
+virDomainFSThaw()
+third-party copy the backing file to backup storage # most time spent here
+virDomainBlockCommit(VIR_DOMAIN_BLOCK_COMMIT_ACTIVE) per disk
+wait for commit ready event per disk
+virDomainBlockJobAbort() per disk
+ </pre></p>
+
+ <p>2. Direct backup
+ <pre>
+virDomainFSFreeze()
+virDomainBackupBegin()
+virDomainFSThaw()
+wait for push mode event, or pull data over NBD # most time spent here
+virDomainBackupEnd()
+ </pre></p>
+
+ </body>
+</html>
diff --git a/docs/formatcheckpoint.html.in b/docs/formatcheckpoint.html.in
index ef5f8a826b..030f0d6af0 100644
--- a/docs/formatcheckpoint.html.in
+++ b/docs/formatcheckpoint.html.in
@@ -13,7 +13,9 @@
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.
+ backups requires different libvirt APIs
+ (see <a href="domainstatecapture.html">domain state
capture</a>
+ for a comparison between APIs).
</p>
<p>
Libvirt is able to facilitate incremental backups by tracking
diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in
index 2bfb69cf49..ee9aa7817f 100644
--- a/docs/formatsnapshot.html.in
+++ b/docs/formatsnapshot.html.in
@@ -9,6 +9,8 @@
<h2><a id="SnapshotAttributes">Snapshot
XML</a></h2>
<p>
+ Snapshots are one form
+ of <a href="domainstatecapture.html">domain state
capture</a>.
There are several types of snapshots:
</p>
<dl>
--
2.20.1
6:23 a.m.
New subject: [libvirt] [PATCH v9 03/13] backup: Document nuances between different state capture APIs
On Sat, Jul 06, 2019 at 22:56:03 -0500, Eric Blake wrote:
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(a)redhat.com>
Reviewed-by: John Ferlan <jferlan(a)redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
docs/docs.html.in | 5 +
docs/domainstatecapture.html.in | 314 ++++++++++++++++++++++++++++++++
docs/formatcheckpoint.html.in | 4 +-
docs/formatsnapshot.html.in | 2 +
4 files changed, 324 insertions(+), 1 deletion(-)
create mode 100644 docs/domainstatecapture.html.in
[...]
diff --git a/docs/domainstatecapture.html.in
b/docs/domainstatecapture.html.in
new file mode 100644
index 0000000000..4f109180da
--- /dev/null
+++ b/docs/domainstatecapture.html.in
@@ -0,0 +1,314 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <body>
+
+ <h1>Domain state capture using Libvirt</h1>
+
+ <ul id="toc"></ul>
+
+ <p>
+ In order to aid application developers to choose which
+ operations best suit their needs, this page compares the
+ different means for capturing state related to a domain managed
+ by libvirt.
+ </p>
+
+ <p>
+ The information here is primarily geared towards capturing the
+ state of an active domain. Capturing the state of an inactive
+ domain essentially amounts to copying the contents of guest
+ disks, followed by a fresh boot with disks restored to that
+ state.
Also the config may be relevant.
+ </p>
+
+ <h2><a id="definitions">State capture
trade-offs</a></h2>
+
+ <p>One of the features made possible with virtual machines is live
+ migration -- transferring all state related to the guest from
+ one host to another with minimal interruption to the guest's
+ activity. In this case, state includes domain memory (including
+ register and device contents), and domain storage (whether the
+ guest's view of the disks are backed by local storage on the
+ host, or by the hypervisor accessing shared storage over a
+ network). A clever observer will then note that if all state is
+ available for live migration, then there is nothing stopping a
+ user from saving some or all of that state at a given point of
+ time in order to be able to later rewind guest execution back to
+ the state it previously had. The astute reader will also realize
+ that state capture at any level requires that the data must be
+ stored and managed by some mechanism. This processing might fit
+ in a single file, or more likely require a chain of related
+ files, and may require synchronization with third-party tools
+ built around managing the amount of data resulting from
+ capturing the state of multiple guests that each use multiple
+ disks.
+ </p>
+
+ <p>
+ There are several libvirt APIs associated with capturing the
+ state of a guest, which can later be used to rewind that guest
+ to the conditions it was in earlier. The following is a list of
+ trade-offs and differences between the various facets that
+ affect capturing domain state for active domains:
+ </p>
+
+ <dl>
+ <dt>Duration</dt>
+ <dd>Capturing state can be a lengthy process, so while the
+ captured state ideally represents an atomic point in time
+ corresponding to something the guest was actually executing,
+ capturing state tends to focus on minimizing guest downtime
+ while performing the rest of the state capture in parallel
+ with guest execution. Some interfaces require up-front
+ preparation (the state captured is not complete until the API
+ ends, which may be some time after the command was first
+ started), while other interfaces track the state when the
+ command was first issued, regardless of the time spent in
+ capturing the rest of the state. Also, time spent in state
+ capture may be longer than the time required for live
+ migration, when state must be duplicated rather than shared.
+ </dd>
+
+ <dt>Amount of state</dt>
+ <dd>For an online guest, there is a choice between capturing the
+ guest's memory (all that is needed during live migration when
+ the storage is already shared between source and destination),
+ the guest's disk state (all that is needed if there are no
+ pending guest I/O transactions that would be lost without the
+ corresponding memory state), or both together. Reverting to
+ partial state may still be viable, but typically, booting from
+ captured disk state without corresponding memory is comparable
+ to rebooting a machine that had power cut before I/O could be
+ flushed. Guests may need to use proper journaling methods to
+ avoid problems when booting from partial state.
+ </dd>
+
+ <dt>Quiescing of data</dt>
+ <dd>Even if a guest has no pending I/O, capturing disk state may
+ catch the guest at a time when the contents of the disk are
+ inconsistent. Cooperating with the guest to perform data
+ quiescing is an optional step to ensure that captured disk
+ state is fully consistent without requiring additional memory
+ state, rather than just crash-consistent. But guest
+ cooperation may also have time constraints, where the guest
+ can rightfully panic if there is too much downtime while I/O
+ is frozen.
+ </dd>
+
+ <dt>Quantity of files</dt>
+ <dd>When capturing state, some approaches store all state within
+ the same file (internal), while others expand a chain of
+ related files that must be used together (external), for more
+ files that a management application must track.
+ </dd>
+
+ <dt>Impact to guest definition</dt>
+ <dd>Capturing state may require temporary changes to the guest
+ definition, such as associating new files into the domain
+ definition. While state capture should never impact the
+ running guest, a change to the domain's active XML may have
+ impact on other host operations being performed on the domain.
+ </dd>
+
+ <dt>Third-party integration</dt>
+ <dd>When capturing state, there are tradeoffs to how much of the
+ process must be done directly by the hypervisor, and how much
+ can be off-loaded to third-party software. Since capturing
+ state is not instantaneous, it is essential that any
+ third-party integration see consistent data even if the
+ running guest continues to modify that data after the point in
+ time of the capture.</dd>
+
+ <dt>Full vs. incremental</dt>
+ <dd>When periodically repeating the action of state capture, it
+ is useful to minimize the amount of state that must be
+ captured by exploiting the relation to a previous capture,
+ such as focusing only on the portions of the disk that the
+ guest has modified in the meantime. Some approaches are able
+ to take advantage of checkpoints to provide an incremental
+ backup, while others are only capable of a full backup even if
+ that means re-capturing unchanged portions of the disk.</dd>
+
+ <dt>Local vs. remote</dt>
+ <dd>Domains that completely use remote storage may only need
+ some mechanism to keep track of guest memory state while using
+ external means to manage storage. Still, hypervisor and guest
+ cooperation to ensure points in time when no I/O is in flight
+ across the network can be important for properly capturing
+ disk state.</dd>
+
+ <dt>Network latency</dt>
+ <dd>Whether it's domain storage or saving domain state into
+ remote storage, network latency has an impact on snapshot
+ data. Having dedicated network capacity, bandwidth, or quality
+ of service levels may play a role, as well as planning for how
+ much of the backup process needs to be local.</dd>
+ </dl>
+
+ <p>
+ An example of the various facets in action is migration of a
+ running guest. In order for the guest to be able to resume on
+ the destination at the same place it left off at the source, the
+ hypervisor has to get to a point where execution on the source
+ is stopped, the last remaining changes occurring since the
+ migration started are then transferred, and the guest is started
+ on the target. The management software thus must keep track of
+ the starting point and any changes since the starting
+ point. These last changes are often referred to as dirty page
+ tracking or dirty disk block bitmaps. At some point in time
+ during the migration, the management software must freeze the
+ source guest, transfer the dirty data, and then start the guest
+ on the target. This period of time must be minimal. To minimize
+ overall migration time, one is advised to use a dedicated
+ network connection with a high quality of service. Alternatively
+ saving the current state of the running guest can just be a
+ point in time type operation which doesn't require updating the
+ "last vestiges" of state prior to writing out the saved state
+ file. The state file is the point in time of whatever is current
+ and may contain incomplete data which if used to restart the
+ guest could cause confusion or problems because some operation
+ wasn't completed depending upon where in time the operation was
+ commenced.
+ </p>
+
+ <h2><a id="apis">State capture APIs</a></h2>
+ <p>With those definitions, the following libvirt APIs related to
+ state capture have these properties:</p>
+ <dl>
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainManagedSave"><code>virDomainManagedSave</code></a></dt>
+ <dd>This API saves guest memory, with libvirt managing all of
+ the saved state, then stops the guest. While stopped, the
+ disks can be copied by a third party. However, since any
+ subsequent restart of the guest by libvirt API will restore
+ the memory state (which typically only works if the disk state
+ is unchanged in the meantime), and since it is not possible to
+ get at the memory state that libvirt is managing, this is not
+ viable as a means for rolling back to earlier saved states,
+ but is rather more suited to situations such as suspending a
+ guest prior to rebooting the host in order to resume the guest
+ when the host is back up. This API also has a drawback of
+ potentially long guest downtime, and therefore does not lend
+ itself well to live backups.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainSave"><code>virDomainSave</code></a></dt>
+ <dd>This API is similar to virDomainManagedSave(), but moves the
+ burden on managing the stored memory state to the user. As
+ such, the user can now couple saved state with copies of the
+ disks to perform a revert to an arbitrary earlier saved state.
+ However, changing who manages the memory state does not change
+ the drawback of potentially long guest downtime when capturing
+ state.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain-snapshot.html#virDomainSnapshotCreateXML"><code>virDomainSnapshotCreateXML</code></a></dt>
+ <dd>This API wraps several approaches for capturing guest state,
+ with a general premise of creating a snapshot (where the
+ current guest resources are frozen in time and a new wrapper
+ layer is opened for tracking subsequent guest changes). It
+ can operate on both offline and running guests, can choose
+ whether to capture the state of memory, disk, or both when
+ used on a running guest, and can choose between internal and
+ external storage for captured state. However, it is geared
+ towards post-event captures (when capturing both memory and
+ disk state, the disk state is not captured until all memory
+ state has been collected first). Using QEMU as the
+ hypervisor, internal snapshots currently have lengthy downtime
+ that is incompatible with freezing guest I/O, but external
+ snapshots are quick. Since creating an external snapshot
This only applies for external snapshots without memory! Including
memory involves a migration with a potentially lenghty downtime.
+ changes which disk image resource is in use by the guest,
this
+ API can be coupled with <a
href="html/libvirt-libvirt-domain.html#virDomainBlockCommit"><code>virDomainBlockCommit()</code></a>
to
+ restore things back to the guest using its original disk
+ image, where a third-party tool can read the backing file
+ prior to the live commit. See also
+ the <a href="formatsnapshot.html">XML details</a> used
with
+ this command.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainFSFreeze"><code>virDomainFSFreeze</code></a>,
<a
href="html/libvirt-libvit-domain.html#virDomainFSThaw"><code>virDomainFSThaw</code></a></dt>
+ <dd>This pair of APIs does not directly capture guest state, but
+ can be used to coordinate with a trusted live guest that state
+ capture is about to happen, and therefore guest I/O should be
+ quiesced so that the state capture is fully consistent, rather
+ than merely crash consistent. Some APIs are able to
+ automatically perform a freeze and thaw via a flags parameter,
+ rather than having to make separate calls to these
+ functions. Also, note that freezing guest I/O is only possible
+ with trusted guests running a guest agent, and that some
+ guests place maximum time limits on how long I/O can be
+ frozen.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainBlockCopy"><code>virDomainBlockCopy</code></a></dt>
+ <dd>This API wraps approaches for capturing the disk state of a
+ running guest, but does not track accompanying guest memory
+ state, and can only operate on one block device per job. To
+ get a consistent copy of multiple disks, multiple jobs must be
+ run in parallel, then the domain must be paused before ending
+ all of the jobs. The capture is consistent only at the end of
+ the operation with a choice for future guest changes to either
+ pivot to the new file or to resume to just using the original
+ file. The resulting backup file is thus the other file no
+ longer in use by the guest.</dd>
I already said that the abuse of block copy should not be documented at
all here.
+
+ <dt><a
href="html/libvirt-libvit-domain-checkpoint.html#virDomainCheckpointCreateXML"><code>virDomainCheckpointCreateXML</code></a></dt>
+ <dd>This API does not actually capture guest state, rather it
+ makes it possible to track which portions of guest disks have
+ changed between a checkpoint and the current live execution of
+ the guest. However, while it is possible use this API to
+ create checkpoints in isolation, it is more typical to create
+ a checkpoint as a side-effect of starting a new incremental
+ backup with <code>virDomainBackupBegin()</code> or at the
+ creation of an external snapshot
+ with <code>virDomainSnapshotCreateXML2()</code>, since a
+ second incremental backup is most useful when using the
+ checkpoint created during the first. See also
+ the <a href="formatcheckpoint.html">XML details</a> used
with
+ this command.</dd>
+
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainBackupBegin"><code>virDomainBackupBegin</code></a>,
<a
href="html/libvirt-libvit-domain.html#virDomainBackupEnd"><code>virDomainBackupEnd</code></a></dt>
+ <dd>This API wraps approaches for capturing the state of disks
+ of a running guest, but does not track accompanying guest
+ memory state. The capture is consistent to the start of the
+ operation, where the captured state is stored independently
+ from the disk image in use with the guest and where it can be
+ easily integrated with a third-party for capturing the disk
+ state. Since the backup operation is stored externally from
+ the guest resources, there is no need to commit data back in
+ at the completion of the operation. When coupled with
+ checkpoints, this can be used to capture incremental backups
+ instead of full.</dd>
[...]
All in all my only complaint is that this reads as an informercial for
backups rather than a summarization of all the approaches.
ACK if and only if you remove the documentation of blockCopy abuse.
10:38 a.m.
New subject: [libvirt] [PATCH v9 03/13] backup: Document nuances between different state capture APIs
On 7/6/19 11:56 PM, Eric Blake wrote:
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(a)redhat.com>
Reviewed-by: John Ferlan <jferlan(a)redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
docs/docs.html.in | 5 +
docs/domainstatecapture.html.in | 314 ++++++++++++++++++++++++++++++++
docs/formatcheckpoint.html.in | 4 +-
docs/formatsnapshot.html.in | 2 +
4 files changed, 324 insertions(+), 1 deletion(-)
create mode 100644 docs/domainstatecapture.html.in
diff --git a/docs/domainstatecapture.html.in b/docs/domainstatecapture.html.in
+ <h2><a id="apis">State capture
APIs</a></h2>
+ <p>With those definitions, the following libvirt APIs related to
+ state capture have these properties:</p>
+ <dl>
+ <dt><a
href="html/libvirt-libvit-domain.html#virDomainManagedSave"><code>virDomainManagedSave</code></a></dt>
s/libvit/libvirt/g in this file, there's other hits in this file too
- Cole
10:56 p.m.
New subject: [libvirt] [PATCH v9 04/13] backup: Parse and output checkpoint XML
Add a new file checkpoint_conf.c that performs the translation to and
from new XML describing a checkpoint. The code shares a common base
class with snapshots, since a checkpoint similarly represents the
domain state at a moment in time. Add some basic testing of round trip
XML handling through the new code.
Of note - this code intentionally differs from snapshots in that XML
schema validation is unconditional, rather than based on a public API
flag. Also, the redefine flag requires the <domain> sub-element to be
present, rather than catering to historical back-compat to older
versions.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/conf/checkpoint_conf.h | 86 +++
src/conf/virconftypes.h | 3 +
po/POTFILES | 1 +
src/conf/Makefile.inc.am | 2 +
src/conf/checkpoint_conf.c | 576 ++++++++++++++++++
src/libvirt_private.syms | 8 +
tests/Makefile.am | 9 +-
.../internal-active-invalid.xml | 53 ++
.../internal-inactive-invalid.xml | 53 ++
tests/qemudomaincheckpointxml2xmltest.c | 213 +++++++
10 files changed, 1002 insertions(+), 2 deletions(-)
create mode 100644 src/conf/checkpoint_conf.h
create mode 100644 src/conf/checkpoint_conf.c
create mode 100644 tests/qemudomaincheckpointxml2xmlout/internal-active-invalid.xml
create mode 100644 tests/qemudomaincheckpointxml2xmlout/internal-inactive-invalid.xml
create mode 100644 tests/qemudomaincheckpointxml2xmltest.c
diff --git a/src/conf/checkpoint_conf.h b/src/conf/checkpoint_conf.h
new file mode 100644
index 0000000000..6215549a20
--- /dev/null
+++ b/src/conf/checkpoint_conf.h
@@ -0,0 +1,86 @@
+/*
+ * checkpoint_conf.h: domain checkpoint XML processing
+ * (based on snapshot_conf.h)
+ *
+ * Copyright (C) 2006-2019 Red Hat, Inc.
+ * Copyright (C) 2006-2008 Daniel P. Berrange
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ */
+
+#pragma once
+
+#include "internal.h"
+#include "domain_conf.h"
+#include "moment_conf.h"
+#include "virobject.h"
+
+/* Items related to checkpoint state */
+
+typedef enum {
+ VIR_DOMAIN_CHECKPOINT_TYPE_DEFAULT = 0,
+ VIR_DOMAIN_CHECKPOINT_TYPE_NONE,
+ VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP,
+
+ VIR_DOMAIN_CHECKPOINT_TYPE_LAST
+} virDomainCheckpointType;
+
+/* Stores disk-checkpoint information */
+typedef struct _virDomainCheckpointDiskDef virDomainCheckpointDiskDef;
+typedef virDomainCheckpointDiskDef *virDomainCheckpointDiskDefPtr;
+struct _virDomainCheckpointDiskDef {
+ char *name; /* name matching the <target dev='...' of the domain */
+ int idx; /* index within checkpoint->dom->disks that matches name */
+ int type; /* virDomainCheckpointType */
+ char *bitmap; /* bitmap name, if type is bitmap */
+ unsigned long long size; /* current checkpoint size in bytes */
+};
+
+/* Stores the complete checkpoint metadata */
+struct _virDomainCheckpointDef {
+ virDomainMomentDef parent;
+
+ /* Additional Public XML. */
+ size_t ndisks; /* should not exceed dom->ndisks */
+ virDomainCheckpointDiskDef *disks;
+};
+
+
+typedef enum {
+ VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE = 1 << 0,
+} virDomainCheckpointParseFlags;
+
+typedef enum {
+ VIR_DOMAIN_CHECKPOINT_FORMAT_SECURE = 1 << 0,
+ VIR_DOMAIN_CHECKPOINT_FORMAT_NO_DOMAIN = 1 << 1,
+ VIR_DOMAIN_CHECKPOINT_FORMAT_SIZE = 1 << 2,
+ VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT = 1 << 3,
+} virDomainCheckpointFormatFlags;
+
+unsigned int virDomainCheckpointFormatConvertXMLFlags(unsigned int flags);
+
+virDomainCheckpointDefPtr virDomainCheckpointDefParseString(const char *xmlStr,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr
xmlopt,
+ bool *current,
+ unsigned int flags);
+virDomainCheckpointDefPtr virDomainCheckpointDefNew(void);
+char *virDomainCheckpointDefFormat(virDomainCheckpointDefPtr def,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ unsigned int flags);
+int virDomainCheckpointAlignDisks(virDomainCheckpointDefPtr checkpoint);
+
+VIR_ENUM_DECL(virDomainCheckpoint);
diff --git a/src/conf/virconftypes.h b/src/conf/virconftypes.h
index b8f553f7fb..fe3f0af14f 100644
--- a/src/conf/virconftypes.h
+++ b/src/conf/virconftypes.h
@@ -102,6 +102,9 @@ typedef virDomainBlkiotune *virDomainBlkiotunePtr;
typedef struct _virDomainBlockIoTuneInfo virDomainBlockIoTuneInfo;
typedef virDomainBlockIoTuneInfo *virDomainBlockIoTuneInfoPtr;
+typedef struct _virDomainCheckpointDef virDomainCheckpointDef;
+typedef virDomainCheckpointDef *virDomainCheckpointDefPtr;
+
typedef struct _virDomainChrDef virDomainChrDef;
typedef virDomainChrDef *virDomainChrDefPtr;
diff --git a/po/POTFILES b/po/POTFILES
index 21eea80329..adf907ed93 100644
--- a/po/POTFILES
+++ b/po/POTFILES
@@ -15,6 +15,7 @@ src/bhyve/bhyve_monitor.c
src/bhyve/bhyve_parse_command.c
src/bhyve/bhyve_process.c
src/conf/capabilities.c
+src/conf/checkpoint_conf.c
src/conf/cpu_conf.c
src/conf/device_conf.c
src/conf/domain_addr.c
diff --git a/src/conf/Makefile.inc.am b/src/conf/Makefile.inc.am
index 6b52ba674b..f0135bcb1c 100644
--- a/src/conf/Makefile.inc.am
+++ b/src/conf/Makefile.inc.am
@@ -14,6 +14,8 @@ NETDEV_CONF_SOURCES = \
DOMAIN_CONF_SOURCES = \
conf/capabilities.c \
conf/capabilities.h \
+ conf/checkpoint_conf.c \
+ conf/checkpoint_conf.h \
conf/domain_addr.c \
conf/domain_addr.h \
conf/domain_capabilities.c \
diff --git a/src/conf/checkpoint_conf.c b/src/conf/checkpoint_conf.c
new file mode 100644
index 0000000000..d50d63ac0e
--- /dev/null
+++ b/src/conf/checkpoint_conf.c
@@ -0,0 +1,576 @@
+/*
+ * checkpoint_conf.c: domain checkpoint XML processing
+ *
+ * Copyright (C) 2006-2019 Red Hat, Inc.
+ * Copyright (C) 2006-2008 Daniel P. Berrange
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ */
+
+#include <config.h>
+
+#include "configmake.h"
+#include "internal.h"
+#include "virbitmap.h"
+#include "virbuffer.h"
+#include "datatypes.h"
+#include "domain_conf.h"
+#include "virlog.h"
+#include "viralloc.h"
+#include "checkpoint_conf.h"
+#include "virstoragefile.h"
+#include "viruuid.h"
+#include "virfile.h"
+#include "virerror.h"
+#include "virxml.h"
+#include "virstring.h"
+
+#define VIR_FROM_THIS VIR_FROM_DOMAIN_CHECKPOINT
+
+VIR_LOG_INIT("conf.checkpoint_conf");
+
+static virClassPtr virDomainCheckpointDefClass;
+static void virDomainCheckpointDefDispose(void *obj);
+
+static int
+virDomainCheckpointOnceInit(void)
+{
+ if (!VIR_CLASS_NEW(virDomainCheckpointDef, virClassForDomainMomentDef()))
+ return -1;
+
+ return 0;
+}
+
+VIR_ONCE_GLOBAL_INIT(virDomainCheckpoint);
+
+VIR_ENUM_IMPL(virDomainCheckpoint,
+ VIR_DOMAIN_CHECKPOINT_TYPE_LAST,
+ "default", "no", "bitmap");
+
+
+/* Checkpoint Def functions */
+static void
+virDomainCheckpointDiskDefClear(virDomainCheckpointDiskDefPtr disk)
+{
+ VIR_FREE(disk->name);
+ VIR_FREE(disk->bitmap);
+}
+
+/* Allocate a new virDomainCheckpointDef; free with virObjectUnref() */
+virDomainCheckpointDefPtr
+virDomainCheckpointDefNew(void)
+{
+ virDomainCheckpointDefPtr def;
+
+ if (virDomainCheckpointInitialize() < 0)
+ return NULL;
+
+ def = virObjectNew(virDomainCheckpointDefClass);
+ return def;
+}
+
+static void
+virDomainCheckpointDefDispose(void *obj)
+{
+ virDomainCheckpointDefPtr def = obj;
+ size_t i;
+
+ for (i = 0; i < def->ndisks; i++)
+ virDomainCheckpointDiskDefClear(&def->disks[i]);
+ VIR_FREE(def->disks);
+}
+
+static int
+virDomainCheckpointDiskDefParseXML(xmlNodePtr node,
+ xmlXPathContextPtr ctxt,
+ virDomainCheckpointDiskDefPtr def)
+{
+ int ret = -1;
+ char *checkpoint = NULL;
+ char *bitmap = NULL;
+ xmlNodePtr saved = ctxt->node;
+
+ ctxt->node = node;
+
+ def->name = virXMLPropString(node, "name");
+ if (!def->name) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing name from disk checkpoint element"));
+ goto cleanup;
+ }
+
+ checkpoint = virXMLPropString(node, "checkpoint");
+ if (checkpoint) {
+ def->type = virDomainCheckpointTypeFromString(checkpoint);
+ if (def->type <= 0) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("unknown disk checkpoint setting '%s'"),
+ checkpoint);
+ goto cleanup;
+ }
+ } else {
+ def->type = VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP;
+ }
+
+ bitmap = virXMLPropString(node, "bitmap");
+ if (bitmap) {
+ if (def->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("disk checkpoint bitmap '%s' requires "
+ "type='bitmap'"),
+ bitmap);
+ goto cleanup;
+ }
+ VIR_STEAL_PTR(def->bitmap, bitmap);
+ }
+
+ ret = 0;
+ cleanup:
+ ctxt->node = saved;
+
+ VIR_FREE(checkpoint);
+ VIR_FREE(bitmap);
+ if (ret < 0)
+ virDomainCheckpointDiskDefClear(def);
+ return ret;
+}
+
+/* flags is bitwise-or of virDomainCheckpointParseFlags. If flags
+ * does not include VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE, then caps
+ * and current are ignored.
+ */
+static virDomainCheckpointDefPtr
+virDomainCheckpointDefParse(xmlXPathContextPtr ctxt,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ bool *current,
+ unsigned int flags)
+{
+ virDomainCheckpointDefPtr def = NULL;
+ virDomainCheckpointDefPtr ret = NULL;
+ xmlNodePtr *nodes = NULL;
+ size_t i;
+ int n;
+ char *creation = NULL;
+ int active;
+ char *tmp;
+
+ if (!(def = virDomainCheckpointDefNew()))
+ return NULL;
+
+ def->parent.name = virXPathString("string(./name)", ctxt);
+ if (def->parent.name == NULL) {
+ if (flags & VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE) {
+ virReportError(VIR_ERR_XML_ERROR, "%s",
+ _("a redefined checkpoint must have a name"));
+ goto cleanup;
+ }
+ }
+
+ def->parent.description = virXPathString("string(./description)",
ctxt);
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE) {
+ if (virXPathLongLong("string(./creationTime)", ctxt,
+ &def->parent.creationTime) < 0) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing creationTime from existing
checkpoint"));
+ goto cleanup;
+ }
+
+ def->parent.parent_name = virXPathString("string(./parent/name)",
ctxt);
+
+ if (virXPathInt("string(./current)", ctxt, &active) < 0 ||
!current) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing current from existing checkpoint"));
+ goto cleanup;
+ }
+ *current = !!active;
+
+ if ((tmp = virXPathString("string(./domain/@type)", ctxt))) {
+ int domainflags = VIR_DOMAIN_DEF_PARSE_INACTIVE |
+ VIR_DOMAIN_DEF_PARSE_SKIP_VALIDATE;
+ xmlNodePtr domainNode = virXPathNode("./domain", ctxt);
+
+ VIR_FREE(tmp);
+ if (!domainNode) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing domain in checkpoint"));
+ goto cleanup;
+ }
+ def->parent.dom = virDomainDefParseNode(ctxt->node->doc,
domainNode,
+ caps, xmlopt, NULL,
+ domainflags);
+ if (!def->parent.dom)
+ goto cleanup;
+ } else {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing domain in checkpoint redefine"));
+ goto cleanup;
+ }
+ } else if (virDomainXMLOptionRunMomentPostParse(xmlopt, &def->parent) < 0)
{
+ goto cleanup;
+ }
+
+ if ((n = virXPathNodeSet("./disks/*", ctxt, &nodes)) < 0)
+ goto cleanup;
+ if (n && VIR_ALLOC_N(def->disks, n) < 0)
+ goto cleanup;
+ def->ndisks = n;
+ for (i = 0; i < def->ndisks; i++) {
+ if (virDomainCheckpointDiskDefParseXML(nodes[i], ctxt,
+ &def->disks[i]) < 0)
+ goto cleanup;
+ }
+
+ VIR_STEAL_PTR(ret, def);
+
+ cleanup:
+ VIR_FREE(creation);
+ VIR_FREE(nodes);
+ virObjectUnref(def);
+
+ return ret;
+}
+
+static virDomainCheckpointDefPtr
+virDomainCheckpointDefParseNode(xmlDocPtr xml,
+ xmlNodePtr root,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ bool *current,
+ unsigned int flags)
+{
+ xmlXPathContextPtr ctxt = NULL;
+ virDomainCheckpointDefPtr def = NULL;
+ VIR_AUTOFREE(char *) schema = NULL;
+
+ if (!virXMLNodeNameEqual(root, "domaincheckpoint")) {
+ virReportError(VIR_ERR_XML_ERROR, "%s",
_("domaincheckpoint"));
+ goto cleanup;
+ }
+
+ /* This is a new enough API to make schema validation unconditional */
+ schema = virFileFindResource("domaincheckpoint.rng",
+ abs_top_srcdir "/docs/schemas",
+ PKGDATADIR "/schemas");
+ if (!schema)
+ return NULL;
+ if (virXMLValidateAgainstSchema(schema, xml) < 0)
+ return NULL;
+
+ ctxt = xmlXPathNewContext(xml);
+ if (ctxt == NULL) {
+ virReportOOMError();
+ goto cleanup;
+ }
+
+ ctxt->node = root;
+ def = virDomainCheckpointDefParse(ctxt, caps, xmlopt, current, flags);
+ cleanup:
+ xmlXPathFreeContext(ctxt);
+ return def;
+}
+
+virDomainCheckpointDefPtr
+virDomainCheckpointDefParseString(const char *xmlStr,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ bool *current,
+ unsigned int flags)
+{
+ virDomainCheckpointDefPtr ret = NULL;
+ xmlDocPtr xml;
+ int keepBlanksDefault = xmlKeepBlanksDefault(0);
+
+ if ((xml = virXMLParse(NULL, xmlStr, _("(domain_checkpoint)")))) {
+ xmlKeepBlanksDefault(keepBlanksDefault);
+ ret = virDomainCheckpointDefParseNode(xml, xmlDocGetRootElement(xml),
+ caps, xmlopt, current, flags);
+ xmlFreeDoc(xml);
+ }
+ xmlKeepBlanksDefault(keepBlanksDefault);
+
+ return ret;
+}
+
+
+/**
+ * virDomainCheckpointDefAssignBitmapNames:
+ * @def: checkpoint def object
+ *
+ * Generate default bitmap names for checkpoint targets. Returns 0 on
+ * success, -1 on error.
+ */
+static int
+virDomainCheckpointDefAssignBitmapNames(virDomainCheckpointDefPtr def)
+{
+ size_t i;
+
+ for (i = 0; i < def->ndisks; i++) {
+ virDomainCheckpointDiskDefPtr disk = &def->disks[i];
+
+ if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP ||
+ disk->bitmap)
+ continue;
+
+ if (VIR_STRDUP(disk->bitmap, def->parent.name) < 0)
+ return -1;
+ }
+
+ return 0;
+}
+
+
+static int
+virDomainCheckpointCompareDiskIndex(const void *a, const void *b)
+{
+ const virDomainCheckpointDiskDef *diska = a;
+ const virDomainCheckpointDiskDef *diskb = b;
+
+ /* Integer overflow shouldn't be a problem here. */
+ return diska->idx - diskb->idx;
+}
+
+/* Align def->disks to def->domain. Sort the list of def->disks,
+ * filling in any missing disks with appropriate default. Convert
+ * paths to disk targets for uniformity. Issue an error and return -1
+ * if any def->disks[n]->name appears more than once or does not map
+ * to dom->disks. */
+int
+virDomainCheckpointAlignDisks(virDomainCheckpointDefPtr def)
+{
+ int ret = -1;
+ virBitmapPtr map = NULL;
+ size_t i;
+ int ndisks;
+ int checkpoint_default = VIR_DOMAIN_CHECKPOINT_TYPE_NONE;
+
+ if (!def->parent.dom) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing domain in checkpoint"));
+ goto cleanup;
+ }
+
+ if (def->ndisks > def->parent.dom->ndisks) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s",
+ _("too many disk checkpoint requests for domain"));
+ goto cleanup;
+ }
+
+ /* Unlikely to have a guest without disks but technically possible. */
+ if (!def->parent.dom->ndisks) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s",
+ _("domain must have at least one disk to perform "
+ "checkpoints"));
+ goto cleanup;
+ }
+
+ /* If <disks> omitted, do bitmap on all disks; otherwise, do nothing
+ * for omitted disks */
+ if (!def->ndisks)
+ checkpoint_default = VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP;
+
+ if (!(map = virBitmapNew(def->parent.dom->ndisks)))
+ goto cleanup;
+
+ /* Double check requested disks. */
+ for (i = 0; i < def->ndisks; i++) {
+ virDomainCheckpointDiskDefPtr disk = &def->disks[i];
+ int idx = virDomainDiskIndexByName(def->parent.dom, disk->name, false);
+
+ if (idx < 0) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("no disk named '%s'"), disk->name);
+ goto cleanup;
+ }
+
+ if (virBitmapIsBitSet(map, idx)) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("disk '%s' specified twice"),
+ disk->name);
+ goto cleanup;
+ }
+ ignore_value(virBitmapSetBit(map, idx));
+ disk->idx = idx;
+
+ if (STRNEQ(disk->name, def->parent.dom->disks[idx]->dst)) {
+ VIR_FREE(disk->name);
+ if (VIR_STRDUP(disk->name, def->parent.dom->disks[idx]->dst) <
0)
+ goto cleanup;
+ }
+ }
+
+ /* Provide defaults for all remaining disks. */
+ ndisks = def->ndisks;
+ if (VIR_EXPAND_N(def->disks, def->ndisks,
+ def->parent.dom->ndisks - def->ndisks) < 0)
+ goto cleanup;
+
+ for (i = 0; i < def->parent.dom->ndisks; i++) {
+ virDomainCheckpointDiskDefPtr disk;
+
+ if (virBitmapIsBitSet(map, i))
+ continue;
+ disk = &def->disks[ndisks++];
+ if (VIR_STRDUP(disk->name, def->parent.dom->disks[i]->dst) < 0)
+ goto cleanup;
+ disk->idx = i;
+
+ /* Don't checkpoint empty drives */
+ if (virStorageSourceIsEmpty(def->parent.dom->disks[i]->src))
+ disk->type = VIR_DOMAIN_CHECKPOINT_TYPE_NONE;
+ else
+ disk->type = checkpoint_default;
+ }
+
+ qsort(&def->disks[0], def->ndisks, sizeof(def->disks[0]),
+ virDomainCheckpointCompareDiskIndex);
+
+ /* Generate default bitmap names for checkpoint */
+ if (virDomainCheckpointDefAssignBitmapNames(def) < 0)
+ goto cleanup;
+
+ ret = 0;
+
+ cleanup:
+ virBitmapFree(map);
+ return ret;
+}
+
+
+/* Converts public VIR_DOMAIN_CHECKPOINT_XML_* into
+ * VIR_DOMAIN_CHECKPOINT_FORMAT_* flags, and silently ignores any other
+ * flags. */
+unsigned int virDomainCheckpointFormatConvertXMLFlags(unsigned int flags)
+{
+ unsigned int formatFlags = 0;
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_XML_SECURE)
+ formatFlags |= VIR_DOMAIN_CHECKPOINT_FORMAT_SECURE;
+ if (flags & VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN)
+ formatFlags |= VIR_DOMAIN_CHECKPOINT_FORMAT_NO_DOMAIN;
+ if (flags & VIR_DOMAIN_CHECKPOINT_XML_SIZE)
+ formatFlags |= VIR_DOMAIN_CHECKPOINT_FORMAT_SIZE;
+
+ return formatFlags;
+}
+
+
+static int
+virDomainCheckpointDiskDefFormat(virBufferPtr buf,
+ virDomainCheckpointDiskDefPtr disk,
+ unsigned int flags)
+{
+ if (!disk->name)
+ return 0;
+
+ virBufferEscapeString(buf, "<disk name='%s'", disk->name);
+ if (disk->type)
+ virBufferAsprintf(buf, " checkpoint='%s'",
+ virDomainCheckpointTypeToString(disk->type));
+ if (disk->bitmap) {
+ virBufferEscapeString(buf, " bitmap='%s'", disk->bitmap);
+ if (flags & VIR_DOMAIN_CHECKPOINT_FORMAT_SIZE)
+ virBufferAsprintf(buf, " size='%llu'", disk->size);
+ }
+ virBufferAddLit(buf, "/>\n");
+ return 0;
+}
+
+
+static int
+virDomainCheckpointDefFormatInternal(virBufferPtr buf,
+ virDomainCheckpointDefPtr def,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ unsigned int flags)
+{
+ size_t i;
+ unsigned int domainflags = VIR_DOMAIN_DEF_FORMAT_INACTIVE;
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_FORMAT_SECURE)
+ domainflags |= VIR_DOMAIN_DEF_FORMAT_SECURE;
+
+ virBufferAddLit(buf, "<domaincheckpoint>\n");
+ virBufferAdjustIndent(buf, 2);
+
+ virBufferEscapeString(buf, "<name>%s</name>\n",
def->parent.name);
+ virBufferEscapeString(buf, "<description>%s</description>\n",
+ def->parent.description);
+
+ if (def->parent.parent_name) {
+ virBufferAddLit(buf, "<parent>\n");
+ virBufferAdjustIndent(buf, 2);
+ virBufferEscapeString(buf, "<name>%s</name>\n",
+ def->parent.parent_name);
+ virBufferAdjustIndent(buf, -2);
+ virBufferAddLit(buf, "</parent>\n");
+ }
+
+ if (def->parent.creationTime)
+ virBufferAsprintf(buf,
"<creationTime>%lld</creationTime>\n",
+ def->parent.creationTime);
+
+ virBufferAsprintf(buf, "<current>%d</current>\n",
+ !!(flags & VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT));
+
+ if (def->ndisks) {
+ virBufferAddLit(buf, "<disks>\n");
+ virBufferAdjustIndent(buf, 2);
+ for (i = 0; i < def->ndisks; i++) {
+ if (virDomainCheckpointDiskDefFormat(buf, &def->disks[i],
+ flags) < 0)
+ goto error;
+ }
+ virBufferAdjustIndent(buf, -2);
+ virBufferAddLit(buf, "</disks>\n");
+ }
+
+ if (!(flags & VIR_DOMAIN_CHECKPOINT_FORMAT_NO_DOMAIN) &&
+ virDomainDefFormatInternal(def->parent.dom, caps, domainflags, buf,
+ xmlopt) < 0)
+ goto error;
+
+ virBufferAdjustIndent(buf, -2);
+ virBufferAddLit(buf, "</domaincheckpoint>\n");
+
+ if (virBufferCheckError(buf) < 0)
+ goto error;
+
+ return 0;
+
+ error:
+ virBufferFreeAndReset(buf);
+ return -1;
+}
+
+char *
+virDomainCheckpointDefFormat(virDomainCheckpointDefPtr def,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ unsigned int flags)
+{
+ virBuffer buf = VIR_BUFFER_INITIALIZER;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_FORMAT_SECURE |
+ VIR_DOMAIN_CHECKPOINT_FORMAT_NO_DOMAIN |
+ VIR_DOMAIN_CHECKPOINT_FORMAT_SIZE |
+ VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT, NULL);
+ if (virDomainCheckpointDefFormatInternal(&buf, def, caps, xmlopt,
+ flags) < 0)
+ return NULL;
+
+ return virBufferContentAndReset(&buf);
+}
diff --git a/src/libvirt_private.syms b/src/libvirt_private.syms
index b8772d2895..a7e508f217 100644
--- a/src/libvirt_private.syms
+++ b/src/libvirt_private.syms
@@ -69,6 +69,14 @@ virCapabilitiesSetHostCPU;
virCapabilitiesSetNetPrefix;
+# conf/checkpoint_conf.h
+virDomainCheckpointDefFormat;
+virDomainCheckpointDefNew;
+virDomainCheckpointDefParseString;
+virDomainCheckpointTypeFromString;
+virDomainCheckpointTypeToString;
+
+
# conf/cpu_conf.h
virCPUCacheModeTypeFromString;
virCPUCacheModeTypeToString;
diff --git a/tests/Makefile.am b/tests/Makefile.am
index 66c6ad911e..1fd698c2d2 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -277,7 +277,7 @@ endif WITH_LIBXL
if WITH_QEMU
test_programs += qemuxml2argvtest qemuxml2xmltest \
- qemudomainsnapshotxml2xmltest \
+ qemudomaincheckpointxml2xmltest qemudomainsnapshotxml2xmltest \
qemumonitorjsontest qemuhotplugtest \
qemuagenttest qemucapabilitiestest qemucaps2xmltest \
qemumemlocktest \
@@ -658,6 +658,11 @@ qemublocktest_LDADD = \
$(qemu_LDADDS) \
$(NULL)
+qemudomaincheckpointxml2xmltest_SOURCES = \
+ qemudomaincheckpointxml2xmltest.c testutilsqemu.c testutilsqemu.h \
+ testutils.c testutils.h
+qemudomaincheckpointxml2xmltest_LDADD = $(qemu_LDADDS)
+
qemudomainsnapshotxml2xmltest_SOURCES = \
qemudomainsnapshotxml2xmltest.c testutilsqemu.c testutilsqemu.h \
testutils.c testutils.h
@@ -693,7 +698,7 @@ qemufirmwaretest_LDADD = $(qemu_LDADDS)
else ! WITH_QEMU
EXTRA_DIST += qemuxml2argvtest.c qemuxml2xmltest.c \
- qemudomainsnapshotxml2xmltest.c \
+ qemudomaincheckpointxml2xmltest.c qemudomainsnapshotxml2xmltest.c \
testutilsqemu.c testutilsqemu.h \
testutilsqemuschema.c testutilsqemuschema.h \
qemumonitorjsontest.c qemuhotplugtest.c \
diff --git a/tests/qemudomaincheckpointxml2xmlout/internal-active-invalid.xml
b/tests/qemudomaincheckpointxml2xmlout/internal-active-invalid.xml
new file mode 100644
index 0000000000..a518c58915
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlout/internal-active-invalid.xml
@@ -0,0 +1,53 @@
+<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>QEMUGuest1</name>
+ <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+ <memory unit='KiB'>219136</memory>
+ <currentMemory unit='KiB'>219136</currentMemory>
+ <vcpu placement='static'>1</vcpu>
+ <os>
+ <type arch='i686' machine='pc'>hvm</type>
+ <boot dev='hd'/>
+ </os>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <emulator>/usr/bin/qemu-system-i686</emulator>
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2'/>
+ <source file='/tmp/data.img'/>
+ <target dev='vda' bus='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x03' function='0x0'/>
+ </disk>
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2'/>
+ <source file='/tmp/logs.img'/>
+ <target dev='vdb' bus='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x04' function='0x0'/>
+ </disk>
+ <controller type='usb' index='0'>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x01' function='0x2'/>
+ </controller>
+ <controller type='ide' index='0'>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x01' function='0x1'/>
+ </controller>
+ <controller type='pci' index='0' model='pci-root'/>
+ <input type='mouse' bus='ps2'/>
+ <input type='keyboard' bus='ps2'/>
+ <memballoon model='none'/>
+ </devices>
+ </domain>
+ <active>1</active>
+</domaincheckpoint>
diff --git a/tests/qemudomaincheckpointxml2xmlout/internal-inactive-invalid.xml
b/tests/qemudomaincheckpointxml2xmlout/internal-inactive-invalid.xml
new file mode 100644
index 0000000000..df14c97836
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmlout/internal-inactive-invalid.xml
@@ -0,0 +1,53 @@
+<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>QEMUGuest1</name>
+ <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+ <memory unit='KiB'>219136</memory>
+ <currentMemory unit='KiB'>219136</currentMemory>
+ <vcpu placement='static'>1</vcpu>
+ <os>
+ <type arch='i686' machine='pc'>hvm</type>
+ <boot dev='hd'/>
+ </os>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <emulator>/usr/bin/qemu-system-i686</emulator>
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2'/>
+ <source file='/tmp/data.img'/>
+ <target dev='vda' bus='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x03' function='0x0'/>
+ </disk>
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2'/>
+ <source file='/tmp/logs.img'/>
+ <target dev='vdb' bus='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x04' function='0x0'/>
+ </disk>
+ <controller type='usb' index='0'>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x01' function='0x2'/>
+ </controller>
+ <controller type='ide' index='0'>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x01' function='0x1'/>
+ </controller>
+ <controller type='pci' index='0' model='pci-root'/>
+ <input type='mouse' bus='ps2'/>
+ <input type='keyboard' bus='ps2'/>
+ <memballoon model='none'/>
+ </devices>
+ </domain>
+ <active>0</active>
+</domaincheckpoint>
diff --git a/tests/qemudomaincheckpointxml2xmltest.c
b/tests/qemudomaincheckpointxml2xmltest.c
new file mode 100644
index 0000000000..d509df37d4
--- /dev/null
+++ b/tests/qemudomaincheckpointxml2xmltest.c
@@ -0,0 +1,213 @@
+#include <config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+
+#include <sys/types.h>
+#include <fcntl.h>
+
+#include "testutils.h"
+
+#ifdef WITH_QEMU
+
+# include "internal.h"
+# include "qemu/qemu_conf.h"
+# include "qemu/qemu_domain.h"
+# include "checkpoint_conf.h"
+# include "testutilsqemu.h"
+# include "virstring.h"
+
+# define VIR_FROM_THIS VIR_FROM_NONE
+
+static virQEMUDriver driver;
+
+enum {
+ TEST_REDEFINE = 1 << 0, /* Test use of REDEFINE parse flag */
+ TEST_PARENT = 1 << 1, /* hard-code parent after parse */
+ TEST_VDA_BITMAP = 1 << 2, /* hard-code disk vda after parse */
+ TEST_SIZE = 1 << 3, /* Test use of SIZE format flag */
+};
+
+static int
+testCompareXMLToXMLFiles(const char *inxml,
+ const char *outxml,
+ unsigned int flags)
+{
+ char *inXmlData = NULL;
+ char *outXmlData = NULL;
+ char *actual = NULL;
+ int ret = -1;
+ virDomainCheckpointDefPtr def = NULL;
+ unsigned int parseflags = 0;
+ unsigned int formatflags = VIR_DOMAIN_CHECKPOINT_FORMAT_SECURE;
+ bool cur = false;
+
+ if (flags & TEST_REDEFINE)
+ parseflags |= VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE;
+
+ if (virTestLoadFile(inxml, &inXmlData) < 0)
+ goto cleanup;
+
+ if (virTestLoadFile(outxml, &outXmlData) < 0)
+ goto cleanup;
+
+ if (!(def = virDomainCheckpointDefParseString(inXmlData, driver.caps,
+ driver.xmlopt, &cur,
+ parseflags)))
+ goto cleanup;
+ if (cur) {
+ if (!(flags & TEST_REDEFINE))
+ goto cleanup;
+ formatflags |= VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT;
+ }
+ if (flags & TEST_PARENT) {
+ if (def->parent.parent_name)
+ goto cleanup;
+ if (VIR_STRDUP(def->parent.parent_name, "1525111885") < 0)
+ goto cleanup;
+ }
+ if (flags & TEST_VDA_BITMAP) {
+ virDomainCheckpointDiskDefPtr disk;
+
+ if (VIR_EXPAND_N(def->disks, def->ndisks, 1) < 0)
+ goto cleanup;
+ disk = &def->disks[0];
+ if (disk->bitmap)
+ goto cleanup;
+ if (!disk->name) {
+ disk->type = VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP;
+ if (VIR_STRDUP(disk->name, "vda") < 0)
+ goto cleanup;
+ } else if (STRNEQ(disk->name, "vda")) {
+ goto cleanup;
+ }
+ if (VIR_STRDUP(disk->bitmap, def->parent.name) < 0)
+ goto cleanup;
+ }
+ if (flags & TEST_SIZE) {
+ def->disks[0].size = 1048576;
+ formatflags |= (VIR_DOMAIN_CHECKPOINT_FORMAT_SIZE |
+ VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT);
+ }
+
+ /* Parsing XML does not populate the domain definition; work
+ * around that by not requesting domain on output */
+ if (!def->parent.dom)
+ formatflags |= VIR_DOMAIN_CHECKPOINT_FORMAT_NO_DOMAIN;
+
+ if (!(actual = virDomainCheckpointDefFormat(def, driver.caps,
+ driver.xmlopt,
+ formatflags)))
+ goto cleanup;
+
+ if (STRNEQ(outXmlData, actual)) {
+ virTestDifferenceFull(stderr, outXmlData, outxml, actual, inxml);
+ goto cleanup;
+ }
+
+ ret = 0;
+
+ cleanup:
+ VIR_FREE(inXmlData);
+ VIR_FREE(outXmlData);
+ VIR_FREE(actual);
+ virObjectUnref(def);
+ return ret;
+}
+
+struct testInfo {
+ const char *inxml;
+ const char *outxml;
+ long long creationTime;
+ unsigned int flags;
+};
+static long long mocktime;
+
+static int
+testCheckpointPostParse(virDomainMomentDefPtr def)
+{
+ if (!mocktime)
+ return 0;
+ if (def->creationTime)
+ return -1;
+ def->creationTime = mocktime;
+ if (!def->name &&
+ virAsprintf(&def->name, "%lld", def->creationTime) < 0)
+ return -1;
+ return 0;
+}
+
+static int
+testCompareXMLToXMLHelper(const void *data)
+{
+ const struct testInfo *info = data;
+
+ mocktime = info->creationTime;
+ return testCompareXMLToXMLFiles(info->inxml, info->outxml, info->flags);
+}
+
+
+static int
+mymain(void)
+{
+ int ret = 0;
+
+ if (qemuTestDriverInit(&driver) < 0)
+ return EXIT_FAILURE;
+
+ virDomainXMLOptionSetMomentPostParse(driver.xmlopt,
+ testCheckpointPostParse);
+
+# define DO_TEST(prefix, name, inpath, outpath, time, flags) \
+ do { \
+ const struct testInfo info = {abs_srcdir "/" inpath "/" name
".xml", \
+ abs_srcdir "/" outpath "/" name
".xml", \
+ time, flags}; \
+ if (virTestRun("CHECKPOINT XML-2-XML " prefix " " name, \
+ testCompareXMLToXMLHelper, &info) < 0) \
+ ret = -1; \
+ } while (0)
+
+# define DO_TEST_INOUT(name, time, flags) \
+ DO_TEST("in->out", name, \
+ "qemudomaincheckpointxml2xmlin", \
+ "qemudomaincheckpointxml2xmlout", \
+ time, flags)
+# define DO_TEST_OUT(name, flags) \
+ DO_TEST("out->out", name, \
+ "qemudomaincheckpointxml2xmlout", \
+ "qemudomaincheckpointxml2xmlout", \
+ 0, flags | TEST_REDEFINE)
+
+ /* Unset or set all envvars here that are copied in qemudBuildCommandLine
+ * using ADD_ENV_COPY, otherwise these tests may fail due to unexpected
+ * values for these envvars */
+ setenv("PATH", "/bin", 1);
+
+ /* Test a normal user redefine */
+ DO_TEST_OUT("redefine", 0);
+
+ /* Tests of valid user input, and resulting output */
+ DO_TEST_INOUT("empty", 1525889631, TEST_VDA_BITMAP);
+ DO_TEST_INOUT("sample", 1525889631, TEST_PARENT | TEST_VDA_BITMAP);
+ DO_TEST_INOUT("size", 1553648510,
+ TEST_PARENT | TEST_VDA_BITMAP | TEST_SIZE);
+
+ qemuTestDriverFree(&driver);
+
+ return ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE;
+}
+
+VIR_TEST_MAIN(mymain)
+
+#else
+
+int
+main(void)
+{
+ return EXIT_AM_SKIP;
+}
+
+#endif /* WITH_QEMU */
--
2.20.1
7:06 a.m.
New subject: [libvirt] [PATCH v9 04/13] backup: Parse and output checkpoint XML
On Sat, Jul 06, 2019 at 22:56:04 -0500, Eric Blake wrote:
Add a new file checkpoint_conf.c that performs the translation to
and
from new XML describing a checkpoint. The code shares a common base
class with snapshots, since a checkpoint similarly represents the
domain state at a moment in time. Add some basic testing of round trip
XML handling through the new code.
Of note - this code intentionally differs from snapshots in that XML
schema validation is unconditional, rather than based on a public API
flag. Also, the redefine flag requires the <domain> sub-element to be
present, rather than catering to historical back-compat to older
versions.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
[...]
diff --git a/src/conf/checkpoint_conf.c b/src/conf/checkpoint_conf.c
new file mode 100644
index 0000000000..d50d63ac0e
--- /dev/null
+++ b/src/conf/checkpoint_conf.c
@@ -0,0 +1,576 @@
[...]
+static int
+virDomainCheckpointDiskDefParseXML(xmlNodePtr node,
+ xmlXPathContextPtr ctxt,
+ virDomainCheckpointDiskDefPtr def)
+{
+ int ret = -1;
+ char *checkpoint = NULL;
+ char *bitmap = NULL;
+ xmlNodePtr saved = ctxt->node;
+
+ ctxt->node = node;
+
+ def->name = virXMLPropString(node, "name");
+ if (!def->name) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing name from disk checkpoint element"));
'name' is mandatory in the schema for <disk>
+ goto cleanup;
+ }
+
+ checkpoint = virXMLPropString(node, "checkpoint");
This attribute seems to be mandatory in the schema [1]
+ if (checkpoint) {
+ def->type = virDomainCheckpointTypeFromString(checkpoint);
+ if (def->type <= 0) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("unknown disk checkpoint setting '%s'"),
+ checkpoint);
These are also mandated.
+ goto cleanup;
+ }
+ } else {
+ def->type = VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP;
[1] so this should never happen
+ }
+
+ bitmap = virXMLPropString(node, "bitmap");
+ if (bitmap) {
+ if (def->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("disk checkpoint bitmap '%s' requires "
+ "type='bitmap'"),
+ bitmap);
And this is also mandated by the schema.
+ goto cleanup;
+ }
+ VIR_STEAL_PTR(def->bitmap, bitmap);
+ }
+
+ ret = 0;
+ cleanup:
+ ctxt->node = saved;
+
+ VIR_FREE(checkpoint);
+ VIR_FREE(bitmap);
+ if (ret < 0)
+ virDomainCheckpointDiskDefClear(def);
+ return ret;
+}
+
+/* flags is bitwise-or of virDomainCheckpointParseFlags. If flags
+ * does not include VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE, then caps
+ * and current are ignored.
+ */
+static virDomainCheckpointDefPtr
+virDomainCheckpointDefParse(xmlXPathContextPtr ctxt,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ bool *current,
+ unsigned int flags)
+{
+ virDomainCheckpointDefPtr def = NULL;
+ virDomainCheckpointDefPtr ret = NULL;
+ xmlNodePtr *nodes = NULL;
+ size_t i;
+ int n;
+ char *creation = NULL;
+ int active;
+ char *tmp;
+
+ if (!(def = virDomainCheckpointDefNew()))
+ return NULL;
+
+ def->parent.name = virXPathString("string(./name)", ctxt);
+ if (def->parent.name == NULL) {
+ if (flags & VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE) {
+ virReportError(VIR_ERR_XML_ERROR, "%s",
+ _("a redefined checkpoint must have a name"));
+ goto cleanup;
+ }
+ }
+
+ def->parent.description = virXPathString("string(./description)",
ctxt);
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE) {
+ if (virXPathLongLong("string(./creationTime)", ctxt,
+ &def->parent.creationTime) < 0) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing creationTime from existing
checkpoint"));
+ goto cleanup;
In v8 I've pointed out that we should not intermix validation of the XML
with the parsing.
+ }
+
+ def->parent.parent_name = virXPathString("string(./parent/name)",
ctxt);
+
+ if (virXPathInt("string(./current)", ctxt, &active) < 0 ||
!current) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing current from existing checkpoint"));
+ goto cleanup;
+ }
+ *current = !!active;
+
+ if ((tmp = virXPathString("string(./domain/@type)", ctxt))) {
+ int domainflags = VIR_DOMAIN_DEF_PARSE_INACTIVE |
+ VIR_DOMAIN_DEF_PARSE_SKIP_VALIDATE;
+ xmlNodePtr domainNode = virXPathNode("./domain", ctxt);
+
+ VIR_FREE(tmp);
+ if (!domainNode) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing domain in checkpoint"));
+ goto cleanup;
+ }
+ def->parent.dom = virDomainDefParseNode(ctxt->node->doc,
domainNode,
+ caps, xmlopt, NULL,
+ domainflags);
+ if (!def->parent.dom)
+ goto cleanup;
+ } else {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing domain in checkpoint redefine"));
+ goto cleanup;
+ }
+ } else if (virDomainXMLOptionRunMomentPostParse(xmlopt, &def->parent) < 0)
{
+ goto cleanup;
+ }
+
+ if ((n = virXPathNodeSet("./disks/*", ctxt, &nodes)) < 0)
+ goto cleanup;
+ if (n && VIR_ALLOC_N(def->disks, n) < 0)
+ goto cleanup;
+ def->ndisks = n;
+ for (i = 0; i < def->ndisks; i++) {
+ if (virDomainCheckpointDiskDefParseXML(nodes[i], ctxt,
+ &def->disks[i]) < 0)
+ goto cleanup;
+ }
+
+ VIR_STEAL_PTR(ret, def);
+
+ cleanup:
+ VIR_FREE(creation);
+ VIR_FREE(nodes);
+ virObjectUnref(def);
+
+ return ret;
+}
+
+static virDomainCheckpointDefPtr
+virDomainCheckpointDefParseNode(xmlDocPtr xml,
+ xmlNodePtr root,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ bool *current,
+ unsigned int flags)
+{
+ xmlXPathContextPtr ctxt = NULL;
+ virDomainCheckpointDefPtr def = NULL;
+ VIR_AUTOFREE(char *) schema = NULL;
+
+ if (!virXMLNodeNameEqual(root, "domaincheckpoint")) {
+ virReportError(VIR_ERR_XML_ERROR, "%s",
_("domaincheckpoint"));
+ goto cleanup;
The schema will be able to validate this.
+ }
+
+ /* This is a new enough API to make schema validation unconditional */
+ schema = virFileFindResource("domaincheckpoint.rng",
+ abs_top_srcdir "/docs/schemas",
+ PKGDATADIR "/schemas");
+ if (!schema)
+ return NULL;
+ if (virXMLValidateAgainstSchema(schema, xml) < 0)
+ return NULL;
+
+ ctxt = xmlXPathNewContext(xml);
+ if (ctxt == NULL) {
+ virReportOOMError();
+ goto cleanup;
+ }
+
+ ctxt->node = root;
+ def = virDomainCheckpointDefParse(ctxt, caps, xmlopt, current, flags);
+ cleanup:
+ xmlXPathFreeContext(ctxt);
+ return def;
+}
[...]
+int
+virDomainCheckpointAlignDisks(virDomainCheckpointDefPtr def)
+{
+ int ret = -1;
+ virBitmapPtr map = NULL;
+ size_t i;
+ int ndisks;
+ int checkpoint_default = VIR_DOMAIN_CHECKPOINT_TYPE_NONE;
+
+ if (!def->parent.dom) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("missing domain in checkpoint"));
+ goto cleanup;
Is this possible?
+ }
+
+ if (def->ndisks > def->parent.dom->ndisks) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s",
+ _("too many disk checkpoint requests for domain"));
+ goto cleanup;
+ }
+
+ /* Unlikely to have a guest without disks but technically possible. */
+ if (!def->parent.dom->ndisks) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s",
+ _("domain must have at least one disk to perform "
+ "checkpoints"));
+ goto cleanup;
+ }
+
+ /* If <disks> omitted, do bitmap on all disks; otherwise, do nothing
+ * for omitted disks */
+ if (!def->ndisks)
+ checkpoint_default = VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP;
+
+ if (!(map = virBitmapNew(def->parent.dom->ndisks)))
+ goto cleanup;
+
+ /* Double check requested disks. */
+ for (i = 0; i < def->ndisks; i++) {
+ virDomainCheckpointDiskDefPtr disk = &def->disks[i];
+ int idx = virDomainDiskIndexByName(def->parent.dom, disk->name, false);
+
+ if (idx < 0) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("no disk named '%s'"), disk->name);
+ goto cleanup;
+ }
+
+ if (virBitmapIsBitSet(map, idx)) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("disk '%s' specified twice"),
+ disk->name);
+ goto cleanup;
+ }
+ ignore_value(virBitmapSetBit(map, idx));
+ disk->idx = idx;
+
+ if (STRNEQ(disk->name, def->parent.dom->disks[idx]->dst)) {
+ VIR_FREE(disk->name);
+ if (VIR_STRDUP(disk->name, def->parent.dom->disks[idx]->dst)
< 0)
+ goto cleanup;
+ }
+ }
+
+ /* Provide defaults for all remaining disks. */
+ ndisks = def->ndisks;
+ if (VIR_EXPAND_N(def->disks, def->ndisks,
+ def->parent.dom->ndisks - def->ndisks) < 0)
+ goto cleanup;
+
+ for (i = 0; i < def->parent.dom->ndisks; i++) {
+ virDomainCheckpointDiskDefPtr disk;
+
+ if (virBitmapIsBitSet(map, i))
+ continue;
+ disk = &def->disks[ndisks++];
+ if (VIR_STRDUP(disk->name, def->parent.dom->disks[i]->dst) < 0)
+ goto cleanup;
+ disk->idx = i;
+
+ /* Don't checkpoint empty drives */
Without -blockdev you'll also have a problem also with readonly disks as
qemu does not open the actual file for writing and thus writing the
bitmap won't work.
Also ... it doesn't make much sense ... since the bitmap will be empty
forever.
+ if
(virStorageSourceIsEmpty(def->parent.dom->disks[i]->src))
+ disk->type = VIR_DOMAIN_CHECKPOINT_TYPE_NONE;
+ else
+ disk->type = checkpoint_default;
+ }
+
+ qsort(&def->disks[0], def->ndisks, sizeof(def->disks[0]),
+ virDomainCheckpointCompareDiskIndex);
+
+ /* Generate default bitmap names for checkpoint */
+ if (virDomainCheckpointDefAssignBitmapNames(def) < 0)
+ goto cleanup;
+
+ ret = 0;
+
+ cleanup:
+ virBitmapFree(map);
+ return ret;
+}
[...]
+static int
+virDomainCheckpointDiskDefFormat(virBufferPtr buf,
+ virDomainCheckpointDiskDefPtr disk,
+ unsigned int flags)
+{
+ if (!disk->name)
+ return 0;
+
+ virBufferEscapeString(buf, "<disk name='%s'", disk->name);
+ if (disk->type)
+ virBufferAsprintf(buf, " checkpoint='%s'",
+ virDomainCheckpointTypeToString(disk->type));
+ if (disk->bitmap) {
+ virBufferEscapeString(buf, " bitmap='%s'", disk->bitmap);
+ if (flags & VIR_DOMAIN_CHECKPOINT_FORMAT_SIZE)
+ virBufferAsprintf(buf, " size='%llu'", disk->size);
The schema does not tie the size attribute to the presence of the
bitmap name.
+ }
+ virBufferAddLit(buf, "/>\n");
+ return 0;
+}
[...]
ACK in general, most of the comments are not problems, if they'll be
addressed later. Note that since this patch introduces a big pile of
old-style code and technical debt it's more than desired that you
address it at some time.
10:24 p.m.
New subject: [libvirt] [PATCH v9 04/13] backup: Parse and output checkpoint XML
On 7/8/19 7:06 AM, Peter Krempa wrote:
On Sat, Jul 06, 2019 at 22:56:04 -0500, Eric Blake wrote:
> Add a new file checkpoint_conf.c that performs the translation to and
> from new XML describing a checkpoint. The code shares a common base
> class with snapshots, since a checkpoint similarly represents the
> domain state at a moment in time. Add some basic testing of round trip
> XML handling through the new code.
>
> Of note - this code intentionally differs from snapshots in that XML
> schema validation is unconditional, rather than based on a public API
> flag. Also, the redefine flag requires the <domain> sub-element to be
> present, rather than catering to historical back-compat to older
> versions.
>
> Signed-off-by: Eric Blake <eblake(a)redhat.com>
> ---
> +static int
> +virDomainCheckpointDiskDefParseXML(xmlNodePtr node,
> + xmlXPathContextPtr ctxt,
> + virDomainCheckpointDiskDefPtr def)
> +{
> + int ret = -1;
> + char *checkpoint = NULL;
> + char *bitmap = NULL;
> + xmlNodePtr saved = ctxt->node;
> +
> + ctxt->node = node;
> +
> + def->name = virXMLPropString(node, "name");
> + if (!def->name) {
> + virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
> + _("missing name from disk checkpoint element"));
'name' is mandatory in the schema for <disk>
True, and I've fixed things to mandate schema compliance, so I'll drop
the unreachable error.
> + goto cleanup;
> + }
> +
> + checkpoint = virXMLPropString(node, "checkpoint");
This attribute seems to be mandatory in the schema [1]
Not quite. It is mandatory if you want checkpoint='no', but optional if
you want to default to checkpoint='bitmap'.
> + if (checkpoint) {
> + def->type = virDomainCheckpointTypeFromString(checkpoint);
> + if (def->type <= 0) {
> + virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
> + _("unknown disk checkpoint setting
'%s'"),
> + checkpoint);
These are also mandated.
Dropping another unreachable error.
> + goto cleanup;
> + }
> + } else {
> + def->type = VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP;
[1] so this should never happen
The schema permits it to be absent; I can enhance the
qemudomaincheckpointxml2xml test to cover that.
> + }
> +
> + bitmap = virXMLPropString(node, "bitmap");
> + if (bitmap) {
> + if (def->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP) {
> + virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
> + _("disk checkpoint bitmap '%s' requires
"
> + "type='bitmap'"),
> + bitmap);
And this is also mandated by the schema.
Correct, dropping another dead block.
> + goto cleanup;
> + }
> + VIR_STEAL_PTR(def->bitmap, bitmap);
> + }
> +
> + ret = 0;
> + cleanup:
> + ctxt->node = saved;
> +
> + VIR_FREE(checkpoint);
> + VIR_FREE(bitmap);
> + if (ret < 0)
> + virDomainCheckpointDiskDefClear(def);
And with a couple of VIR_AUTOFREE and VIR_XPATH_NODE_AUTORESTORE, this
entire cleanup label can disappear.
> + return ret;
> +}
> +
> +/* flags is bitwise-or of virDomainCheckpointParseFlags. If flags
> + * does not include VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE, then caps
> + * and current are ignored.
> + */
> +static virDomainCheckpointDefPtr
> +virDomainCheckpointDefParse(xmlXPathContextPtr ctxt,
> + virCapsPtr caps,
> + virDomainXMLOptionPtr xmlopt,
> + bool *current,
> + unsigned int flags)
> +{
> + virDomainCheckpointDefPtr def = NULL;
> + virDomainCheckpointDefPtr ret = NULL;
> + xmlNodePtr *nodes = NULL;
> + size_t i;
> + int n;
> + char *creation = NULL;
> + int active;
> + char *tmp;
> +
> + if (!(def = virDomainCheckpointDefNew()))
> + return NULL;
> +
> + def->parent.name = virXPathString("string(./name)", ctxt);
> + if (def->parent.name == NULL) {
> + if (flags & VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE) {
> + virReportError(VIR_ERR_XML_ERROR, "%s",
> + _("a redefined checkpoint must have a name"));
> + goto cleanup;
> + }
> + }
> +
> + def->parent.description = virXPathString("string(./description)",
ctxt);
> +
> + if (flags & VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE) {
> + if (virXPathLongLong("string(./creationTime)", ctxt,
> + &def->parent.creationTime) < 0) {
> + virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
> + _("missing creationTime from existing
checkpoint"));
> + goto cleanup;
In v8 I've pointed out that we should not intermix validation of the XML
with the parsing.
If I'm understanding, you want me to populate the entire struct with as
much (or as little) information as possible in the first half of the
function, then in the second half, if PARSE_REDEFINE was set, check that
the information that is optional for normal defines is present for a
redefine? The RNG schema doesn't make that easy to has something
optional by default but mandatory when a flag was passed, so there still
has to be a manual check; for timestamp it might be easy to validate
that a non-zero timestamp was set by the parse code, but it may be
harder for other elements where you are complaining about intermixed
validation. In the meantime, this copies the flow used by snapshots, so
I'm hesitant to rearrange it too much.
> +static virDomainCheckpointDefPtr
> +virDomainCheckpointDefParseNode(xmlDocPtr xml,
> + xmlNodePtr root,
> + virCapsPtr caps,
> + virDomainXMLOptionPtr xmlopt,
> + bool *current,
> + unsigned int flags)
> +{
> + xmlXPathContextPtr ctxt = NULL;
> + virDomainCheckpointDefPtr def = NULL;
> + VIR_AUTOFREE(char *) schema = NULL;
> +
> + if (!virXMLNodeNameEqual(root, "domaincheckpoint")) {
> + virReportError(VIR_ERR_XML_ERROR, "%s",
_("domaincheckpoint"));
> + goto cleanup;
The schema will be able to validate this.
Concur, another dead check dropped.
> +int
> +virDomainCheckpointAlignDisks(virDomainCheckpointDefPtr def)
> +{
> + int ret = -1;
> + virBitmapPtr map = NULL;
> + size_t i;
> + int ndisks;
> + int checkpoint_default = VIR_DOMAIN_CHECKPOINT_TYPE_NONE;
> +
> + if (!def->parent.dom) {
> + virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
> + _("missing domain in checkpoint"));
> + goto cleanup;
Is this possible?
The schema doesn't guarantee it, but it is a coding error if the driver
didn't set the domain. But since we don't use assert(), I don't have
any better way to express that fact.
> + for (i = 0; i < def->parent.dom->ndisks; i++) {
> + virDomainCheckpointDiskDefPtr disk;
> +
> + if (virBitmapIsBitSet(map, i))
> + continue;
> + disk = &def->disks[ndisks++];
> + if (VIR_STRDUP(disk->name, def->parent.dom->disks[i]->dst) <
0)
> + goto cleanup;
> + disk->idx = i;
> +
> + /* Don't checkpoint empty drives */
Without -blockdev you'll also have a problem also with readonly disks as
qemu does not open the actual file for writing and thus writing the
bitmap won't work.
Also ... it doesn't make much sense ... since the bitmap will be empty
forever.
True; I'll tweak things so that readonly disks do not default to having
a checkpoint added.
> +static int
> +virDomainCheckpointDiskDefFormat(virBufferPtr buf,
> + virDomainCheckpointDiskDefPtr disk,
> + unsigned int flags)
> +{
> + if (!disk->name)
> + return 0;
> +
> + virBufferEscapeString(buf, "<disk name='%s'",
disk->name);
> + if (disk->type)
> + virBufferAsprintf(buf, " checkpoint='%s'",
> + virDomainCheckpointTypeToString(disk->type));
> + if (disk->bitmap) {
> + virBufferEscapeString(buf, " bitmap='%s'",
disk->bitmap);
> + if (flags & VIR_DOMAIN_CHECKPOINT_FORMAT_SIZE)
> + virBufferAsprintf(buf, " size='%llu'",
disk->size);
The schema does not tie the size attribute to the presence of the
bitmap name.
I can try to tweak that.
> + }
> + virBufferAddLit(buf, "/>\n");
> + return 0;
> +}
[...]
ACK in general, most of the comments are not problems, if they'll be
addressed later. Note that since this patch introduces a big pile of
old-style code and technical debt it's more than desired that you
address it at some time.
I just re-compared this against snapshot_conf.c, and didn't see obvious
differences where snapshots had moved on to more modern code. Yes,
there's probably things that can be modernized (and my v10 will have a
few more VIR_AUTOFREE), but I don't want to delay this any longer than
necessary. Thanks for the close reviews so far.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org
10:56 p.m.
New subject: [libvirt] [PATCH v9 05/13] backup: Allow for lists of checkpoint objects
Create a new file for managing a list of checkpoint objects, borrowing
heavily from existing virDomainSnapshotObjList paradigms.
Note that while checkpoints definitely have a use case for multiple
children to a single parent (create a base snapshot, create a child
snapshot, revert to the base, then create another child snapshot),
it's harder to predict how checkpoints will play out with reverting to
prior points in time. Thus, in initial use, we may find that in a list
of checkpoints, you never have more than one child. However, as the
snapshot machinery is already generic, it is easier to reuse the
generic machinery that tracks relations between domain moments than it
is to open-code a new list-management scheme just for checkpoints.
Similarly, although the initial checkpoint implementation in qemu will
only support a single current checkpoint, it is conceivable that a
future hypervisor implementation could expose multiple current
checkpoints in differential backup scenarios - the API is prepared for
this by exposing whether a checkpoint is current via the XML
description and via a ListAll filter. But for now, living with the
generic code supporting only a single current checkpoint is easier
than reworking that aspect of the code.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/conf/checkpoint_conf.h | 7 +
src/conf/domain_conf.h | 2 +
src/conf/virconftypes.h | 6 +
src/conf/virdomaincheckpointobjlist.h | 74 ++++++++
src/conf/virdomainobjlist.h | 7 +-
src/conf/Makefile.inc.am | 2 +
src/conf/checkpoint_conf.c | 54 ++++++
src/conf/domain_conf.c | 6 +
src/conf/virdomaincheckpointobjlist.c | 232 ++++++++++++++++++++++++++
src/conf/virdomainmomentobjlist.c | 2 +-
src/conf/virdomainobjlist.c | 11 ++
src/libvirt_private.syms | 18 ++
12 files changed, 419 insertions(+), 2 deletions(-)
create mode 100644 src/conf/virdomaincheckpointobjlist.h
create mode 100644 src/conf/virdomaincheckpointobjlist.c
diff --git a/src/conf/checkpoint_conf.h b/src/conf/checkpoint_conf.h
index 6215549a20..a2482e9e64 100644
--- a/src/conf/checkpoint_conf.h
+++ b/src/conf/checkpoint_conf.h
@@ -83,4 +83,11 @@ char *virDomainCheckpointDefFormat(virDomainCheckpointDefPtr def,
unsigned int flags);
int virDomainCheckpointAlignDisks(virDomainCheckpointDefPtr checkpoint);
+int virDomainCheckpointRedefinePrep(virDomainPtr domain,
+ virDomainObjPtr vm,
+ virDomainCheckpointDefPtr *def,
+ virDomainMomentObjPtr *checkpoint,
+ virDomainXMLOptionPtr xmlopt,
+ bool *update_current);
+
VIR_ENUM_DECL(virDomainCheckpoint);
diff --git a/src/conf/domain_conf.h b/src/conf/domain_conf.h
index c1b5fc1337..bd63215b4c 100644
--- a/src/conf/domain_conf.h
+++ b/src/conf/domain_conf.h
@@ -2561,6 +2561,8 @@ struct _virDomainObj {
bool hasManagedSave;
+ virDomainCheckpointObjListPtr checkpoints;
+
void *privateData;
void (*privateDataFreeFunc)(void *);
diff --git a/src/conf/virconftypes.h b/src/conf/virconftypes.h
index fe3f0af14f..e8e9b6c314 100644
--- a/src/conf/virconftypes.h
+++ b/src/conf/virconftypes.h
@@ -105,6 +105,12 @@ typedef virDomainBlockIoTuneInfo *virDomainBlockIoTuneInfoPtr;
typedef struct _virDomainCheckpointDef virDomainCheckpointDef;
typedef virDomainCheckpointDef *virDomainCheckpointDefPtr;
+typedef struct _virDomainCheckpointObj virDomainCheckpointObj;
+typedef virDomainCheckpointObj *virDomainCheckpointObjPtr;
+
+typedef struct _virDomainCheckpointObjList virDomainCheckpointObjList;
+typedef virDomainCheckpointObjList *virDomainCheckpointObjListPtr;
+
typedef struct _virDomainChrDef virDomainChrDef;
typedef virDomainChrDef *virDomainChrDefPtr;
diff --git a/src/conf/virdomaincheckpointobjlist.h
b/src/conf/virdomaincheckpointobjlist.h
new file mode 100644
index 0000000000..df7ddf621a
--- /dev/null
+++ b/src/conf/virdomaincheckpointobjlist.h
@@ -0,0 +1,74 @@
+/*
+ * virdomaincheckpointobjlist.h: handle a tree of checkpoint objects
+ * (derived from virdomainsnapshotobjlist.h)
+ *
+ * Copyright (C) 2006-2019 Red Hat, Inc.
+ * Copyright (C) 2006-2008 Daniel P. Berrange
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ */
+
+#pragma once
+
+#include "internal.h"
+#include "virdomainmomentobjlist.h"
+#include "virbuffer.h"
+
+virDomainCheckpointObjListPtr virDomainCheckpointObjListNew(void);
+void virDomainCheckpointObjListFree(virDomainCheckpointObjListPtr checkpoints);
+
+virDomainMomentObjPtr virDomainCheckpointAssignDef(virDomainCheckpointObjListPtr
checkpoints,
+ virDomainCheckpointDefPtr def);
+
+virDomainMomentObjPtr virDomainCheckpointFindByName(virDomainCheckpointObjListPtr
checkpoints,
+ const char *name);
+virDomainMomentObjPtr virDomainCheckpointGetCurrent(virDomainCheckpointObjListPtr
checkpoints);
+const char *virDomainCheckpointGetCurrentName(virDomainCheckpointObjListPtr
checkpoints);
+void virDomainCheckpointSetCurrent(virDomainCheckpointObjListPtr checkpoints,
+ virDomainMomentObjPtr checkpoint);
+bool virDomainCheckpointObjListRemove(virDomainCheckpointObjListPtr checkpoints,
+ virDomainMomentObjPtr checkpoint);
+void virDomainCheckpointObjListRemoveAll(virDomainCheckpointObjListPtr checkpoints);
+int virDomainCheckpointForEach(virDomainCheckpointObjListPtr checkpoints,
+ virHashIterator iter,
+ void *data);
+int virDomainCheckpointUpdateRelations(virDomainCheckpointObjListPtr checkpoints);
+int virDomainCheckpointCheckCycles(virDomainCheckpointObjListPtr checkpoints,
+ virDomainCheckpointDefPtr def,
+ const char *domname);
+
+#define VIR_DOMAIN_CHECKPOINT_FILTERS_LEAVES \
+ (VIR_DOMAIN_CHECKPOINT_LIST_LEAVES | \
+ VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES)
+
+#define VIR_DOMAIN_CHECKPOINT_FILTERS_CURRENT \
+ (VIR_DOMAIN_CHECKPOINT_LIST_CURRENT | \
+ VIR_DOMAIN_CHECKPOINT_LIST_NO_CURRENT)
+
+#define VIR_DOMAIN_CHECKPOINT_FILTERS_ALL \
+ (VIR_DOMAIN_CHECKPOINT_FILTERS_LEAVES | \
+ VIR_DOMAIN_CHECKPOINT_FILTERS_CURRENT)
+
+int virDomainListCheckpoints(virDomainCheckpointObjListPtr checkpoints,
+ virDomainMomentObjPtr from,
+ virDomainPtr dom,
+ virDomainCheckpointPtr **objs,
+ unsigned int flags);
+
+static inline virDomainCheckpointDefPtr
+virDomainCheckpointObjGetDef(virDomainMomentObjPtr obj)
+{
+ return (virDomainCheckpointDefPtr) obj->def;
+}
diff --git a/src/conf/virdomainobjlist.h b/src/conf/virdomainobjlist.h
index bf3ab396fa..7d71bc54d0 100644
--- a/src/conf/virdomainobjlist.h
+++ b/src/conf/virdomainobjlist.h
@@ -120,13 +120,18 @@ int virDomainObjListForEach(virDomainObjListPtr doms,
(VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT | \
VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT)
+#define VIR_CONNECT_LIST_DOMAINS_FILTERS_CHECKPOINT \
+ (VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT | \
+ VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT)
+
#define VIR_CONNECT_LIST_DOMAINS_FILTERS_ALL \
(VIR_CONNECT_LIST_DOMAINS_FILTERS_ACTIVE | \
VIR_CONNECT_LIST_DOMAINS_FILTERS_PERSISTENT | \
VIR_CONNECT_LIST_DOMAINS_FILTERS_STATE | \
VIR_CONNECT_LIST_DOMAINS_FILTERS_MANAGEDSAVE | \
VIR_CONNECT_LIST_DOMAINS_FILTERS_AUTOSTART | \
- VIR_CONNECT_LIST_DOMAINS_FILTERS_SNAPSHOT)
+ VIR_CONNECT_LIST_DOMAINS_FILTERS_SNAPSHOT | \
+ VIR_CONNECT_LIST_DOMAINS_FILTERS_CHECKPOINT)
int virDomainObjListCollect(virDomainObjListPtr doms,
virConnectPtr conn,
diff --git a/src/conf/Makefile.inc.am b/src/conf/Makefile.inc.am
index f0135bcb1c..b72ebbbda5 100644
--- a/src/conf/Makefile.inc.am
+++ b/src/conf/Makefile.inc.am
@@ -35,6 +35,8 @@ DOMAIN_CONF_SOURCES = \
conf/numa_conf.c \
conf/numa_conf.h \
conf/virconftypes.h \
+ conf/virdomaincheckpointobjlist.c \
+ conf/virdomaincheckpointobjlist.h \
conf/virdomainobjlist.c \
conf/virdomainobjlist.h \
conf/virdomainmomentobjlist.c \
diff --git a/src/conf/checkpoint_conf.c b/src/conf/checkpoint_conf.c
index d50d63ac0e..aebd3a0d10 100644
--- a/src/conf/checkpoint_conf.c
+++ b/src/conf/checkpoint_conf.c
@@ -36,6 +36,7 @@
#include "virerror.h"
#include "virxml.h"
#include "virstring.h"
+#include "virdomaincheckpointobjlist.h"
#define VIR_FROM_THIS VIR_FROM_DOMAIN_CHECKPOINT
@@ -574,3 +575,56 @@ virDomainCheckpointDefFormat(virDomainCheckpointDefPtr def,
return virBufferContentAndReset(&buf);
}
+
+
+int
+virDomainCheckpointRedefinePrep(virDomainPtr domain,
+ virDomainObjPtr vm,
+ virDomainCheckpointDefPtr *defptr,
+ virDomainMomentObjPtr *chk,
+ virDomainXMLOptionPtr xmlopt,
+ bool *update_current)
+{
+ virDomainCheckpointDefPtr def = *defptr;
+ char uuidstr[VIR_UUID_STRING_BUFLEN];
+ virDomainMomentObjPtr other;
+ virDomainCheckpointDefPtr otherdef = NULL;
+
+ virUUIDFormat(domain->uuid, uuidstr);
+
+ if (virDomainCheckpointCheckCycles(vm->checkpoints, def, vm->def->name) <
0)
+ return -1;
+
+ if (!def->parent.dom ||
+ memcmp(def->parent.dom->uuid, domain->uuid, VIR_UUID_BUFLEN)) {
+ virReportError(VIR_ERR_INVALID_ARG,
+ _("definition for checkpoint %s must use uuid %s"),
+ def->parent.name, uuidstr);
+ return -1;
+ }
+ if (virDomainCheckpointAlignDisks(def) < 0)
+ return -1;
+
+ other = virDomainCheckpointFindByName(vm->checkpoints, def->parent.name);
+ if (other) {
+ otherdef = virDomainCheckpointObjGetDef(other);
+ if (!virDomainDefCheckABIStability(otherdef->parent.dom,
+ def->parent.dom, xmlopt))
+ return -1;
+
+ if (other == virDomainCheckpointGetCurrent(vm->checkpoints)) {
+ *update_current = true;
+ virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
+ }
+
+ /* Drop and rebuild the parent relationship, but keep all
+ * child relations by reusing chk. */
+ virDomainMomentDropParent(other);
+ virObjectUnref(otherdef);
+ other->def = &(*defptr)->parent;
+ *defptr = NULL;
+ *chk = other;
+ }
+
+ return 0;
+}
diff --git a/src/conf/domain_conf.c b/src/conf/domain_conf.c
index 3323c9a5b1..906d799d0a 100644
--- a/src/conf/domain_conf.c
+++ b/src/conf/domain_conf.c
@@ -29,6 +29,7 @@
#include "configmake.h"
#include "internal.h"
#include "virerror.h"
+#include "checkpoint_conf.h"
#include "datatypes.h"
#include "domain_addr.h"
#include "domain_conf.h"
@@ -60,6 +61,7 @@
#include "virhostdev.h"
#include "virmdev.h"
#include "virdomainsnapshotobjlist.h"
+#include "virdomaincheckpointobjlist.h"
#define VIR_FROM_THIS VIR_FROM_DOMAIN
@@ -3485,6 +3487,7 @@ static void virDomainObjDispose(void *obj)
(dom->privateDataFreeFunc)(dom->privateData);
virDomainSnapshotObjListFree(dom->snapshots);
+ virDomainCheckpointObjListFree(dom->checkpoints);
}
virDomainObjPtr
@@ -3514,6 +3517,9 @@ virDomainObjNew(virDomainXMLOptionPtr xmlopt)
if (!(domain->snapshots = virDomainSnapshotObjListNew()))
goto error;
+ if (!(domain->checkpoints = virDomainCheckpointObjListNew()))
+ goto error;
+
virObjectLock(domain);
virDomainObjSetState(domain, VIR_DOMAIN_SHUTOFF,
VIR_DOMAIN_SHUTOFF_UNKNOWN);
diff --git a/src/conf/virdomaincheckpointobjlist.c
b/src/conf/virdomaincheckpointobjlist.c
new file mode 100644
index 0000000000..2bf91f3d5f
--- /dev/null
+++ b/src/conf/virdomaincheckpointobjlist.c
@@ -0,0 +1,232 @@
+/*
+ * virdomaincheckpointobjlist.c: handle a tree of checkpoint objects
+ * (derived from virdomainsnapshotobjlist.c)
+ *
+ * Copyright (C) 2006-2019 Red Hat, Inc.
+ * Copyright (C) 2006-2008 Daniel P. Berrange
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ */
+
+#include <config.h>
+
+#include "internal.h"
+#include "virdomaincheckpointobjlist.h"
+#include "checkpoint_conf.h"
+#include "virlog.h"
+#include "virerror.h"
+#include "datatypes.h"
+#include "virstring.h"
+#include "viralloc.h"
+
+#define VIR_FROM_THIS VIR_FROM_DOMAIN_CHECKPOINT
+
+VIR_LOG_INIT("conf.virdomaincheckpointobjlist");
+
+struct _virDomainCheckpointObjList {
+ virDomainMomentObjListPtr base;
+};
+
+virDomainMomentObjPtr
+virDomainCheckpointAssignDef(virDomainCheckpointObjListPtr checkpoints,
+ virDomainCheckpointDefPtr def)
+{
+ return virDomainMomentAssignDef(checkpoints->base, &def->parent);
+}
+
+
+static bool
+virDomainCheckpointFilter(virDomainMomentObjPtr obj ATTRIBUTE_UNUSED,
+ unsigned int flags)
+{
+ /* For now, we have no further filters than what the common code handles. */
+ virCheckFlags(0, false);
+ return true;
+}
+
+
+virDomainCheckpointObjListPtr
+virDomainCheckpointObjListNew(void)
+{
+ virDomainCheckpointObjListPtr checkpoints;
+
+ if (VIR_ALLOC(checkpoints) < 0)
+ return NULL;
+ checkpoints->base = virDomainMomentObjListNew();
+ if (!checkpoints->base) {
+ VIR_FREE(checkpoints);
+ return NULL;
+ }
+ return checkpoints;
+}
+
+
+void
+virDomainCheckpointObjListFree(virDomainCheckpointObjListPtr checkpoints)
+{
+ if (!checkpoints)
+ return;
+ virDomainMomentObjListFree(checkpoints->base);
+ VIR_FREE(checkpoints);
+}
+
+
+static int
+virDomainCheckpointObjListGetNames(virDomainCheckpointObjListPtr checkpoints,
+ virDomainMomentObjPtr from,
+ char **const names,
+ int maxnames,
+ unsigned int flags)
+{
+ /* We intentionally chose our public flags to match the common flags */
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_ROOTS ==
+ (int) VIR_DOMAIN_MOMENT_LIST_ROOTS);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL ==
+ (int) VIR_DOMAIN_MOMENT_LIST_TOPOLOGICAL);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_LEAVES ==
+ (int) VIR_DOMAIN_MOMENT_LIST_LEAVES);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES ==
+ (int) VIR_DOMAIN_MOMENT_LIST_NO_LEAVES);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_CURRENT ==
+ (int) VIR_DOMAIN_MOMENT_LIST_CURRENT);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_NO_CURRENT ==
+ (int) VIR_DOMAIN_MOMENT_LIST_NO_CURRENT);
+
+ return virDomainMomentObjListGetNames(checkpoints->base, from, names,
+ maxnames, flags,
+ virDomainCheckpointFilter, 0);
+}
+
+
+virDomainMomentObjPtr
+virDomainCheckpointFindByName(virDomainCheckpointObjListPtr checkpoints,
+ const char *name)
+{
+ return virDomainMomentFindByName(checkpoints->base, name);
+}
+
+
+/* Return the current checkpoint, or NULL */
+virDomainMomentObjPtr
+virDomainCheckpointGetCurrent(virDomainCheckpointObjListPtr checkpoints)
+{
+ return virDomainMomentGetCurrent(checkpoints->base);
+}
+
+
+/* Return the current checkpoint's name, or NULL */
+const char *
+virDomainCheckpointGetCurrentName(virDomainCheckpointObjListPtr checkpoints)
+{
+ return virDomainMomentGetCurrentName(checkpoints->base);
+}
+
+
+/* Update the current checkpoint, using NULL if no current remains */
+void
+virDomainCheckpointSetCurrent(virDomainCheckpointObjListPtr checkpoints,
+ virDomainMomentObjPtr checkpoint)
+{
+ virDomainMomentSetCurrent(checkpoints->base, checkpoint);
+}
+
+
+/* Remove checkpoint from the list; return true if it was current */
+bool
+virDomainCheckpointObjListRemove(virDomainCheckpointObjListPtr checkpoints,
+ virDomainMomentObjPtr checkpoint)
+{
+ return virDomainMomentObjListRemove(checkpoints->base, checkpoint);
+}
+
+
+/* Remove all checkpoints tracked in the list */
+void
+virDomainCheckpointObjListRemoveAll(virDomainCheckpointObjListPtr checkpoints)
+{
+ return virDomainMomentObjListRemoveAll(checkpoints->base);
+}
+
+
+int
+virDomainCheckpointForEach(virDomainCheckpointObjListPtr checkpoints,
+ virHashIterator iter,
+ void *data)
+{
+ return virDomainMomentForEach(checkpoints->base, iter, data);
+}
+
+
+/* Populate parent link and child count of all checkpoints, with all
+ * assigned defs having relations starting as 0/NULL. Return 0 on
+ * success, -1 if a parent is missing or if a circular relationship
+ * was requested. */
+int
+virDomainCheckpointUpdateRelations(virDomainCheckpointObjListPtr checkpoints)
+{
+ return virDomainMomentUpdateRelations(checkpoints->base);
+}
+
+
+int
+virDomainCheckpointCheckCycles(virDomainCheckpointObjListPtr checkpoints,
+ virDomainCheckpointDefPtr def,
+ const char *domname)
+{
+ return virDomainMomentCheckCycles(checkpoints->base, &def->parent,
domname);
+}
+
+
+int
+virDomainListCheckpoints(virDomainCheckpointObjListPtr checkpoints,
+ virDomainMomentObjPtr from,
+ virDomainPtr dom,
+ virDomainCheckpointPtr **chks,
+ unsigned int flags)
+{
+ int count = virDomainCheckpointObjListGetNames(checkpoints, from, NULL,
+ 0, flags);
+ virDomainCheckpointPtr *list = NULL;
+ char **names;
+ int ret = -1;
+ size_t i;
+
+ if (!chks || count < 0)
+ return count;
+ if (VIR_ALLOC_N(names, count) < 0 ||
+ VIR_ALLOC_N(list, count + 1) < 0)
+ goto cleanup;
+
+ if (virDomainCheckpointObjListGetNames(checkpoints, from, names, count,
+ flags) < 0)
+ goto cleanup;
+ for (i = 0; i < count; i++)
+ if ((list[i] = virGetDomainCheckpoint(dom, names[i])) == NULL)
+ goto cleanup;
+
+ ret = count;
+ *chks = list;
+
+ cleanup:
+ for (i = 0; i < count; i++)
+ VIR_FREE(names[i]);
+ VIR_FREE(names);
+ if (ret < 0 && list) {
+ for (i = 0; i < count; i++)
+ virObjectUnref(list[i]);
+ VIR_FREE(list);
+ }
+ return ret;
+}
diff --git a/src/conf/virdomainmomentobjlist.c b/src/conf/virdomainmomentobjlist.c
index 55d1db9fb0..098bf1872f 100644
--- a/src/conf/virdomainmomentobjlist.c
+++ b/src/conf/virdomainmomentobjlist.c
@@ -31,8 +31,8 @@
#include "viralloc.h"
/* FIXME: using virObject would allow us to not need this */
-#include "snapshot_conf.h"
#include "virdomainsnapshotobjlist.h"
+#include "virdomaincheckpointobjlist.h"
#define VIR_FROM_THIS VIR_FROM_DOMAIN
diff --git a/src/conf/virdomainobjlist.c b/src/conf/virdomainobjlist.c
index d58d25f847..d640da6205 100644
--- a/src/conf/virdomainobjlist.c
+++ b/src/conf/virdomainobjlist.c
@@ -25,12 +25,14 @@
#include "internal.h"
#include "datatypes.h"
#include "virdomainobjlist.h"
+#include "checkpoint_conf.h"
#include "snapshot_conf.h"
#include "viralloc.h"
#include "virfile.h"
#include "virlog.h"
#include "virstring.h"
#include "virdomainsnapshotobjlist.h"
+#include "virdomaincheckpointobjlist.h"
#define VIR_FROM_THIS VIR_FROM_DOMAIN
@@ -887,6 +889,15 @@ virDomainObjMatchFilter(virDomainObjPtr vm,
return false;
}
+ /* filter by checkpoint existence */
+ if (MATCH(VIR_CONNECT_LIST_DOMAINS_FILTERS_CHECKPOINT)) {
+ int nchk = virDomainListCheckpoints(vm->checkpoints, NULL, NULL,
+ NULL, 0);
+ if (!((MATCH(VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT) && nchk > 0) ||
+ (MATCH(VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT) && nchk <= 0)))
+ return false;
+ }
+
return true;
}
#undef MATCH
diff --git a/src/libvirt_private.syms b/src/libvirt_private.syms
index a7e508f217..28f654bbf8 100644
--- a/src/libvirt_private.syms
+++ b/src/libvirt_private.syms
@@ -70,9 +70,12 @@ virCapabilitiesSetNetPrefix;
# conf/checkpoint_conf.h
+virDomainCheckpointAlignDisks;
virDomainCheckpointDefFormat;
virDomainCheckpointDefNew;
virDomainCheckpointDefParseString;
+virDomainCheckpointFormatConvertXMLFlags;
+virDomainCheckpointRedefinePrep;
virDomainCheckpointTypeFromString;
virDomainCheckpointTypeToString;
@@ -977,6 +980,21 @@ virChrdevFree;
virChrdevOpen;
+# conf/virdomaincheckpointobjlist.h
+virDomainCheckpointAssignDef;
+virDomainCheckpointFindByName;
+virDomainCheckpointForEach;
+virDomainCheckpointGetCurrent;
+virDomainCheckpointGetCurrentName;
+virDomainCheckpointObjListFree;
+virDomainCheckpointObjListNew;
+virDomainCheckpointObjListRemove;
+virDomainCheckpointObjListRemoveAll;
+virDomainCheckpointSetCurrent;
+virDomainCheckpointUpdateRelations;
+virDomainListCheckpoints;
+
+
# conf/virdomainmomentobjlist.h
virDomainMomentDropChildren;
virDomainMomentDropParent;
--
2.20.1
7:40 a.m.
New subject: [libvirt] [PATCH v9 05/13] backup: Allow for lists of checkpoint objects
On Sat, Jul 06, 2019 at 22:56:05 -0500, Eric Blake wrote:
Create a new file for managing a list of checkpoint objects,
borrowing
heavily from existing virDomainSnapshotObjList paradigms.
Note that while checkpoints definitely have a use case for multiple
snapshots?
children to a single parent (create a base snapshot, create a child
snapshot, revert to the base, then create another child snapshot),
it's harder to predict how checkpoints will play out with reverting to
prior points in time. Thus, in initial use, we may find that in a list
of checkpoints, you never have more than one child. However, as the
snapshot machinery is already generic, it is easier to reuse the
generic machinery that tracks relations between domain moments than it
is to open-code a new list-management scheme just for checkpoints.
Similarly, although the initial checkpoint implementation in qemu will
only support a single current checkpoint, it is conceivable that a
future hypervisor implementation could expose multiple current
checkpoints in differential backup scenarios - the API is prepared for
this by exposing whether a checkpoint is current via the XML
description and via a ListAll filter. But for now, living with the
generic code supporting only a single current checkpoint is easier
than reworking that aspect of the code.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
[...]
diff --git a/src/conf/virdomaincheckpointobjlist.c
b/src/conf/virdomaincheckpointobjlist.c
new file mode 100644
index 0000000000..2bf91f3d5f
--- /dev/null
+++ b/src/conf/virdomaincheckpointobjlist.c
@@ -0,0 +1,232 @@
[...]
+static int
+virDomainCheckpointObjListGetNames(virDomainCheckpointObjListPtr checkpoints,
+ virDomainMomentObjPtr from,
+ char **const names,
+ int maxnames,
+ unsigned int flags)
+{
+ /* We intentionally chose our public flags to match the common flags */
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_ROOTS ==
+ (int) VIR_DOMAIN_MOMENT_LIST_ROOTS);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL ==
+ (int) VIR_DOMAIN_MOMENT_LIST_TOPOLOGICAL);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_LEAVES ==
+ (int) VIR_DOMAIN_MOMENT_LIST_LEAVES);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES ==
+ (int) VIR_DOMAIN_MOMENT_LIST_NO_LEAVES);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_CURRENT ==
+ (int) VIR_DOMAIN_MOMENT_LIST_CURRENT);
+ verify(VIR_DOMAIN_CHECKPOINT_LIST_NO_CURRENT ==
+ (int) VIR_DOMAIN_MOMENT_LIST_NO_CURRENT);
In v8 I asked for these to be put where VIR_DOMAIN_CHECKPOINT_LIST_* are
defined rather than randomly into the code.
ACK with the above addressed.
10:56 p.m.
New subject: [libvirt] [PATCH v9 06/13] backup: Add new domain:checkpoint access control
Creating a checkpoint does not modify guest-visible state,
but does modify host resources. Rather than reuse existing
domain:write, domain:block_write, or domain:snapshot access
controls, it seems better to introduce a new access control
specific to tasks related to checkpoints and incremental
backups of guest disk state.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
src/access/viraccessperm.h | 6 ++++++
src/access/viraccessperm.c | 3 ++-
2 files changed, 8 insertions(+), 1 deletion(-)
diff --git a/src/access/viraccessperm.h b/src/access/viraccessperm.h
index d4b9c69c1e..a42512d5e0 100644
--- a/src/access/viraccessperm.h
+++ b/src/access/viraccessperm.h
@@ -186,6 +186,12 @@ typedef enum {
*/
VIR_ACCESS_PERM_DOMAIN_MIGRATE, /* Host migration */
+ /**
+ * @desc: Checkpoint domain
+ * @message: Checkpointing domain requires authorization
+ */
+ VIR_ACCESS_PERM_DOMAIN_CHECKPOINT, /* Checkpoint disks */
+
/**
* @desc: Snapshot domain
* @message: Snapshotting domain requires authorization
diff --git a/src/access/viraccessperm.c b/src/access/viraccessperm.c
index 74993e9f29..33db7752b6 100644
--- a/src/access/viraccessperm.c
+++ b/src/access/viraccessperm.c
@@ -39,7 +39,8 @@ VIR_ENUM_IMPL(virAccessPermDomain,
"getattr", "read", "write",
"read_secure",
"start", "stop", "reset",
"save", "delete",
- "migrate", "snapshot", "suspend",
"hibernate", "core_dump", "pm_control",
+ "migrate", "checkpoint", "snapshot",
"suspend", "hibernate",
+ "core_dump", "pm_control",
"init_control", "inject_nmi", "send_input",
"send_signal",
"fs_trim", "fs_freeze",
"block_read", "block_write", "mem_read",
--
2.20.1
10:56 p.m.
New subject: [libvirt] [PATCH v9 07/13] backup: Implement checkpoint APIs for remote driver
The remote code generator had to be taught about the new
virDomainCheckpointPtr type, at which point the remote driver code for
checkpoints can be generated.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
src/remote/remote_daemon_dispatch.c | 20 +++++
src/remote/remote_driver.c | 24 +++++-
src/remote/remote_protocol.x | 123 +++++++++++++++++++++++++++-
src/remote_protocol-structs | 69 ++++++++++++++++
src/rpc/gendispatch.pl | 32 ++++----
5 files changed, 252 insertions(+), 16 deletions(-)
diff --git a/src/remote/remote_daemon_dispatch.c b/src/remote/remote_daemon_dispatch.c
index 856c5e48e7..444c03a644 100644
--- a/src/remote/remote_daemon_dispatch.c
+++ b/src/remote/remote_daemon_dispatch.c
@@ -90,6 +90,7 @@ static virStorageVolPtr get_nonnull_storage_vol(virConnectPtr conn,
remote_nonnu
static virSecretPtr get_nonnull_secret(virConnectPtr conn, remote_nonnull_secret
secret);
static virNWFilterPtr get_nonnull_nwfilter(virConnectPtr conn, remote_nonnull_nwfilter
nwfilter);
static virNWFilterBindingPtr get_nonnull_nwfilter_binding(virConnectPtr conn,
remote_nonnull_nwfilter_binding binding);
+static virDomainCheckpointPtr get_nonnull_domain_checkpoint(virDomainPtr dom,
remote_nonnull_domain_checkpoint checkpoint);
static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr dom,
remote_nonnull_domain_snapshot snapshot);
static virNodeDevicePtr get_nonnull_node_device(virConnectPtr conn,
remote_nonnull_node_device dev);
static int make_nonnull_domain(remote_nonnull_domain *dom_dst, virDomainPtr dom_src)
ATTRIBUTE_RETURN_CHECK;
@@ -102,6 +103,7 @@ static int make_nonnull_node_device(remote_nonnull_node_device
*dev_dst, virNode
static int make_nonnull_secret(remote_nonnull_secret *secret_dst, virSecretPtr
secret_src) ATTRIBUTE_RETURN_CHECK;
static int make_nonnull_nwfilter(remote_nonnull_nwfilter *net_dst, virNWFilterPtr
nwfilter_src) ATTRIBUTE_RETURN_CHECK;
static int make_nonnull_nwfilter_binding(remote_nonnull_nwfilter_binding *binding_dst,
virNWFilterBindingPtr binding_src) ATTRIBUTE_RETURN_CHECK;
+static int make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint
*checkpoint_dst, virDomainCheckpointPtr checkpoint_src) ATTRIBUTE_RETURN_CHECK;
static int make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *snapshot_dst,
virDomainSnapshotPtr snapshot_src) ATTRIBUTE_RETURN_CHECK;
static int
@@ -7301,6 +7303,12 @@ get_nonnull_nwfilter_binding(virConnectPtr conn,
remote_nonnull_nwfilter_binding
return virGetNWFilterBinding(conn, binding.portdev, binding.filtername);
}
+static virDomainCheckpointPtr
+get_nonnull_domain_checkpoint(virDomainPtr dom, remote_nonnull_domain_checkpoint
checkpoint)
+{
+ return virGetDomainCheckpoint(dom, checkpoint.name);
+}
+
static virDomainSnapshotPtr
get_nonnull_domain_snapshot(virDomainPtr dom, remote_nonnull_domain_snapshot snapshot)
{
@@ -7421,6 +7429,18 @@ make_nonnull_nwfilter_binding(remote_nonnull_nwfilter_binding
*binding_dst, virN
return 0;
}
+static int
+make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint *checkpoint_dst,
virDomainCheckpointPtr checkpoint_src)
+{
+ if (VIR_STRDUP(checkpoint_dst->name, checkpoint_src->name) < 0)
+ return -1;
+ if (make_nonnull_domain(&checkpoint_dst->dom, checkpoint_src->domain) <
0) {
+ VIR_FREE(checkpoint_dst->name);
+ return -1;
+ }
+ return 0;
+}
+
static int
make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *snapshot_dst,
virDomainSnapshotPtr snapshot_src)
{
diff --git a/src/remote/remote_driver.c b/src/remote/remote_driver.c
index 925ada1cac..72c2336b7a 100644
--- a/src/remote/remote_driver.c
+++ b/src/remote/remote_driver.c
@@ -146,6 +146,7 @@ static virStoragePoolPtr get_nonnull_storage_pool(virConnectPtr conn,
remote_non
static virStorageVolPtr get_nonnull_storage_vol(virConnectPtr conn,
remote_nonnull_storage_vol vol);
static virNodeDevicePtr get_nonnull_node_device(virConnectPtr conn,
remote_nonnull_node_device dev);
static virSecretPtr get_nonnull_secret(virConnectPtr conn, remote_nonnull_secret
secret);
+static virDomainCheckpointPtr get_nonnull_domain_checkpoint(virDomainPtr domain,
remote_nonnull_domain_checkpoint checkpoint);
static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr domain,
remote_nonnull_domain_snapshot snapshot);
static void make_nonnull_domain(remote_nonnull_domain *dom_dst, virDomainPtr dom_src);
static void make_nonnull_network(remote_nonnull_network *net_dst, virNetworkPtr
net_src);
@@ -158,6 +159,7 @@ make_nonnull_node_device(remote_nonnull_node_device *dev_dst,
virNodeDevicePtr d
static void make_nonnull_secret(remote_nonnull_secret *secret_dst, virSecretPtr
secret_src);
static void make_nonnull_nwfilter(remote_nonnull_nwfilter *nwfilter_dst, virNWFilterPtr
nwfilter_src);
static void make_nonnull_nwfilter_binding(remote_nonnull_nwfilter_binding *binding_dst,
virNWFilterBindingPtr binding_src);
+static void make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint
*checkpoint_dst, virDomainCheckpointPtr checkpoint_src);
static void make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *snapshot_dst,
virDomainSnapshotPtr snapshot_src);
/*----------------------------------------------------------------------*/
@@ -8242,6 +8244,12 @@ get_nonnull_nwfilter_binding(virConnectPtr conn,
remote_nonnull_nwfilter_binding
return virGetNWFilterBinding(conn, binding.portdev, binding.filtername);
}
+static virDomainCheckpointPtr
+get_nonnull_domain_checkpoint(virDomainPtr domain, remote_nonnull_domain_checkpoint
checkpoint)
+{
+ return virGetDomainCheckpoint(domain, checkpoint.name);
+}
+
static virDomainSnapshotPtr
get_nonnull_domain_snapshot(virDomainPtr domain, remote_nonnull_domain_snapshot
snapshot)
{
@@ -8324,6 +8332,13 @@ make_nonnull_nwfilter_binding(remote_nonnull_nwfilter_binding
*binding_dst, virN
binding_dst->filtername = binding_src->filtername;
}
+static void
+make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint *checkpoint_dst,
virDomainCheckpointPtr checkpoint_src)
+{
+ checkpoint_dst->name = checkpoint_src->name;
+ make_nonnull_domain(&checkpoint_dst->dom, checkpoint_src->domain);
+}
+
static void
make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *snapshot_dst,
virDomainSnapshotPtr snapshot_src)
{
@@ -8573,7 +8588,14 @@ static virHypervisorDriver hypervisor_driver = {
.connectCompareHypervisorCPU = remoteConnectCompareHypervisorCPU, /* 4.4.0 */
.connectBaselineHypervisorCPU = remoteConnectBaselineHypervisorCPU, /* 4.4.0 */
.nodeGetSEVInfo = remoteNodeGetSEVInfo, /* 4.5.0 */
- .domainGetLaunchSecurityInfo = remoteDomainGetLaunchSecurityInfo /* 4.5.0 */
+ .domainGetLaunchSecurityInfo = remoteDomainGetLaunchSecurityInfo, /* 4.5.0 */
+ .domainCheckpointCreateXML = remoteDomainCheckpointCreateXML, /* 5.6.0 */
+ .domainCheckpointGetXMLDesc = remoteDomainCheckpointGetXMLDesc, /* 5.6.0 */
+ .domainListAllCheckpoints = remoteDomainListAllCheckpoints, /* 5.6.0 */
+ .domainCheckpointListAllChildren = remoteDomainCheckpointListAllChildren, /* 5.6.0
*/
+ .domainCheckpointLookupByName = remoteDomainCheckpointLookupByName, /* 5.6.0 */
+ .domainCheckpointGetParent = remoteDomainCheckpointGetParent, /* 5.6.0 */
+ .domainCheckpointDelete = remoteDomainCheckpointDelete, /* 5.6.0 */
};
static virNetworkDriver network_driver = {
diff --git a/src/remote/remote_protocol.x b/src/remote/remote_protocol.x
index 2e45b5cef0..2f91bd1921 100644
--- a/src/remote/remote_protocol.x
+++ b/src/remote/remote_protocol.x
@@ -140,6 +140,9 @@ const REMOTE_AUTH_TYPE_LIST_MAX = 20;
/* Upper limit on list of memory stats */
const REMOTE_DOMAIN_MEMORY_STATS_MAX = 1024;
+/* Upper limit on lists of domain checkpoints. */
+const REMOTE_DOMAIN_CHECKPOINT_LIST_MAX = 16384;
+
/* Upper limit on lists of domain snapshots. */
const REMOTE_DOMAIN_SNAPSHOT_LIST_MAX = 16384;
@@ -336,6 +339,12 @@ struct remote_nonnull_secret {
remote_nonnull_string usageID;
};
+/* A checkpoint which may not be NULL. */
+struct remote_nonnull_domain_checkpoint {
+ remote_nonnull_string name;
+ remote_nonnull_domain dom;
+};
+
/* A snapshot which may not be NULL. */
struct remote_nonnull_domain_snapshot {
remote_nonnull_string name;
@@ -3649,6 +3658,70 @@ struct remote_network_port_delete_args {
unsigned int flags;
};
+struct remote_domain_checkpoint_create_xml_args {
+ remote_nonnull_domain dom;
+ remote_nonnull_string xml_desc;
+ unsigned int flags;
+};
+
+struct remote_domain_checkpoint_create_xml_ret {
+ remote_nonnull_domain_checkpoint checkpoint;
+};
+
+struct remote_domain_checkpoint_get_xml_desc_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ unsigned int flags;
+};
+
+struct remote_domain_checkpoint_get_xml_desc_ret {
+ remote_nonnull_string xml;
+};
+
+struct remote_domain_list_all_checkpoints_args {
+ remote_nonnull_domain dom;
+ int need_results;
+ unsigned int flags;
+};
+
+struct remote_domain_list_all_checkpoints_ret { /* insert@1 */
+ remote_nonnull_domain_checkpoint
checkpoints<REMOTE_DOMAIN_CHECKPOINT_LIST_MAX>;
+ int ret;
+};
+
+struct remote_domain_checkpoint_list_all_children_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ int need_results;
+ unsigned int flags;
+};
+
+struct remote_domain_checkpoint_list_all_children_ret { /* insert@1 */
+ remote_nonnull_domain_checkpoint
checkpoints<REMOTE_DOMAIN_CHECKPOINT_LIST_MAX>;
+ int ret;
+};
+
+struct remote_domain_checkpoint_lookup_by_name_args {
+ remote_nonnull_domain dom;
+ remote_nonnull_string name;
+ unsigned int flags;
+};
+
+struct remote_domain_checkpoint_lookup_by_name_ret {
+ remote_nonnull_domain_checkpoint checkpoint;
+};
+
+struct remote_domain_checkpoint_get_parent_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ unsigned int flags;
+};
+
+struct remote_domain_checkpoint_get_parent_ret {
+ remote_nonnull_domain_checkpoint parent;
+};
+
+struct remote_domain_checkpoint_delete_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ unsigned int flags;
+};
/*----- Protocol. -----*/
@@ -6463,5 +6536,53 @@ enum remote_procedure {
* @generate: both
* @acl: network_port:delete
*/
- REMOTE_PROC_NETWORK_PORT_DELETE = 410
+ REMOTE_PROC_NETWORK_PORT_DELETE = 410,
+
+ /**
+ * @generate: both
+ * @acl: domain:checkpoint
+ * @acl: domain:fs_freeze:VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE
+ */
+ REMOTE_PROC_DOMAIN_CHECKPOINT_CREATE_XML = 411,
+
+ /**
+ * @generate: both
+ * @acl: domain:read
+ * @acl: domain:read_secure:VIR_DOMAIN_CHECKPOINT_XML_SECURE
+ */
+ REMOTE_PROC_DOMAIN_CHECKPOINT_GET_XML_DESC = 412,
+
+ /**
+ * @generate: both
+ * @priority: high
+ * @acl: domain:read
+ */
+ REMOTE_PROC_DOMAIN_LIST_ALL_CHECKPOINTS = 413,
+
+ /**
+ * @generate: both
+ * @priority: high
+ * @acl: domain:read
+ */
+ REMOTE_PROC_DOMAIN_CHECKPOINT_LIST_ALL_CHILDREN = 414,
+
+ /**
+ * @generate: both
+ * @priority: high
+ * @acl: domain:read
+ */
+ REMOTE_PROC_DOMAIN_CHECKPOINT_LOOKUP_BY_NAME = 415,
+
+ /**
+ * @generate: both
+ * @priority: high
+ * @acl: domain:read
+ */
+ REMOTE_PROC_DOMAIN_CHECKPOINT_GET_PARENT = 416,
+
+ /**
+ * @generate: both
+ * @acl: domain:checkpoint
+ */
+ REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 417
};
diff --git a/src/remote_protocol-structs b/src/remote_protocol-structs
index 2398494520..a42b4a9671 100644
--- a/src/remote_protocol-structs
+++ b/src/remote_protocol-structs
@@ -50,6 +50,10 @@ struct remote_nonnull_secret {
int usageType;
remote_nonnull_string usageID;
};
+struct remote_nonnull_domain_checkpoint {
+ remote_nonnull_string name;
+ remote_nonnull_domain dom;
+};
struct remote_nonnull_domain_snapshot {
remote_nonnull_string name;
remote_nonnull_domain dom;
@@ -3043,6 +3047,64 @@ struct remote_network_port_delete_args {
remote_nonnull_network_port port;
u_int flags;
};
+struct remote_domain_checkpoint_create_xml_args {
+ remote_nonnull_domain dom;
+ remote_nonnull_string xml_desc;
+ u_int flags;
+};
+struct remote_domain_checkpoint_create_xml_ret {
+ remote_nonnull_domain_checkpoint checkpoint;
+};
+struct remote_domain_checkpoint_get_xml_desc_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ u_int flags;
+};
+struct remote_domain_checkpoint_get_xml_desc_ret {
+ remote_nonnull_string xml;
+};
+struct remote_domain_list_all_checkpoints_args {
+ remote_nonnull_domain dom;
+ int need_results;
+ u_int flags;
+};
+struct remote_domain_list_all_checkpoints_ret {
+ struct {
+ u_int checkpoints_len;
+ remote_nonnull_domain_checkpoint * checkpoints_val;
+ } checkpoints;
+ int ret;
+};
+struct remote_domain_checkpoint_list_all_children_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ int need_results;
+ u_int flags;
+};
+struct remote_domain_checkpoint_list_all_children_ret {
+ struct {
+ u_int checkpoints_len;
+ remote_nonnull_domain_checkpoint * checkpoints_val;
+ } checkpoints;
+ int ret;
+};
+struct remote_domain_checkpoint_lookup_by_name_args {
+ remote_nonnull_domain dom;
+ remote_nonnull_string name;
+ u_int flags;
+};
+struct remote_domain_checkpoint_lookup_by_name_ret {
+ remote_nonnull_domain_checkpoint checkpoint;
+};
+struct remote_domain_checkpoint_get_parent_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ u_int flags;
+};
+struct remote_domain_checkpoint_get_parent_ret {
+ remote_nonnull_domain_checkpoint parent;
+};
+struct remote_domain_checkpoint_delete_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ u_int flags;
+};
enum remote_procedure {
REMOTE_PROC_CONNECT_OPEN = 1,
REMOTE_PROC_CONNECT_CLOSE = 2,
@@ -3454,4 +3516,11 @@ enum remote_procedure {
REMOTE_PROC_NETWORK_PORT_SET_PARAMETERS = 408,
REMOTE_PROC_NETWORK_PORT_GET_XML_DESC = 409,
REMOTE_PROC_NETWORK_PORT_DELETE = 410,
+ REMOTE_PROC_DOMAIN_CHECKPOINT_CREATE_XML = 411,
+ REMOTE_PROC_DOMAIN_CHECKPOINT_GET_XML_DESC = 412,
+ REMOTE_PROC_DOMAIN_LIST_ALL_CHECKPOINTS = 413,
+ REMOTE_PROC_DOMAIN_CHECKPOINT_LIST_ALL_CHILDREN = 414,
+ REMOTE_PROC_DOMAIN_CHECKPOINT_LOOKUP_BY_NAME = 415,
+ REMOTE_PROC_DOMAIN_CHECKPOINT_GET_PARENT = 416,
+ REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 417,
};
diff --git a/src/rpc/gendispatch.pl b/src/rpc/gendispatch.pl
index f683e711ce..4e548e14cd 100755
--- a/src/rpc/gendispatch.pl
+++ b/src/rpc/gendispatch.pl
@@ -58,6 +58,7 @@ sub fixup_name {
$name =~ s/Nwfilter/NWFilter/;
$name =~ s/Xml$/XML/;
+ $name =~ s/Xml2$/XML2/;
$name =~ s/Uri$/URI/;
$name =~ s/Uuid$/UUID/;
$name =~ s/Id$/ID/;
@@ -567,18 +568,20 @@ elsif ($mode eq "server") {
push(@args_list, "$2");
push(@free_list,
" virObjectUnref($2);");
- } elsif ($args_member =~ m/^remote_nonnull_domain_snapshot (\S+);$/) {
+ } elsif ($args_member =~ m/^remote_nonnull_domain_(checkpoint|snapshot)
(\S+);$/) {
+ my $type_name = name_to_TypeName($1);
+
push(@vars_list, "virDomainPtr dom = NULL");
- push(@vars_list, "virDomainSnapshotPtr snapshot = NULL");
+ push(@vars_list, "virDomain${type_name}Ptr ${1} = NULL");
push(@getters_list,
- " if (!(dom = get_nonnull_domain($conn,
args->${1}.dom)))\n" .
+ " if (!(dom = get_nonnull_domain($conn,
args->${2}.dom)))\n" .
" goto cleanup;\n" .
"\n" .
- " if (!(snapshot = get_nonnull_domain_snapshot(dom,
args->${1})))\n" .
+ " if (!($1 = get_nonnull_domain_${1}(dom,
args->$2)))\n" .
" goto cleanup;\n");
- push(@args_list, "snapshot");
+ push(@args_list, "$1");
push(@free_list,
- " virObjectUnref(snapshot);\n" .
+ " virObjectUnref($1);\n" .
" virObjectUnref(dom);");
} elsif ($args_member =~ m/^(?:(?:admin|remote)_string|remote_uuid)
(\S+)<\S+>;/) {
push(@args_list, $conn) if !@args_list;
@@ -722,7 +725,7 @@ elsif ($mode eq "server") {
if (!$modern_ret_as_list) {
push(@ret_list, "ret->$3 = tmp.$3;");
}
- } elsif ($ret_member =~
m/(?:admin|remote)_nonnull_(secret|nwfilter|nwfilter_binding|node_device|interface|network|network_port|storage_vol|storage_pool|domain_snapshot|domain|server|client)
(\S+)<(\S+)>;/) {
+ } elsif ($ret_member =~
m/(?:admin|remote)_nonnull_(secret|nwfilter|nwfilter_binding|node_device|interface|network|network_port|storage_vol|storage_pool|domain_checkpoint|domain_snapshot|domain|server|client)
(\S+)<(\S+)>;/) {
$modern_ret_struct_name = $1;
$single_ret_list_error_msg_type = $1;
$single_ret_list_name = $2;
@@ -780,7 +783,7 @@ elsif ($mode eq "server") {
$single_ret_var = $1;
$single_ret_by_ref = 0;
$single_ret_check = " == NULL";
- } elsif ($ret_member =~
m/^remote_nonnull_(domain|network|network_port|storage_pool|storage_vol|interface|node_device|secret|nwfilter|nwfilter_binding|domain_snapshot)
(\S+);/) {
+ } elsif ($ret_member =~
m/^remote_nonnull_(domain|network|network_port|storage_pool|storage_vol|interface|node_device|secret|nwfilter|nwfilter_binding|domain_checkpoint|domain_snapshot)
(\S+);/) {
my $type_name = name_to_TypeName($1);
if ($call->{ProcName} eq "DomainCreateWithFlags") {
@@ -1328,13 +1331,14 @@ elsif ($mode eq "client") {
$priv_src = "dev->conn";
push(@args_list, "virNodeDevicePtr dev");
push(@setters_list, "args.name = dev->name;");
- } elsif ($args_member =~
m/^remote_nonnull_(domain|network|network_port|storage_pool|storage_vol|interface|secret|nwfilter|nwfilter_binding|domain_snapshot)
(\S+);/) {
+ } elsif ($args_member =~
m/^remote_nonnull_(domain|network|network_port|storage_pool|storage_vol|interface|secret|nwfilter|nwfilter_binding|domain_checkpoint|domain_snapshot)
(\S+);/) {
my $name = $1;
my $arg_name = $2;
my $type_name = name_to_TypeName($name);
if ($is_first_arg) {
- if ($name eq "domain_snapshot") {
+ if ($name eq "domain_snapshot" ||
+ $name eq "domain_checkpoint") {
$priv_src = "$arg_name->domain->conn";
} elsif ($name eq "network_port") {
$priv_src = "$arg_name->net->conn";
@@ -1523,7 +1527,7 @@ elsif ($mode eq "client") {
}
push(@ret_list, "memcpy(result->$3, ret.$3,
sizeof(result->$3));");
- } elsif ($ret_member =~
m/(?:admin|remote)_nonnull_(secret|nwfilter|nwfilter_binding|node_device|interface|network|network_port|storage_vol|storage_pool|domain_snapshot|domain|server|client)
(\S+)<(\S+)>;/) {
+ } elsif ($ret_member =~
m/(?:admin|remote)_nonnull_(secret|nwfilter|nwfilter_binding|node_device|interface|network|network_port|storage_vol|storage_pool|domain_checkpoint|domain_snapshot|domain|server|client)
(\S+)<(\S+)>;/) {
my $proc_name = name_to_TypeName($1);
if ($structprefix eq "admin") {
@@ -1576,7 +1580,7 @@ elsif ($mode eq "client") {
push(@ret_list, "VIR_FREE(ret.$1);");
$single_ret_var = "char *rv = NULL";
$single_ret_type = "char *";
- } elsif ($ret_member =~
m/^remote_nonnull_(domain|network|network_port|storage_pool|storage_vol|node_device|interface|secret|nwfilter|nwfilter_binding|domain_snapshot)
(\S+);/) {
+ } elsif ($ret_member =~
m/^remote_nonnull_(domain|network|network_port|storage_pool|storage_vol|node_device|interface|secret|nwfilter|nwfilter_binding|domain_checkpoint|domain_snapshot)
(\S+);/) {
my $name = $1;
my $arg_name = $2;
my $type_name = name_to_TypeName($name);
@@ -1590,7 +1594,7 @@ elsif ($mode eq "client") {
$single_ret_var = "int rv = -1";
$single_ret_type = "int";
} else {
- if ($name eq "domain_snapshot") {
+ if ($name =~ m/^domain_.*/) {
my $dom = "$priv_src";
$dom =~ s/->conn//;
push(@ret_list, "rv = get_nonnull_$name($dom,
ret.$arg_name);");
@@ -1934,7 +1938,7 @@ elsif ($mode eq "client") {
print " }\n";
print "\n";
} elsif ($modern_ret_as_list) {
- if ($modern_ret_struct_name =~ m/domain_snapshot|client/) {
+ if ($modern_ret_struct_name =~ m/domain_checkpoint|domain_snapshot|client/)
{
$priv_src =~ s/->conn//;
}
print " if (result) {\n";
--
2.20.1
10:56 p.m.
New subject: [libvirt] [PATCH v9 08/13] backup: Implement virsh support for checkpoints
Introduce a bunch of new virsh commands for managing checkpoints in
isolation. More commands are needed for performing incremental
backups, but these commands were easy to implement by modeling heavily
after virsh-snapshot.c. There is no need for checkpoint-revert or
checkpoint-current since those snapshot APIs have no checkpoint
counterpart. Similarly, it is not necessary to change which
checkpoint is current when redefining from XML, since checkpoints
expose whether they are current in the public XML (rather than the way
snapshots did it behind the scenese). checkpoint-list is a bit
simpler, in part because we don't have to cater to back-compat to
older API. checkpoint-info is a bit trickier, because it requires
parsing XML (maybe we'll want virDomainCheckpointIsCurrent() as an API
after all).
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
tools/virsh-checkpoint.h | 26 +
tools/virsh-completer.h | 4 +
tools/virsh-util.h | 3 +
tools/virsh.h | 1 +
po/POTFILES | 1 +
tools/Makefile.am | 1 +
tools/virsh-checkpoint.c | 1226 ++++++++++++++++++++++++++++++++++
tools/virsh-completer.c | 51 ++
tools/virsh-domain-monitor.c | 23 +
tools/virsh-domain.c | 7 +
tools/virsh-util.c | 11 +
tools/virsh.c | 2 +
tools/virsh.pod | 221 +++++-
13 files changed, 1570 insertions(+), 7 deletions(-)
create mode 100644 tools/virsh-checkpoint.h
create mode 100644 tools/virsh-checkpoint.c
diff --git a/tools/virsh-checkpoint.h b/tools/virsh-checkpoint.h
new file mode 100644
index 0000000000..7cc998638f
--- /dev/null
+++ b/tools/virsh-checkpoint.h
@@ -0,0 +1,26 @@
+/*
+ * virsh-checkpoint.h: Commands to manage domain checkpoints
+ *
+ * Copyright (C) 2005-2019 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ *
+ */
+
+#pragma once
+
+#include "virsh.h"
+
+extern const vshCmdDef checkpointCmds[];
diff --git a/tools/virsh-completer.h b/tools/virsh-completer.h
index 9b3951f4fd..fc377f798b 100644
--- a/tools/virsh-completer.h
+++ b/tools/virsh-completer.h
@@ -78,6 +78,10 @@ char ** virshSecretUUIDCompleter(vshControl *ctl,
const vshCmd *cmd,
unsigned int flags);
+char ** virshCheckpointNameCompleter(vshControl *ctl,
+ const vshCmd *cmd,
+ unsigned int flags);
+
char ** virshSnapshotNameCompleter(vshControl *ctl,
const vshCmd *cmd,
unsigned int flags);
diff --git a/tools/virsh-util.h b/tools/virsh-util.h
index 55520302ff..9005aa9d36 100644
--- a/tools/virsh-util.h
+++ b/tools/virsh-util.h
@@ -42,6 +42,9 @@ virshCommandOptDomain(vshControl *ctl,
void
virshDomainFree(virDomainPtr dom);
+void
+virshDomainCheckpointFree(virDomainCheckpointPtr chk);
+
void
virshDomainSnapshotFree(virDomainSnapshotPtr snap);
diff --git a/tools/virsh.h b/tools/virsh.h
index 847ed25151..b4e610b2a4 100644
--- a/tools/virsh.h
+++ b/tools/virsh.h
@@ -40,6 +40,7 @@
/*
* Command group types
*/
+#define VIRSH_CMD_GRP_CHECKPOINT "Checkpoint"
#define VIRSH_CMD_GRP_DOM_MANAGEMENT "Domain Management"
#define VIRSH_CMD_GRP_DOM_MONITORING "Domain Monitoring"
#define VIRSH_CMD_GRP_STORAGE_POOL "Storage Pool"
diff --git a/po/POTFILES b/po/POTFILES
index adf907ed93..460e54d4fb 100644
--- a/po/POTFILES
+++ b/po/POTFILES
@@ -298,6 +298,7 @@ src/xenconfig/xen_xl.c
src/xenconfig/xen_xm.c
tests/virpolkittest.c
tools/libvirt-guests.sh.in
+tools/virsh-checkpoint.c
tools/virsh-console.c
tools/virsh-domain-monitor.c
tools/virsh-domain.c
diff --git a/tools/Makefile.am b/tools/Makefile.am
index c6064dee08..2807b9f6fd 100644
--- a/tools/Makefile.am
+++ b/tools/Makefile.am
@@ -216,6 +216,7 @@ virt_login_shell_CFLAGS = \
virsh_SOURCES = \
virsh.c virsh.h \
+ virsh-checkpoint.c virsh-checkpoint.h \
virsh-completer.c virsh-completer.h \
virsh-console.c virsh-console.h \
virsh-domain.c virsh-domain.h \
diff --git a/tools/virsh-checkpoint.c b/tools/virsh-checkpoint.c
new file mode 100644
index 0000000000..8200687f8a
--- /dev/null
+++ b/tools/virsh-checkpoint.c
@@ -0,0 +1,1226 @@
+/*
+ * virsh-checkpoint.c: Commands to manage domain checkpoints
+ *
+ * Copyright (C) 2005-2019 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ *
+ * Daniel Veillard <veillard(a)redhat.com>
+ * Karel Zak <kzak(a)redhat.com>
+ * Daniel P. Berrange <berrange(a)redhat.com>
+ *
+ */
+
+#include <config.h>
+#include "virsh-checkpoint.h"
+
+#include <assert.h>
+
+#include <libxml/parser.h>
+#include <libxml/tree.h>
+#include <libxml/xpath.h>
+#include <libxml/xmlsave.h>
+
+#include "internal.h"
+#include "virbuffer.h"
+#include "viralloc.h"
+#include "virfile.h"
+#include "virsh-util.h"
+#include "virstring.h"
+#include "virxml.h"
+#include "conf/checkpoint_conf.h"
+#include "vsh-table.h"
+
+/* Helper for checkpoint-create and checkpoint-create-as */
+static bool
+virshCheckpointCreate(vshControl *ctl,
+ virDomainPtr dom,
+ const char *buffer,
+ unsigned int flags,
+ const char *from)
+{
+ bool ret = false;
+ virDomainCheckpointPtr checkpoint;
+ const char *name = NULL;
+
+ checkpoint = virDomainCheckpointCreateXML(dom, buffer, flags);
+
+ if (checkpoint == NULL)
+ goto cleanup;
+
+ name = virDomainCheckpointGetName(checkpoint);
+ if (!name) {
+ vshError(ctl, "%s", _("Could not get checkpoint name"));
+ goto cleanup;
+ }
+
+ if (from)
+ vshPrintExtra(ctl, _("Domain checkpoint %s created from
'%s'"),
+ name, from);
+ else
+ vshPrintExtra(ctl, _("Domain checkpoint %s created"), name);
+
+ ret = true;
+
+ cleanup:
+ virshDomainCheckpointFree(checkpoint);
+ return ret;
+}
+
+
+/*
+ * "checkpoint-create" command
+ */
+static const vshCmdInfo info_checkpoint_create[] = {
+ {.name = "help",
+ .data = N_("Create a checkpoint from XML")
+ },
+ {.name = "desc",
+ .data = N_("Create a checkpoint from XML for use in "
+ "future incremental backups")
+ },
+ {.name = NULL}
+};
+
+static const vshCmdOptDef opts_checkpoint_create[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "xmlfile",
+ .type = VSH_OT_STRING,
+ .help = N_("domain checkpoint XML")
+ },
+ {.name = "redefine",
+ .type = VSH_OT_BOOL,
+ .help = N_("redefine metadata for existing checkpoint")
+ },
+ {.name = "no-metadata",
+ .type = VSH_OT_BOOL,
+ .help = N_("create checkpoint but create no metadata")
+ },
+ {.name = "quiesce",
+ .type = VSH_OT_BOOL,
+ .help = N_("quiesce guest's file systems")
+ },
+ {.name = NULL}
+};
+
+static bool
+cmdCheckpointCreate(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ bool ret = false;
+ const char *from = NULL;
+ char *buffer = NULL;
+ unsigned int flags = 0;
+
+ if (vshCommandOptBool(cmd, "redefine"))
+ flags |= VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE;
+ if (vshCommandOptBool(cmd, "no-metadata"))
+ flags |= VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA;
+ if (vshCommandOptBool(cmd, "quiesce"))
+ flags |= VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE;
+
+ if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
+ goto cleanup;
+
+ if (vshCommandOptStringReq(ctl, cmd, "xmlfile", &from) < 0)
+ goto cleanup;
+ if (!from) {
+ buffer = vshStrdup(ctl, "<domaincheckpoint/>");
+ } else {
+ if (virFileReadAll(from, VSH_MAX_XML_FILE, &buffer) < 0) {
+ vshSaveLibvirtError();
+ goto cleanup;
+ }
+ }
+
+ ret = virshCheckpointCreate(ctl, dom, buffer, flags, from);
+
+ cleanup:
+ VIR_FREE(buffer);
+ virshDomainFree(dom);
+
+ return ret;
+}
+
+
+/*
+ * "checkpoint-create-as" command
+ */
+static int
+virshParseCheckpointDiskspec(vshControl *ctl,
+ virBufferPtr buf,
+ const char *str)
+{
+ int ret = -1;
+ const char *name = NULL;
+ const char *checkpoint = NULL;
+ const char *bitmap = NULL;
+ char **array = NULL;
+ int narray;
+ size_t i;
+
+ narray = vshStringToArray(str, &array);
+ if (narray <= 0)
+ goto cleanup;
+
+ name = array[0];
+ for (i = 1; i < narray; i++) {
+ if (!checkpoint && STRPREFIX(array[i], "checkpoint="))
+ checkpoint = array[i] + strlen("checkpoint=");
+ else if (!bitmap && STRPREFIX(array[i], "bitmap="))
+ bitmap = array[i] + strlen("bitmap=");
+ else
+ goto cleanup;
+ }
+
+ virBufferEscapeString(buf, "<disk name='%s'", name);
+ if (checkpoint)
+ virBufferAsprintf(buf, " checkpoint='%s'", checkpoint);
+ if (bitmap)
+ virBufferAsprintf(buf, " bitmap='%s'", bitmap);
+ virBufferAddLit(buf, "/>\n");
+ ret = 0;
+ cleanup:
+ if (ret < 0)
+ vshError(ctl, _("unable to parse diskspec: %s"), str);
+ virStringListFree(array);
+ return ret;
+}
+
+static const vshCmdInfo info_checkpoint_create_as[] = {
+ {.name = "help",
+ .data = N_("Create a checkpoint from a set of args")
+ },
+ {.name = "desc",
+ .data = N_("Create a checkpoint from arguments for use in "
+ "future incremental backups")
+ },
+ {.name = NULL}
+};
+
+static const vshCmdOptDef opts_checkpoint_create_as[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "name",
+ .type = VSH_OT_STRING,
+ .help = N_("name of checkpoint")
+ },
+ {.name = "description",
+ .type = VSH_OT_STRING,
+ .help = N_("description of checkpoint")
+ },
+ {.name = "print-xml",
+ .type = VSH_OT_BOOL,
+ .help = N_("print XML document rather than create")
+ },
+ {.name = "no-metadata",
+ .type = VSH_OT_BOOL,
+ .help = N_("take checkpoint but create no metadata")
+ },
+ {.name = "quiesce",
+ .type = VSH_OT_BOOL,
+ .help = N_("quiesce guest's file systems")
+ },
+ {.name = "diskspec",
+ .type = VSH_OT_ARGV,
+ .help = N_("disk attributes: disk[,checkpoint=type][,bitmap=name]")
+ },
+ {.name = NULL}
+};
+
+
+static bool
+cmdCheckpointCreateAs(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ bool ret = false;
+ char *buffer = NULL;
+ const char *name = NULL;
+ const char *desc = NULL;
+ virBuffer buf = VIR_BUFFER_INITIALIZER;
+ unsigned int flags = 0;
+ const vshCmdOpt *opt = NULL;
+
+ if (vshCommandOptBool(cmd, "no-metadata"))
+ flags |= VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA;
+ if (vshCommandOptBool(cmd, "quiesce"))
+ flags |= VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE;
+
+ if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
+ return false;
+
+ if (vshCommandOptStringReq(ctl, cmd, "name", &name) < 0 ||
+ vshCommandOptStringReq(ctl, cmd, "description", &desc) < 0)
+ goto cleanup;
+
+ virBufferAddLit(&buf, "<domaincheckpoint>\n");
+ virBufferAdjustIndent(&buf, 2);
+ virBufferEscapeString(&buf, "<name>%s</name>\n", name);
+ virBufferEscapeString(&buf,
"<description>%s</description>\n", desc);
+
+ if (vshCommandOptBool(cmd, "diskspec")) {
+ virBufferAddLit(&buf, "<disks>\n");
+ virBufferAdjustIndent(&buf, 2);
+ while ((opt = vshCommandOptArgv(ctl, cmd, opt))) {
+ if (virshParseCheckpointDiskspec(ctl, &buf, opt->data) < 0)
+ goto cleanup;
+ }
+ virBufferAdjustIndent(&buf, -2);
+ virBufferAddLit(&buf, "</disks>\n");
+ }
+ virBufferAdjustIndent(&buf, -2);
+ virBufferAddLit(&buf, "</domaincheckpoint>\n");
+
+ if (virBufferError(&buf)) {
+ vshError(ctl, "%s", _("Out of memory"));
+ goto cleanup;
+ }
+
+ buffer = virBufferContentAndReset(&buf);
+
+ if (vshCommandOptBool(cmd, "print-xml")) {
+ vshPrint(ctl, "%s\n", buffer);
+ ret = true;
+ goto cleanup;
+ }
+
+ ret = virshCheckpointCreate(ctl, dom, buffer, flags, NULL);
+
+ cleanup:
+ virBufferFreeAndReset(&buf);
+ VIR_FREE(buffer);
+ virshDomainFree(dom);
+
+ return ret;
+}
+
+
+/* Helper for resolving {--current | --ARG name} into a checkpoint
+ * belonging to DOM. On success, populate *CHK and *NAME, before
+ * returning 0. On failure, return -1 after issuing an error
+ * message. */
+static int
+virshLookupCheckpoint(vshControl *ctl,
+ const vshCmd *cmd,
+ const char *arg,
+ virDomainPtr dom,
+ virDomainCheckpointPtr *chk,
+ const char **name)
+{
+ bool current = vshCommandOptBool(cmd, "current");
+ const char *chkname = NULL;
+
+ if (vshCommandOptStringReq(ctl, cmd, arg, &chkname) < 0)
+ return -1;
+
+ if (current && chkname) {
+ vshError(ctl, _("--%s and --current are mutually exclusive"), arg);
+ return -1;
+ }
+
+ if (chkname) {
+ *chk = virDomainCheckpointLookupByName(dom, chkname, 0);
+ } else if (current) {
+ int count;
+ virDomainCheckpointPtr *checkpoints = NULL;
+
+ count = virDomainListAllCheckpoints(dom, &checkpoints,
+ VIR_DOMAIN_CHECKPOINT_LIST_CURRENT);
+ if (count < 0)
+ return -1;
+ if (count == 0) {
+ vshError(ctl, _("domain has no current checkpoint"));
+ return -1;
+ }
+ if (count > 1) {
+ while (count-- > 0)
+ virDomainCheckpointFree(checkpoints[count]);
+ VIR_FREE(checkpoints);
+ vshError(ctl, _("domain has more than one current checkpoint"));
+ return -1;
+ }
+ *chk = checkpoints[0];
+ VIR_FREE(checkpoints);
+ } else {
+ vshError(ctl, _("--%s or --current is required"), arg);
+ return -1;
+ }
+ if (!*chk) {
+ vshReportError(ctl);
+ return -1;
+ }
+
+ *name = virDomainCheckpointGetName(*chk);
+ return 0;
+}
+
+
+/*
+ * "checkpoint-edit" command
+ */
+static const vshCmdInfo info_checkpoint_edit[] = {
+ {.name = "help",
+ .data = N_("edit XML for a checkpoint")
+ },
+ {.name = "desc",
+ .data = N_("Edit the domain checkpoint XML for a named checkpoint")
+ },
+ {.name = NULL}
+};
+
+static const vshCmdOptDef opts_checkpoint_edit[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "checkpointname",
+ .type = VSH_OT_STRING,
+ .help = N_("checkpoint name"),
+ .completer = virshCheckpointNameCompleter,
+ },
+ VIRSH_COMMON_OPT_CURRENT(N_("edit current checkpoint")),
+ {.name = NULL}
+};
+
+static bool
+cmdCheckpointEdit(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+ virDomainCheckpointPtr edited = NULL;
+ const char *name = NULL;
+ const char *edited_name;
+ bool ret = false;
+ unsigned int getxml_flags = VIR_DOMAIN_CHECKPOINT_XML_SECURE;
+ unsigned int define_flags = VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE;
+
+ if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
+ return false;
+
+ if (virshLookupCheckpoint(ctl, cmd, "checkpointname", dom,
+ &checkpoint, &name) < 0)
+ goto cleanup;
+
+#define EDIT_GET_XML \
+ virDomainCheckpointGetXMLDesc(checkpoint, getxml_flags)
+#define EDIT_NOT_CHANGED \
+ do { \
+ vshPrintExtra(ctl, \
+ _("Checkpoint %s XML configuration not changed.\n"), \
+ name); \
+ ret = true; \
+ goto edit_cleanup; \
+ } while (0)
+#define EDIT_DEFINE \
+ edited = virDomainCheckpointCreateXML(dom, doc_edited, define_flags)
+#include "virsh-edit.c"
+
+ edited_name = virDomainCheckpointGetName(edited);
+ if (STREQ(name, edited_name)) {
+ vshPrintExtra(ctl, _("Checkpoint %s edited.\n"), name);
+ } else {
+ unsigned int delete_flags = VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY;
+
+ if (virDomainCheckpointDelete(edited, delete_flags) < 0) {
+ vshReportError(ctl);
+ vshError(ctl, _("Failed to clean up %s"), edited_name);
+ goto cleanup;
+ }
+ vshError(ctl, _("Cannot rename checkpoint %s to %s"),
+ name, edited_name);
+ goto cleanup;
+ }
+
+ ret = true;
+
+ cleanup:
+ if (!ret && name)
+ vshError(ctl, _("Failed to update %s"), name);
+ virshDomainCheckpointFree(edited);
+ virshDomainCheckpointFree(checkpoint);
+ virshDomainFree(dom);
+ return ret;
+}
+
+
+/* Helper function to get the name of a checkpoint's parent. Caller
+ * must free the result. Returns 0 on success (including when it was
+ * proven no parent exists), and -1 on failure with error reported
+ * (such as no checkpoint support or domain deleted in meantime). */
+static int
+virshGetCheckpointParent(vshControl *ctl,
+ virDomainCheckpointPtr checkpoint,
+ char **parent_name)
+{
+ virDomainCheckpointPtr parent = NULL;
+ int ret = -1;
+
+ *parent_name = NULL;
+
+ parent = virDomainCheckpointGetParent(checkpoint, 0);
+ if (parent) {
+ /* API works, and virDomainCheckpointGetName will succeed */
+ *parent_name = vshStrdup(ctl, virDomainCheckpointGetName(parent));
+ ret = 0;
+ } else if (last_error->code == VIR_ERR_NO_DOMAIN_CHECKPOINT) {
+ /* API works, and we found a root with no parent */
+ ret = 0;
+ }
+
+ if (ret < 0) {
+ vshReportError(ctl);
+ vshError(ctl, "%s", _("unable to determine if checkpoint has
parent"));
+ } else {
+ vshResetLibvirtError();
+ }
+ virshDomainCheckpointFree(parent);
+ return ret;
+}
+
+
+/*
+ * "checkpoint-info" command
+ */
+static const vshCmdInfo info_checkpoint_info[] = {
+ {.name = "help",
+ .data = N_("checkpoint information")
+ },
+ {.name = "desc",
+ .data = N_("Returns basic information about a checkpoint.")
+ },
+ {.name = NULL}
+};
+
+static const vshCmdOptDef opts_checkpoint_info[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "checkpointname",
+ .type = VSH_OT_STRING,
+ .help = N_("checkpoint name"),
+ .completer = virshCheckpointNameCompleter,
+ },
+ VIRSH_COMMON_OPT_CURRENT(N_("info on current checkpoint")),
+ {.name = NULL}
+};
+
+
+static bool
+cmdCheckpointInfo(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom;
+ virDomainCheckpointPtr checkpoint = NULL;
+ const char *name;
+ char *parent = NULL;
+ char *xml = NULL;
+ xmlDocPtr xmldoc = NULL;
+ xmlXPathContextPtr ctxt = NULL;
+ bool ret = false;
+ int count;
+ unsigned int flags;
+ int current;
+
+ dom = virshCommandOptDomain(ctl, cmd, NULL);
+ if (dom == NULL)
+ return false;
+
+ if (virshLookupCheckpoint(ctl, cmd, "checkpointname", dom,
+ &checkpoint, &name) < 0)
+ goto cleanup;
+
+ vshPrint(ctl, "%-15s %s\n", _("Name:"), name);
+ vshPrint(ctl, "%-15s %s\n", _("Domain:"),
virDomainGetName(dom));
+
+ /* Determine if checkpoint is current. */
+ xml = virDomainCheckpointGetXMLDesc(checkpoint,
+ VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN);
+ if (!xml)
+ goto cleanup;
+
+ xmldoc = virXMLParseStringCtxt(xml, _("(domain_checkpoint)"), &ctxt);
+ if (!xmldoc)
+ goto cleanup;
+
+ if (virXPathInt("string(/domaincheckpoint/current)", ctxt, ¤t)
< 0)
+ goto cleanup;
+ vshPrint(ctl, "%-15s %s\n", _("Current:"),
+ current > 0 ? _("yes") : _("no"));
+
+ if (virshGetCheckpointParent(ctl, checkpoint, &parent) < 0) {
+ vshError(ctl, "%s",
+ _("unexpected problem querying checkpoint state"));
+ goto cleanup;
+ }
+ vshPrint(ctl, "%-15s %s\n", _("Parent:"), parent ? parent :
"-");
+
+ /* Children, Descendants. */
+ flags = 0;
+ count = virDomainCheckpointListAllChildren(checkpoint, NULL, flags);
+ if (count < 0) {
+ if (last_error->code == VIR_ERR_NO_SUPPORT) {
+ vshResetLibvirtError();
+ ret = true;
+ }
+ goto cleanup;
+ }
+ vshPrint(ctl, "%-15s %d\n", _("Children:"), count);
+ flags = VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS;
+ count = virDomainCheckpointListAllChildren(checkpoint, NULL, flags);
+ if (count < 0)
+ goto cleanup;
+ vshPrint(ctl, "%-15s %d\n", _("Descendants:"), count);
+
+ ret = true;
+
+ cleanup:
+ xmlXPathFreeContext(ctxt);
+ xmlFreeDoc(xmldoc);
+ VIR_FREE(xml);
+ VIR_FREE(parent);
+ virshDomainCheckpointFree(checkpoint);
+ virshDomainFree(dom);
+ return ret;
+}
+
+
+/* Helpers for collecting a list of checkpoints. */
+struct virshChk {
+ virDomainCheckpointPtr chk;
+ char *parent;
+};
+struct virshCheckpointList {
+ struct virshChk *chks;
+ int nchks;
+};
+typedef struct virshCheckpointList *virshCheckpointListPtr;
+
+static void
+virshCheckpointListFree(virshCheckpointListPtr checkpointlist)
+{
+ size_t i;
+
+ if (!checkpointlist)
+ return;
+ if (checkpointlist->chks) {
+ for (i = 0; i < checkpointlist->nchks; i++) {
+ virshDomainCheckpointFree(checkpointlist->chks[i].chk);
+ VIR_FREE(checkpointlist->chks[i].parent);
+ }
+ VIR_FREE(checkpointlist->chks);
+ }
+ VIR_FREE(checkpointlist);
+}
+
+
+static int
+virshChkSorter(const void *a,
+ const void *b)
+{
+ const struct virshChk *sa = a;
+ const struct virshChk *sb = b;
+
+ if (sa->chk && !sb->chk)
+ return -1;
+ if (!sa->chk)
+ return sb->chk != NULL;
+
+ return vshStrcasecmp(virDomainCheckpointGetName(sa->chk),
+ virDomainCheckpointGetName(sb->chk));
+}
+
+
+/* Compute a list of checkpoints from DOM. If FROM is provided, the
+ * list is limited to descendants of the given checkpoint. If FLAGS is
+ * given, the list is filtered. If TREE is specified, then all but
+ * FROM or the roots will also have parent information. */
+static virshCheckpointListPtr
+virshCheckpointListCollect(vshControl *ctl,
+ virDomainPtr dom,
+ virDomainCheckpointPtr from,
+ unsigned int orig_flags,
+ bool tree)
+{
+ size_t i;
+ char **names = NULL;
+ int count = -1;
+ virDomainCheckpointPtr *chks;
+ virshCheckpointListPtr checkpointlist = vshMalloc(ctl,
+ sizeof(*checkpointlist));
+ virshCheckpointListPtr ret = NULL;
+ unsigned int flags = orig_flags;
+
+ if (from)
+ count = virDomainCheckpointListAllChildren(from, &chks, flags);
+ else
+ count = virDomainListAllCheckpoints(dom, &chks, flags);
+ if (count < 0) {
+ vshError(ctl, "%s",
+ _("unexpected problem querying checkpoints"));
+ goto cleanup;
+ }
+
+ /* When mixing --from and --tree, we also want a copy of from
+ * in the list, but with no parent for that one entry. */
+ checkpointlist->chks = vshCalloc(ctl, count + (tree && from),
+ sizeof(*checkpointlist->chks));
+ checkpointlist->nchks = count;
+ for (i = 0; i < count; i++)
+ checkpointlist->chks[i].chk = chks[i];
+ VIR_FREE(chks);
+ if (tree) {
+ for (i = 0; i < count; i++) {
+ if (virshGetCheckpointParent(ctl, checkpointlist->chks[i].chk,
+ &checkpointlist->chks[i].parent) < 0)
+ goto cleanup;
+ }
+ if (from) {
+ checkpointlist->chks[checkpointlist->nchks++].chk = from;
+ virDomainCheckpointRef(from);
+ }
+ }
+
+ if (!(orig_flags & VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL))
+ qsort(checkpointlist->chks, checkpointlist->nchks,
+ sizeof(*checkpointlist->chks), virshChkSorter);
+
+ ret = checkpointlist;
+ checkpointlist = NULL;
+
+ cleanup:
+ virshCheckpointListFree(checkpointlist);
+ if (names && count > 0)
+ for (i = 0; i < count; i++)
+ VIR_FREE(names[i]);
+ VIR_FREE(names);
+ return ret;
+}
+
+
+static const char *
+virshCheckpointListLookup(int id,
+ bool parent,
+ void *opaque)
+{
+ virshCheckpointListPtr checkpointlist = opaque;
+ if (parent)
+ return checkpointlist->chks[id].parent;
+ return virDomainCheckpointGetName(checkpointlist->chks[id].chk);
+}
+
+
+/*
+ * "checkpoint-list" command
+ */
+static const vshCmdInfo info_checkpoint_list[] = {
+ {.name = "help",
+ .data = N_("List checkpoints for a domain")
+ },
+ {.name = "desc",
+ .data = N_("Checkpoint List")
+ },
+ {.name = NULL}
+};
+
+static const vshCmdOptDef opts_checkpoint_list[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "parent",
+ .type = VSH_OT_BOOL,
+ .help = N_("add a column showing parent checkpoint")
+ },
+ {.name = "roots",
+ .type = VSH_OT_BOOL,
+ .help = N_("list only checkpoints without parents")
+ },
+ {.name = "leaves",
+ .type = VSH_OT_BOOL,
+ .help = N_("list only checkpoints without children")
+ },
+ {.name = "no-leaves",
+ .type = VSH_OT_BOOL,
+ .help = N_("list only checkpoints that are not leaves (with children)")
+ },
+ {.name = "tree",
+ .type = VSH_OT_BOOL,
+ .help = N_("list checkpoints in a tree")
+ },
+ {.name = "from",
+ .type = VSH_OT_STRING,
+ .help = N_("limit list to children of given checkpoint"),
+ .completer = virshCheckpointNameCompleter,
+ },
+ VIRSH_COMMON_OPT_CURRENT(N_("limit list to children of current
checkpoint")),
+ {.name = "descendants",
+ .type = VSH_OT_BOOL,
+ .help = N_("with --from, list all descendants")
+ },
+ {.name = "name",
+ .type = VSH_OT_BOOL,
+ .help = N_("list checkpoint names only")
+ },
+ {.name = "topological",
+ .type = VSH_OT_BOOL,
+ .help = N_("sort list topologically rather than by name"),
+ },
+ {.name = "current-only",
+ .type = VSH_OT_BOOL,
+ .help = N_("filter to just current checkpoints"),
+ },
+ {.name = "no-current",
+ .type = VSH_OT_BOOL,
+ .help = N_("filter out current checkpoints"),
+ },
+ {.name = NULL}
+};
+
+static bool
+cmdCheckpointList(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ bool ret = false;
+ unsigned int flags = 0;
+ size_t i;
+ xmlDocPtr xml = NULL;
+ xmlXPathContextPtr ctxt = NULL;
+ char *doc = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+ long long creation_longlong;
+ time_t creation_time_t;
+ char timestr[100];
+ struct tm time_info;
+ bool tree = vshCommandOptBool(cmd, "tree");
+ bool name = vshCommandOptBool(cmd, "name");
+ bool from = vshCommandOptBool(cmd, "from");
+ bool parent = vshCommandOptBool(cmd, "parent");
+ bool roots = vshCommandOptBool(cmd, "roots");
+ bool current = vshCommandOptBool(cmd, "current");
+ const char *from_chk = NULL;
+ char *parent_chk = NULL;
+ virDomainCheckpointPtr start = NULL;
+ virshCheckpointListPtr checkpointlist = NULL;
+ vshTablePtr table = NULL;
+
+ VSH_EXCLUSIVE_OPTIONS_VAR(tree, name);
+ VSH_EXCLUSIVE_OPTIONS_VAR(parent, roots);
+ VSH_EXCLUSIVE_OPTIONS_VAR(parent, tree);
+ VSH_EXCLUSIVE_OPTIONS_VAR(roots, tree);
+ VSH_EXCLUSIVE_OPTIONS_VAR(roots, from);
+ VSH_EXCLUSIVE_OPTIONS_VAR(roots, current);
+
+#define FILTER(option, flag) \
+ do { \
+ if (vshCommandOptBool(cmd, option)) { \
+ if (tree) { \
+ vshError(ctl, \
+ _("--%s and --tree are mutually exclusive"), \
+ option); \
+ return false; \
+ } \
+ flags |= VIR_DOMAIN_CHECKPOINT_LIST_ ## flag; \
+ } \
+ } while (0)
+
+ FILTER("leaves", LEAVES);
+ FILTER("no-leaves", NO_LEAVES);
+ FILTER("current-only", CURRENT);
+ FILTER("no-current", NO_CURRENT);
+#undef FILTER
+
+ if (vshCommandOptBool(cmd, "topological"))
+ flags |= VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL;
+
+ if (roots)
+ flags |= VIR_DOMAIN_CHECKPOINT_LIST_ROOTS;
+
+ if (vshCommandOptBool(cmd, "descendants")) {
+ if (!from && !current) {
+ vshError(ctl, "%s",
+ _("--descendants requires either --from or --current"));
+ return false;
+ }
+ flags |= VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS;
+ }
+
+ if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
+ return false;
+
+ if ((from || current) &&
+ virshLookupCheckpoint(ctl, cmd, "from", dom, &start, &from_chk)
< 0)
+ goto cleanup;
+
+ if (!(checkpointlist = virshCheckpointListCollect(ctl, dom, start, flags,
+ tree)))
+ goto cleanup;
+
+ if (!tree && !name) {
+ if (parent)
+ table = vshTableNew(_("Name"), _("Creation Time"),
_("Parent"),
+ NULL);
+ else
+ table = vshTableNew(_("Name"), _("Creation Time"),
NULL);
+ if (!table)
+ goto cleanup;
+ }
+
+ if (tree) {
+ for (i = 0; i < checkpointlist->nchks; i++) {
+ if (!checkpointlist->chks[i].parent &&
+ vshTreePrint(ctl, virshCheckpointListLookup, checkpointlist,
+ checkpointlist->nchks, i) < 0)
+ goto cleanup;
+ }
+ ret = true;
+ goto cleanup;
+ }
+
+ for (i = 0; i < checkpointlist->nchks; i++) {
+ const char *chk_name;
+
+ /* free up memory from previous iterations of the loop */
+ VIR_FREE(parent_chk);
+ xmlXPathFreeContext(ctxt);
+ xmlFreeDoc(xml);
+ VIR_FREE(doc);
+
+ checkpoint = checkpointlist->chks[i].chk;
+ chk_name = virDomainCheckpointGetName(checkpoint);
+ assert(chk_name);
+
+ if (name) {
+ /* just print the checkpoint name */
+ vshPrint(ctl, "%s\n", chk_name);
+ continue;
+ }
+
+ if (!(doc = virDomainCheckpointGetXMLDesc(checkpoint, 0)))
+ continue;
+
+ if (!(xml = virXMLParseStringCtxt(doc, _("(domain_checkpoint)"),
&ctxt)))
+ continue;
+
+ if (parent)
+ parent_chk =
virXPathString("string(/domaincheckpoint/parent/name)",
+ ctxt);
+
+ if (virXPathLongLong("string(/domaincheckpoint/creationTime)", ctxt,
+ &creation_longlong) < 0)
+ continue;
+ creation_time_t = creation_longlong;
+ if (creation_time_t != creation_longlong) {
+ vshError(ctl, "%s", _("time_t overflow"));
+ continue;
+ }
+ localtime_r(&creation_time_t, &time_info);
+ strftime(timestr, sizeof(timestr), "%Y-%m-%d %H:%M:%S %z",
+ &time_info);
+
+ if (parent) {
+ if (vshTableRowAppend(table, chk_name, timestr,
+ NULLSTR_EMPTY(parent_chk), NULL) < 0)
+ goto cleanup;
+ } else {
+ if (vshTableRowAppend(table, chk_name, timestr, NULL) < 0)
+ goto cleanup;
+ }
+ }
+
+ if (table)
+ vshTablePrintToStdout(table, ctl);
+
+ ret = true;
+
+ cleanup:
+ /* this frees up memory from the last iteration of the loop */
+ virshCheckpointListFree(checkpointlist);
+ VIR_FREE(parent_chk);
+ virshDomainCheckpointFree(start);
+ xmlXPathFreeContext(ctxt);
+ xmlFreeDoc(xml);
+ VIR_FREE(doc);
+ virshDomainFree(dom);
+ vshTableFree(table);
+
+ return ret;
+}
+
+
+/*
+ * "checkpoint-dumpxml" command
+ */
+static const vshCmdInfo info_checkpoint_dumpxml[] = {
+ {.name = "help",
+ .data = N_("Dump XML for a domain checkpoint")
+ },
+ {.name = "desc",
+ .data = N_("Checkpoint Dump XML")
+ },
+ {.name = NULL}
+};
+
+static const vshCmdOptDef opts_checkpoint_dumpxml[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "checkpointname",
+ .type = VSH_OT_STRING,
+ .help = N_("checkpoint name"),
+ .completer = virshCheckpointNameCompleter,
+ },
+ VIRSH_COMMON_OPT_CURRENT(N_("dump xml for current checkpoint")),
+ {.name = "security-info",
+ .type = VSH_OT_BOOL,
+ .help = N_("include security sensitive information in XML dump")
+ },
+ {.name = "no-domain",
+ .type = VSH_OT_BOOL,
+ .help = N_("exclude <domain> from XML")
+ },
+ {.name = "size",
+ .type = VSH_OT_BOOL,
+ .help = N_("include backup size estimate in XML dump")
+ },
+ {.name = NULL}
+};
+
+static bool
+cmdCheckpointDumpXML(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ bool ret = false;
+ const char *name = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+ char *xml = NULL;
+ unsigned int flags = 0;
+
+ if (vshCommandOptBool(cmd, "security-info"))
+ flags |= VIR_DOMAIN_CHECKPOINT_XML_SECURE;
+ if (vshCommandOptBool(cmd, "no-domain"))
+ flags |= VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN;
+ if (vshCommandOptBool(cmd, "size"))
+ flags |= VIR_DOMAIN_CHECKPOINT_XML_SIZE;
+
+ if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
+ return false;
+
+ if (virshLookupCheckpoint(ctl, cmd, "checkpointname", dom,
+ &checkpoint, &name) < 0)
+ goto cleanup;
+
+ if (!(xml = virDomainCheckpointGetXMLDesc(checkpoint, flags)))
+ goto cleanup;
+
+ vshPrint(ctl, "%s", xml);
+ ret = true;
+
+ cleanup:
+ VIR_FREE(xml);
+ virshDomainCheckpointFree(checkpoint);
+ virshDomainFree(dom);
+
+ return ret;
+}
+
+
+/*
+ * "checkpoint-parent" command
+ */
+static const vshCmdInfo info_checkpoint_parent[] = {
+ {.name = "help",
+ .data = N_("Get the name of the parent of a checkpoint")
+ },
+ {.name = "desc",
+ .data = N_("Extract the checkpoint's parent, if any")
+ },
+ {.name = NULL}
+};
+
+static const vshCmdOptDef opts_checkpoint_parent[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "checkpointname",
+ .type = VSH_OT_STRING,
+ .help = N_("find parent of checkpoint name"),
+ .completer = virshCheckpointNameCompleter,
+ },
+ VIRSH_COMMON_OPT_CURRENT(N_("find parent of current checkpoint")),
+ {.name = NULL}
+};
+
+static bool
+cmdCheckpointParent(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ bool ret = false;
+ const char *name = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+ char *parent = NULL;
+
+ dom = virshCommandOptDomain(ctl, cmd, NULL);
+ if (dom == NULL)
+ goto cleanup;
+
+ if (virshLookupCheckpoint(ctl, cmd, "checkpointname", dom,
+ &checkpoint, &name) < 0)
+ goto cleanup;
+
+ if (virshGetCheckpointParent(ctl, checkpoint, &parent) < 0)
+ goto cleanup;
+ if (!parent) {
+ vshError(ctl, _("checkpoint '%s' has no parent"), name);
+ goto cleanup;
+ }
+
+ vshPrint(ctl, "%s", parent);
+
+ ret = true;
+
+ cleanup:
+ VIR_FREE(parent);
+ virshDomainCheckpointFree(checkpoint);
+ virshDomainFree(dom);
+
+ return ret;
+}
+
+
+/*
+ * "checkpoint-delete" command
+ */
+static const vshCmdInfo info_checkpoint_delete[] = {
+ {.name = "help",
+ .data = N_("Delete a domain checkpoint")
+ },
+ {.name = "desc",
+ .data = N_("Checkpoint Delete")
+ },
+ {.name = NULL}
+};
+
+static const vshCmdOptDef opts_checkpoint_delete[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "checkpointname",
+ .type = VSH_OT_STRING,
+ .help = N_("checkpoint name"),
+ .completer = virshCheckpointNameCompleter,
+ },
+ VIRSH_COMMON_OPT_CURRENT(N_("delete current checkpoint")),
+ {.name = "children",
+ .type = VSH_OT_BOOL,
+ .help = N_("delete checkpoint and all children")
+ },
+ {.name = "children-only",
+ .type = VSH_OT_BOOL,
+ .help = N_("delete children but not checkpoint")
+ },
+ {.name = "metadata",
+ .type = VSH_OT_BOOL,
+ .help = N_("delete only libvirt metadata, leaving checkpoint contents
behind")
+ },
+ {.name = NULL}
+};
+
+static bool
+cmdCheckpointDelete(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ bool ret = false;
+ const char *name = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+ unsigned int flags = 0;
+
+ dom = virshCommandOptDomain(ctl, cmd, NULL);
+ if (dom == NULL)
+ goto cleanup;
+
+ if (virshLookupCheckpoint(ctl, cmd, "checkpointname", dom,
+ &checkpoint, &name) < 0)
+ goto cleanup;
+
+ if (vshCommandOptBool(cmd, "children"))
+ flags |= VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN;
+ if (vshCommandOptBool(cmd, "children-only"))
+ flags |= VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY;
+ if (vshCommandOptBool(cmd, "metadata"))
+ flags |= VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY;
+
+ if (virDomainCheckpointDelete(checkpoint, flags) == 0) {
+ if (flags & VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY)
+ vshPrintExtra(ctl, _("Domain checkpoint %s children deleted\n"),
name);
+ else
+ vshPrintExtra(ctl, _("Domain checkpoint %s deleted\n"), name);
+ } else {
+ vshError(ctl, _("Failed to delete checkpoint %s"), name);
+ goto cleanup;
+ }
+
+ ret = true;
+
+ cleanup:
+ virshDomainCheckpointFree(checkpoint);
+ virshDomainFree(dom);
+
+ return ret;
+}
+
+
+const vshCmdDef checkpointCmds[] = {
+ {.name = "checkpoint-create",
+ .handler = cmdCheckpointCreate,
+ .opts = opts_checkpoint_create,
+ .info = info_checkpoint_create,
+ .flags = 0
+ },
+ {.name = "checkpoint-create-as",
+ .handler = cmdCheckpointCreateAs,
+ .opts = opts_checkpoint_create_as,
+ .info = info_checkpoint_create_as,
+ .flags = 0
+ },
+ {.name = "checkpoint-delete",
+ .handler = cmdCheckpointDelete,
+ .opts = opts_checkpoint_delete,
+ .info = info_checkpoint_delete,
+ .flags = 0
+ },
+ {.name = "checkpoint-dumpxml",
+ .handler = cmdCheckpointDumpXML,
+ .opts = opts_checkpoint_dumpxml,
+ .info = info_checkpoint_dumpxml,
+ .flags = 0
+ },
+ {.name = "checkpoint-edit",
+ .handler = cmdCheckpointEdit,
+ .opts = opts_checkpoint_edit,
+ .info = info_checkpoint_edit,
+ .flags = 0
+ },
+ {.name = "checkpoint-info",
+ .handler = cmdCheckpointInfo,
+ .opts = opts_checkpoint_info,
+ .info = info_checkpoint_info,
+ .flags = 0
+ },
+ {.name = "checkpoint-list",
+ .handler = cmdCheckpointList,
+ .opts = opts_checkpoint_list,
+ .info = info_checkpoint_list,
+ .flags = 0
+ },
+ {.name = "checkpoint-parent",
+ .handler = cmdCheckpointParent,
+ .opts = opts_checkpoint_parent,
+ .info = info_checkpoint_parent,
+ .flags = 0
+ },
+ {.name = NULL}
+};
diff --git a/tools/virsh-completer.c b/tools/virsh-completer.c
index 7d5cf8cb90..b54699fafa 100644
--- a/tools/virsh-completer.c
+++ b/tools/virsh-completer.c
@@ -619,6 +619,57 @@ virshSecretUUIDCompleter(vshControl *ctl,
}
+char **
+virshCheckpointNameCompleter(vshControl *ctl,
+ const vshCmd *cmd,
+ unsigned int flags)
+{
+ virshControlPtr priv = ctl->privData;
+ virDomainPtr dom = NULL;
+ virDomainCheckpointPtr *checkpoints = NULL;
+ int ncheckpoints = 0;
+ size_t i = 0;
+ char **ret = NULL;
+
+ virCheckFlags(0, NULL);
+
+ if (!priv->conn || virConnectIsAlive(priv->conn) <= 0)
+ return NULL;
+
+ if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
+ return NULL;
+
+ if ((ncheckpoints = virDomainListAllCheckpoints(dom, &checkpoints,
+ flags)) < 0)
+ goto error;
+
+ if (VIR_ALLOC_N(ret, ncheckpoints + 1) < 0)
+ goto error;
+
+ for (i = 0; i < ncheckpoints; i++) {
+ const char *name = virDomainCheckpointGetName(checkpoints[i]);
+
+ if (VIR_STRDUP(ret[i], name) < 0)
+ goto error;
+
+ virshDomainCheckpointFree(checkpoints[i]);
+ }
+ VIR_FREE(checkpoints);
+ virshDomainFree(dom);
+
+ return ret;
+
+ error:
+ for (; i < ncheckpoints; i++)
+ virshDomainCheckpointFree(checkpoints[i]);
+ VIR_FREE(checkpoints);
+ for (i = 0; i < ncheckpoints; i++)
+ VIR_FREE(ret[i]);
+ VIR_FREE(ret);
+ virshDomainFree(dom);
+ return NULL;
+}
+
char **
virshSnapshotNameCompleter(vshControl *ctl,
const vshCmd *cmd,
diff --git a/tools/virsh-domain-monitor.c b/tools/virsh-domain-monitor.c
index e399195deb..0e2c4191d7 100644
--- a/tools/virsh-domain-monitor.c
+++ b/tools/virsh-domain-monitor.c
@@ -1621,6 +1621,7 @@ virshDomainListCollect(vshControl *ctl, unsigned int flags)
int autostart;
int state;
int nsnap;
+ int nchk;
int mansave;
virshControlPtr priv = ctl->privData;
@@ -1788,6 +1789,17 @@ virshDomainListCollect(vshControl *ctl, unsigned int flags)
goto remove_entry;
}
+ /* checkpoint filter */
+ if (VSH_MATCH(VIR_CONNECT_LIST_DOMAINS_FILTERS_CHECKPOINT)) {
+ if ((nchk = virDomainListAllCheckpoints(dom, NULL, 0)) < 0) {
+ vshError(ctl, "%s", _("Failed to get checkpoint
count"));
+ goto cleanup;
+ }
+ if (!((VSH_MATCH(VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT) && nchk
> 0) ||
+ (VSH_MATCH(VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT) && nchk ==
0)))
+ goto remove_entry;
+ }
+
/* the domain matched all filters, it may stay */
continue;
@@ -1849,6 +1861,14 @@ static const vshCmdOptDef opts_list[] = {
.type = VSH_OT_BOOL,
.help = N_("list domains without a snapshot")
},
+ {.name = "with-checkpoint",
+ .type = VSH_OT_BOOL,
+ .help = N_("list domains with existing checkpoint")
+ },
+ {.name = "without-checkpoint",
+ .type = VSH_OT_BOOL,
+ .help = N_("list domains without a checkpoint")
+ },
{.name = "state-running",
.type = VSH_OT_BOOL,
.help = N_("list domains in running state")
@@ -1948,6 +1968,9 @@ cmdList(vshControl *ctl, const vshCmd *cmd)
FILTER("with-snapshot", VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT);
FILTER("without-snapshot", VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT);
+ FILTER("with-checkpoint", VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT);
+ FILTER("without-checkpoint", VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT);
+
FILTER("state-running", VIR_CONNECT_LIST_DOMAINS_RUNNING);
FILTER("state-paused", VIR_CONNECT_LIST_DOMAINS_PAUSED);
FILTER("state-shutoff", VIR_CONNECT_LIST_DOMAINS_SHUTOFF);
diff --git a/tools/virsh-domain.c b/tools/virsh-domain.c
index 828ae30789..0b5aca4758 100644
--- a/tools/virsh-domain.c
+++ b/tools/virsh-domain.c
@@ -3633,6 +3633,10 @@ static const vshCmdOptDef opts_undefine[] = {
.type = VSH_OT_BOOL,
.help = N_("remove all domain snapshot metadata (vm must be inactive)")
},
+ {.name = "checkpoints-metadata",
+ .type = VSH_OT_BOOL,
+ .help = N_("remove all domain checkpoint metadata (vm must be inactive)")
+ },
{.name = "nvram",
.type = VSH_OT_BOOL,
.help = N_("remove nvram file, if inactive")
@@ -3662,6 +3666,7 @@ cmdUndefine(vshControl *ctl, const vshCmd *cmd)
/* User-requested actions. */
bool managed_save = vshCommandOptBool(cmd, "managed-save");
bool snapshots_metadata = vshCommandOptBool(cmd, "snapshots-metadata");
+ bool checkpoints_metadata = vshCommandOptBool(cmd,
"checkpoints-metadata");
bool wipe_storage = vshCommandOptBool(cmd, "wipe-storage");
bool remove_all_storage = vshCommandOptBool(cmd, "remove-all-storage");
bool delete_snapshots = vshCommandOptBool(cmd, "delete-snapshots");
@@ -3716,6 +3721,8 @@ cmdUndefine(vshControl *ctl, const vshCmd *cmd)
flags |= VIR_DOMAIN_UNDEFINE_SNAPSHOTS_METADATA;
snapshots_safe = true;
}
+ if (checkpoints_metadata)
+ flags |= VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA;
if (nvram)
flags |= VIR_DOMAIN_UNDEFINE_NVRAM;
if (keep_nvram)
diff --git a/tools/virsh-util.c b/tools/virsh-util.c
index aa88397d61..933d1c825d 100644
--- a/tools/virsh-util.c
+++ b/tools/virsh-util.c
@@ -228,6 +228,17 @@ virshDomainFree(virDomainPtr dom)
}
+void
+virshDomainCheckpointFree(virDomainCheckpointPtr chk)
+{
+ if (!chk)
+ return;
+
+ vshSaveLibvirtHelperError();
+ virDomainCheckpointFree(chk); /* sc_prohibit_obj_free_apis_in_virsh */
+}
+
+
void
virshDomainSnapshotFree(virDomainSnapshotPtr snap)
{
diff --git a/tools/virsh.c b/tools/virsh.c
index b41304a888..0de41e33b8 100644
--- a/tools/virsh.c
+++ b/tools/virsh.c
@@ -50,6 +50,7 @@
#include "virstring.h"
#include "virgettext.h"
+#include "virsh-checkpoint.h"
#include "virsh-console.h"
#include "virsh-domain.h"
#include "virsh-domain-monitor.h"
@@ -832,6 +833,7 @@ static const vshCmdGrp cmdGroups[] = {
{VIRSH_CMD_GRP_DOM_MANAGEMENT, "domain", domManagementCmds},
{VIRSH_CMD_GRP_DOM_MONITORING, "monitor", domMonitoringCmds},
{VIRSH_CMD_GRP_HOST_AND_HV, "host", hostAndHypervisorCmds},
+ {VIRSH_CMD_GRP_CHECKPOINT, "checkpoint", checkpointCmds},
{VIRSH_CMD_GRP_IFACE, "interface", ifaceCmds},
{VIRSH_CMD_GRP_NWFILTER, "filter", nwfilterCmds},
{VIRSH_CMD_GRP_NETWORK, "network", networkCmds},
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 4dffcafea0..8d69d349e9 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -409,6 +409,7 @@ Inject NMI to the guest.
[I<--with-managed-save>] [I<--without-managed-save>]
[I<--autostart>] [I<--no-autostart>]
[I<--with-snapshot>] [I<--without-snapshot>]
+ [I<--with-checkpoint>] [I<--without-checkpoint>]
[I<--state-running>] [I<--state-paused>]
[I<--state-shutoff>] [I<--state-other>]
@@ -514,6 +515,11 @@ this feature disabled use I<--no-autostart>.
Domains that have snapshot images can be listed using flag I<--with-snapshot>,
domains without a snapshot I<--without-snapshot>.
+=item B<Checkpoint existence>
+
+Domains that have checkpoints can be listed using flag I<--with-checkpoint>,
+domains without a checkpoint I<--without-checkpoint>.
+
=back
When talking to older servers, this command is forced to use a series of API
@@ -809,7 +815,8 @@ can be restarted later.
If I<domain> is transient, then the metadata of any snapshots will
be lost once the guest stops running, but the snapshot contents still
exist, and a new domain with the same name and UUID can restore the
-snapshot metadata with B<snapshot-create>.
+snapshot metadata with B<snapshot-create>. Similarly, the metadata of
+any checkpoints will be lost, but can be restored with B<checkpoint-create>.
If I<--graceful> is specified, don't resort to extreme measures
(e.g. SIGKILL) when the guest doesn't stop after a reasonable timeout;
@@ -1574,7 +1581,7 @@ Convert a domain Id (or UUID) to domain name
Rename a domain. This command changes current domain name to the new name
specified in the second argument.
-B<Note>: Domain must be inactive and without snapshots.
+B<Note>: Domain must be inactive and without snapshots or checkpoints.
=item B<domstate> I<domain> [I<--reason>]
@@ -2815,10 +2822,11 @@ services must be shutdown in the domain.
The exact behavior of a domain when it shuts down is set by the
I<on_poweroff> parameter in the domain's XML definition.
-If I<domain> is transient, then the metadata of any snapshots will
-be lost once the guest stops running, but the snapshot contents still
-exist, and a new domain with the same name and UUID can restore the
-snapshot metadata with B<snapshot-create>.
+If I<domain> is transient, then the metadata of any snapshots and
+checkpoints will be lost once the guest stops running, but the underlying
+contents still exist, and a new domain with the same name and UUID can
+restore the snapshot metadata with B<snapshot-create>, and the checkpoint
+metadata with B<checkpoint-create>.
By default the hypervisor will try to pick a suitable shutdown
method. To specify an alternative method, the I<--mode> parameter
@@ -2895,7 +2903,7 @@ Output the device used for the TTY console of the domain. If the
information
is not available the processes will provide an exit code of 1.
=item B<undefine> I<domain> [I<--managed-save>]
[I<--snapshots-metadata>]
-[I<--nvram>] [I<--keep-nvram>]
+[I<--checkpoints-metadata>] [I<--nvram>] [I<--keep-nvram>]
[ {I<--storage> B<volumes> | I<--remove-all-storage>
[I<--delete-storage-volume-snapshots>]} I<--wipe-storage>]
@@ -2913,6 +2921,12 @@ domain. Without the flag, attempts to undefine an inactive domain
with
snapshot metadata will fail. If the domain is active, this flag is
ignored.
+The I<--checkpoints-metadata> flag guarantees that any checkpoints (see the
+B<checkpoint-list> command) are also cleaned up when undefining an inactive
+domain. Without the flag, attempts to undefine an inactive domain with
+checkpoint metadata will fail. If the domain is active, this flag is
+ignored.
+
I<--nvram> and I<--keep-nvram> specify accordingly to delete or keep nvram
(/domain/os/nvram/) file. If the domain has an nvram file and the flags are
omitted, the undefine will fail.
@@ -4655,6 +4669,10 @@ a persistent domain. However, for transient domains, snapshot
metadata is silently lost when the domain quits running (whether
by command such as B<destroy> or by internal guest action).
+For now, it is not possible to create snapshots in a domain that has
+checkpoints, although this restriction will be lifted in a future
+release.
+
=item B<snapshot-create-as> I<domain> {[I<--print-xml>]
[I<--no-metadata>] [I<--halt>] [I<--reuse-external>]} [I<name>]
[I<description>] [I<--disk-only> [I<--quiesce>]] [I<--atomic>]
@@ -4718,6 +4736,10 @@ If I<--live> is specified, libvirt takes the snapshot while
the guest is
running. This increases the size of the memory image of the external
snapshot. This is currently supported only for external full system snapshots.
+For now, it is not possible to create snapshots in a domain that has
+checkpoints, although this restriction will be lifted in a future
+release.
+
=item B<snapshot-current> I<domain> {[I<--name>] |
[I<--security-info>]
| [I<snapshotname>]}
@@ -4892,6 +4914,191 @@ the data contents from that point in time.
=back
+=head1 CHECKPOINT COMMANDS
+
+The following commands manipulate domain checkpoints. Checkpoints serve as
+a point in time to identify which portions of a guest's disks have changed
+after that time, making it possible to perform incremental and differential
+backups. Checkpoints are identified with a unique name. See
+L<https://libvirt.org/formatcheckpoint.html> for documentation of the XML
+format used to represent properties of checkpoints.
+
+=over 4
+
+=item B<checkpoint-create> I<domain> [I<xmlfile>] {
I<--redefine>
+| [I<--no-metadata>] [I<--quiesce>]}
+
+Create a checkpoint for domain I<domain> with the properties specified
+in I<xmlfile> describing a <domaincheckpoint> top-level element. The
+format of the input XML file will be validated against an internal RNG
+schema (idential to using the L<virt-xml-validate(1)> tool). If
+I<xmlfile> is completely omitted, then libvirt will create a
+checkpoint with a name based on the current time.
+
+If I<--redefine> is specified, then all XML elements produced by
+B<checkpoint-dumpxml> are valid; this can be used to migrate
+checkpoint hierarchy from one machine to another, to recreate
+hierarchy for the case of a transient domain that goes away and is
+later recreated with the same name and UUID, or to make slight
+alterations in the checkpoint metadata (such as host-specific aspects
+of the domain XML embedded in the checkpoint). When this flag is
+supplied, the I<xmlfile> argument is mandatory.
+
+If I<--no-metadata> is specified, then the checkpoint is only created
+if the server does not require libvirt to track metadata for the
+checkpoint (some hypervisors may always fail if this flag is
+requested).
+
+If I<--quiesce> is specified, libvirt will try to use guest agent
+to freeze and unfreeze domain's mounted file systems. However,
+if domain has no guest agent, checkpoint creation will fail.
+
+Existence of checkpoint metadata will prevent attempts to B<undefine>
+a persistent domain. However, for transient domains, checkpoint
+metadata is silently lost when the domain quits running (whether
+by command such as B<destroy> or by internal guest action).
+
+For now, it is not possible to create checkpoints in a domain that has
+snapshots, although this restriction will be lifted in a future
+release.
+
+=item B<checkpoint-create-as> I<domain> {[I<--print-xml>]
+| [I<--no-metadata>]} [I<name>] [I<description>] [I<--quiesce>]
+[I<--diskspec>] B<diskspec>]...
+
+Create a checkpoint for domain I<domain> with the given <name> and
+<description>; if either value is omitted, libvirt will choose a
+value. If I<--print-xml> is specified, then XML appropriate for
+I<checkpoint-create> is output, rather than actually creating a
+checkpoint.
+
+The I<--diskspec> option can be used to control which guest disks
+participate in the checkpoint. This option can occur multiple times,
+according to the number of <disk> elements in the domain xml. Each
+<diskspec> is in the form B<disk[,checkpoint=type][,bitmap=name]>. A
+literal I<--diskspec> must precede each B<diskspec> unless
+all three of I<domain>, I<name>, and I<description> are also present.
+For example, a diskspec of "vda,checkpoint=bitmap,bitmap=map1"
+results in the following XML:
+ <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
+
+If I<--quiesce> is specified, libvirt will try to use guest agent
+to freeze and unfreeze domain's mounted file systems. However,
+if domain has no guest agent, checkpoint creation will fail.
+
+If I<--no-metadata> is specified, then the checkpoint is only created
+if the server does not require libvirt to track metadata for the
+checkpoint (some hypervisors may always fail if this flag is
+requested).
+
+For now, it is not possible to create checkpoints in a domain that has
+snapshots, although this restriction will be lifted in a future
+release.
+
+=item B<checkpoint-edit> I<domain> {I<checkpointname> |
I<--current>}
+
+Edit the XML configuration file for I<checkpointname> of a domain. If
+the domain has exactly one current checkpoint, I<--current> can be used
+in place of the checkpoint's name.
+
+This is equivalent to:
+
+ virsh checkpoint-dumpxml dom name > checkpoint.xml
+ vi checkpoint.xml (or make changes with your other text editor)
+ virsh checkpoint-create dom checkpoint.xml --redefine
+
+except that it does some error checking, including that the edits
+should not attempt to change the checkpoint name.
+
+The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
+variables, and defaults to C<vi>.
+
+=item B<checkpoint-info> I<domain> {I<checkpoint> |
I<--current>}
+
+Output basic information about a named <checkpoint>, or the current
+checkpoint with I<--current>.
+
+=item B<checkpoint-list> I<domain> [I<--metadata>]
[I<--no-metadata>]
+[{I<--parent> | I<--roots> | [{I<--tree> | I<--name>}]}]
[I<--topological>]
+[{[I<--from>] B<checkpoint> | I<--current>} [I<--descendants>]]
+[I<--leaves>] [I<--no-leaves>] [I<--current-only>]
[I<--no-current>]
+
+List all of the available checkpoints for the given domain, defaulting
+to show columns for the checkpoint name and creation time.
+
+Normally, table form output is sorted by checkpoint name; using
+I<--topological> instead sorts so that no child is listed before its
+ancestors (although there may be more than one possible ordering with
+this property).
+
+If I<--parent> is specified, add a column to the output table giving
+the name of the parent of each checkpoint. If I<--roots> is
+specified, the list will be filtered to just checkpoints that have no
+parents. If I<--tree> is specified, the output will be in a tree
+format, listing just checkpoint names. These three options are
+mutually exclusive. If I<--name> is specified only the checkpoint name
+is printed. This option is mutually exclusive with I<--tree>.
+
+If I<--from> is provided, filter the list to checkpoints which are
+children of the given B<checkpoint>; or if I<--current> is provided,
+start at the current checkpoint. When used in isolation or with
+I<--parent>, the list is limited to direct children unless
+I<--descendants> is also present. When used with I<--tree>, the use
+of I<--descendants> is implied. This option is not compatible with
+I<--roots>. Note that the starting point of I<--from> or I<--current>
+is not included in the list unless the I<--tree> option is also
+present.
+
+If I<--leaves> is specified, the list will be filtered to just
+checkpoints that have no children. Likewise, if I<--no-leaves> is
+specified, the list will be filtered to just checkpoints with
+children. (Note that omitting both options does no filtering, while
+providing both options will either produce the same list or error out
+depending on whether the server recognizes the flags). Filtering
+options are not compatible with I<--tree>.
+
+If I<--current-only> is specified, the list will be filtered to just
+current checkpoints. If I<--no-current> is specified, the list will
+be filtered to exclude current checkpoints.
+
+=item B<checkpoint-dumpxml> I<domain> {I<checkpoint> |
I<--current>}
+[I<--security-info>] [I<--no-domain>] [I<--size>]
+
+Output the checkpoint XML for the domain's checkpoint named
+I<checkpoint>. If the domain has exactly one current checkpoint,
+I<--current> can be used in place of the checkpoint's name. Using
+I<--security-info> will also include security sensitive information.
+Using I<--size> will add XML indicating the current size in bytes of
+guest data that has changed since the checkpoint was created (although
+remember that guest activity between a size check and actually
+creating a backup can result in the backup needing slightly more
+space). Using I<--no-domain> will omit the <domain> element from the
+output for a more compact view.
+
+=item B<checkpoint-parent> I<domain> {I<checkpoint> |
I<--current>}
+
+Output the name of the parent checkpoint, if any, for the given
+I<checkpoint>, or for the current checkpoint with I<--current>.
+
+=item B<checkpoint-delete> I<domain> {I<checkpoint> |
I<--current>}
+[I<--metadata>] [{I<--children> | I<--children-only>}]
+
+Delete the checkpoint for the domain named I<checkpoint>, or the
+current checkpoint with I<--current>. The record of which portions of
+the disk changed since the checkpoint are merged into the parent
+checkpoint (if any). If I<--children> is passed, then delete this
+checkpoint and any children of this checkpoint. If I<--children-only>
+is passed, then delete any children of this checkpoint, but leave this
+checkpoint intact. These two flags are mutually exclusive.
+
+If I<--metadata> is specified, then only delete the checkpoint
+metadata maintained by libvirt, while leaving the checkpoint contents
+intact for access by external tools; otherwise deleting a checkpoint
+also removes the ability to perform an incremental backup from that
+point in time.
+
+=back
+
=head1 NWFILTER COMMANDS
The following commands manipulate network filters. Network filters allow
--
2.20.1
8:26 a.m.
New subject: [libvirt] [PATCH v9 08/13] backup: Implement virsh support for checkpoints
On Sat, Jul 06, 2019 at 22:56:08 -0500, Eric Blake wrote:
Introduce a bunch of new virsh commands for managing checkpoints in
isolation. More commands are needed for performing incremental
backups, but these commands were easy to implement by modeling heavily
after virsh-snapshot.c. There is no need for checkpoint-revert or
checkpoint-current since those snapshot APIs have no checkpoint
counterpart. Similarly, it is not necessary to change which
checkpoint is current when redefining from XML, since checkpoints
expose whether they are current in the public XML (rather than the way
snapshots did it behind the scenese). checkpoint-list is a bit
simpler, in part because we don't have to cater to back-compat to
older API. checkpoint-info is a bit trickier, because it requires
parsing XML (maybe we'll want virDomainCheckpointIsCurrent() as an API
after all).
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
[...]
diff --git a/tools/virsh-checkpoint.c b/tools/virsh-checkpoint.c
new file mode 100644
index 0000000000..8200687f8a
--- /dev/null
+++ b/tools/virsh-checkpoint.c
@@ -0,0 +1,1226 @@
[...]
+static const vshCmdOptDef opts_checkpoint_create[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "xmlfile",
+ .type = VSH_OT_STRING,
+ .help = N_("domain checkpoint XML")
+ },
+ {.name = "redefine",
+ .type = VSH_OT_BOOL,
+ .help = N_("redefine metadata for existing checkpoint")
+ },
+ {.name = "no-metadata",
+ .type = VSH_OT_BOOL,
+ .help = N_("create checkpoint but create no metadata")
+ },
This needs to be deleted. [1]
+ {.name = "quiesce",
+ .type = VSH_OT_BOOL,
+ .help = N_("quiesce guest's file systems")
+ },
+ {.name = NULL}
+};
+
+static bool
+cmdCheckpointCreate(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ bool ret = false;
+ const char *from = NULL;
+ char *buffer = NULL;
+ unsigned int flags = 0;
+
+ if (vshCommandOptBool(cmd, "redefine"))
+ flags |= VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE;
+ if (vshCommandOptBool(cmd, "no-metadata"))
+ flags |= VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA;
[1]
[...]
+static const vshCmdOptDef opts_checkpoint_create_as[] = {
+ VIRSH_COMMON_OPT_DOMAIN_FULL(0),
+ {.name = "name",
+ .type = VSH_OT_STRING,
+ .help = N_("name of checkpoint")
+ },
+ {.name = "description",
+ .type = VSH_OT_STRING,
+ .help = N_("description of checkpoint")
+ },
+ {.name = "print-xml",
+ .type = VSH_OT_BOOL,
+ .help = N_("print XML document rather than create")
+ },
+ {.name = "no-metadata",
+ .type = VSH_OT_BOOL,
+ .help = N_("take checkpoint but create no metadata")
[1]
+static bool
+cmdCheckpointCreateAs(vshControl *ctl,
+ const vshCmd *cmd)
+{
+ virDomainPtr dom = NULL;
+ bool ret = false;
+ char *buffer = NULL;
+ const char *name = NULL;
+ const char *desc = NULL;
+ virBuffer buf = VIR_BUFFER_INITIALIZER;
+ unsigned int flags = 0;
+ const vshCmdOpt *opt = NULL;
+
+ if (vshCommandOptBool(cmd, "no-metadata"))
+ flags |= VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA;
[1]
[...]
+/* Helper for resolving {--current | --ARG name} into a checkpoint
+ * belonging to DOM. On success, populate *CHK and *NAME, before
+ * returning 0. On failure, return -1 after issuing an error
+ * message. */
+static int
+virshLookupCheckpoint(vshControl *ctl,
+ const vshCmd *cmd,
+ const char *arg,
+ virDomainPtr dom,
+ virDomainCheckpointPtr *chk,
+ const char **name)
+{
+ bool current = vshCommandOptBool(cmd, "current");
+ const char *chkname = NULL;
+
+ if (vshCommandOptStringReq(ctl, cmd, arg, &chkname) < 0)
+ return -1;
+
+ if (current && chkname) {
+ vshError(ctl, _("--%s and --current are mutually exclusive"), arg);
+ return -1;
+ }
+
+ if (chkname) {
+ *chk = virDomainCheckpointLookupByName(dom, chkname, 0);
+ } else if (current) {
+ int count;
+ virDomainCheckpointPtr *checkpoints = NULL;
+
+ count = virDomainListAllCheckpoints(dom, &checkpoints,
+ VIR_DOMAIN_CHECKPOINT_LIST_CURRENT);
+ if (count < 0)
+ return -1;
+ if (count == 0) {
+ vshError(ctl, _("domain has no current checkpoint"));
+ return -1;
+ }
+ if (count > 1) {
+ while (count-- > 0)
+ virDomainCheckpointFree(checkpoints[count]);
+ VIR_FREE(checkpoints);
+ vshError(ctl, _("domain has more than one current checkpoint"));
Ummm, so what's the point of all this? I'd rather not include any of
this if it's not done properly. [2]
+ return -1;
+ }
+ *chk = checkpoints[0];
+ VIR_FREE(checkpoints);
+ } else {
+ vshError(ctl, _("--%s or --current is required"), arg);
+ return -1;
+ }
+ if (!*chk) {
+ vshReportError(ctl);
+ return -1;
+ }
+
+ *name = virDomainCheckpointGetName(*chk);
+ return 0;
+}
[...]
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 4dffcafea0..8d69d349e9 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
[...]
@@ -4655,6 +4669,10 @@ a persistent domain. However, for transient
domains, snapshot
metadata is silently lost when the domain quits running (whether
by command such as B<destroy> or by internal guest action).
+For now, it is not possible to create snapshots in a domain that has
+checkpoints, although this restriction will be lifted in a future
+release.
Next time please consider splitting out the tangentially related stuff
such as this or the changes to snapshot lists into separate commits to
improve review comfort.
+
=item B<snapshot-create-as> I<domain> {[I<--print-xml>]
[I<--no-metadata>] [I<--halt>] [I<--reuse-external>]} [I<name>]
[I<description>] [I<--disk-only> [I<--quiesce>]] [I<--atomic>]
[...]
@@ -4892,6 +4914,191 @@ the data contents from that point in time.
=back
+=head1 CHECKPOINT COMMANDS
+
+The following commands manipulate domain checkpoints. Checkpoints serve as
+a point in time to identify which portions of a guest's disks have changed
+after that time, making it possible to perform incremental and differential
+backups. Checkpoints are identified with a unique name. See
+L<https://libvirt.org/formatcheckpoint.html> for documentation of the XML
+format used to represent properties of checkpoints.
+
+=over 4
+
+=item B<checkpoint-create> I<domain> [I<xmlfile>] {
I<--redefine>
+| [I<--no-metadata>] [I<--quiesce>]}
+
+Create a checkpoint for domain I<domain> with the properties specified
+in I<xmlfile> describing a <domaincheckpoint> top-level element. The
+format of the input XML file will be validated against an internal RNG
+schema (idential to using the L<virt-xml-validate(1)> tool). If
+I<xmlfile> is completely omitted, then libvirt will create a
+checkpoint with a name based on the current time.
+
+If I<--redefine> is specified, then all XML elements produced by
+B<checkpoint-dumpxml> are valid; this can be used to migrate
+checkpoint hierarchy from one machine to another, to recreate
+hierarchy for the case of a transient domain that goes away and is
+later recreated with the same name and UUID, or to make slight
+alterations in the checkpoint metadata (such as host-specific aspects
+of the domain XML embedded in the checkpoint). When this flag is
+supplied, the I<xmlfile> argument is mandatory.
+
+If I<--no-metadata> is specified, then the checkpoint is only created
+if the server does not require libvirt to track metadata for the
+checkpoint (some hypervisors may always fail if this flag is
+requested).
[1]
+
+If I<--quiesce> is specified, libvirt will try to use guest agent
+to freeze and unfreeze domain's mounted file systems. However,
+if domain has no guest agent, checkpoint creation will fail.
+
+Existence of checkpoint metadata will prevent attempts to B<undefine>
+a persistent domain. However, for transient domains, checkpoint
+metadata is silently lost when the domain quits running (whether
+by command such as B<destroy> or by internal guest action).
+
+For now, it is not possible to create checkpoints in a domain that has
+snapshots, although this restriction will be lifted in a future
+release.
+
+=item B<checkpoint-create-as> I<domain> {[I<--print-xml>]
+| [I<--no-metadata>]} [I<name>] [I<description>] [I<--quiesce>]
+[I<--diskspec>] B<diskspec>]...
+
+Create a checkpoint for domain I<domain> with the given <name> and
+<description>; if either value is omitted, libvirt will choose a
+value. If I<--print-xml> is specified, then XML appropriate for
+I<checkpoint-create> is output, rather than actually creating a
+checkpoint.
+
+The I<--diskspec> option can be used to control which guest disks
+participate in the checkpoint. This option can occur multiple times,
+according to the number of <disk> elements in the domain xml. Each
+<diskspec> is in the form B<disk[,checkpoint=type][,bitmap=name]>. A
+literal I<--diskspec> must precede each B<diskspec> unless
+all three of I<domain>, I<name>, and I<description> are also present.
+For example, a diskspec of "vda,checkpoint=bitmap,bitmap=map1"
+results in the following XML:
+ <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
+
+If I<--quiesce> is specified, libvirt will try to use guest agent
+to freeze and unfreeze domain's mounted file systems. However,
+if domain has no guest agent, checkpoint creation will fail.
+
+If I<--no-metadata> is specified, then the checkpoint is only created
+if the server does not require libvirt to track metadata for the
+checkpoint (some hypervisors may always fail if this flag is
+requested).
[1]
+
+For now, it is not possible to create checkpoints in a domain that has
+snapshots, although this restriction will be lifted in a future
+release.
+
ACK if you get rid of [1], [2] and all uses of VIRSH_COMMON_OPT_CURRENT
in this patch.
10:56 p.m.
New subject: [libvirt] [PATCH v9 09/13] backup: test: Implement metadata tracking for checkpoint APIs
A lot of this work heavily copies from the existing snapshot APIs.
The test driver doesn't really have to do anything more than just
expose an interface into libvirt metadata, making it possible to test
saving and restoring XML, and tracking relations between multiple
checkpoints.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/test/test_driver.c | 390 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 390 insertions(+)
diff --git a/src/test/test_driver.c b/src/test/test_driver.c
index e7ad4dbbd7..ddc8867bdd 100644
--- a/src/test/test_driver.c
+++ b/src/test/test_driver.c
@@ -39,6 +39,7 @@
#include "viralloc.h"
#include "virnetworkobj.h"
#include "interface_conf.h"
+#include "checkpoint_conf.h"
#include "domain_conf.h"
#include "domain_event.h"
#include "network_event.h"
@@ -63,6 +64,7 @@
#include "virdomainobjlist.h"
#include "virinterfaceobj.h"
#include "virhostcpu.h"
+#include "virdomaincheckpointobjlist.h"
#include "virdomainsnapshotobjlist.h"
#include "virkeycode.h"
@@ -7174,6 +7176,12 @@ testDomainSnapshotCreateXML(virDomainPtr domain,
if (!(vm = testDomObjFromDomain(domain)))
goto cleanup;
+ if (virDomainListCheckpoints(vm->checkpoints, NULL, domain, NULL, 0) > 0) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot create snapshot while checkpoint exists"));
+ goto cleanup;
+ }
+
if (!vm->persistent && (flags & VIR_DOMAIN_SNAPSHOT_CREATE_HALT)) {
virReportError(VIR_ERR_OPERATION_INVALID, "%s",
_("cannot halt after transient domain snapshot"));
@@ -7565,7 +7573,381 @@ testDomainRevertToSnapshot(virDomainSnapshotPtr snapshot,
return ret;
}
+/*
+ * Checkpoint APIs
+ */
+static int
+testDomainCheckpointDiscardAll(void *payload,
+ const void *name ATTRIBUTE_UNUSED,
+ void *data)
+{
+ virDomainMomentObjPtr chk = payload;
+ testMomentRemoveDataPtr curr = data;
+
+ curr->current |= virDomainCheckpointObjListRemove(curr->vm->checkpoints,
+ chk);
+ return 0;
+}
+
+static virDomainObjPtr
+testDomObjFromCheckpoint(virDomainCheckpointPtr checkpoint)
+{
+ return testDomObjFromDomain(checkpoint->domain);
+}
+
+static virDomainMomentObjPtr
+testCheckObjFromName(virDomainObjPtr vm,
+ const char *name)
+{
+ virDomainMomentObjPtr chk = NULL;
+
+ chk = virDomainCheckpointFindByName(vm->checkpoints, name);
+ if (!chk)
+ virReportError(VIR_ERR_NO_DOMAIN_CHECKPOINT,
+ _("no domain checkpoint with matching name
'%s'"),
+ name);
+
+ return chk;
+}
+
+static virDomainMomentObjPtr
+testCheckObjFromCheckpoint(virDomainObjPtr vm,
+ virDomainCheckpointPtr checkpoint)
+{
+ return testCheckObjFromName(vm, checkpoint->name);
+}
+
+static virDomainCheckpointPtr
+testDomainCheckpointCreateXML(virDomainPtr domain,
+ const char *xmlDesc,
+ unsigned int flags)
+{
+ testDriverPtr privconn = domain->conn->privateData;
+ virDomainObjPtr vm = NULL;
+ char *xml = NULL;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+ virDomainMomentObjPtr current = NULL;
+ bool update_current = true;
+ bool *set_current = NULL;
+ bool redefine = flags & VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE;
+ unsigned int parse_flags = 0;
+ virDomainMomentObjPtr other = NULL;
+ VIR_AUTOUNREF(virDomainCheckpointDefPtr) def = NULL;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE |
+ VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA |
+ VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE, NULL);
+
+ if (redefine) {
+ parse_flags |= VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE;
+ set_current = &update_current;
+ }
+ if (redefine || (flags & VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA))
+ update_current = false;
+
+ if (!(vm = testDomObjFromDomain(domain)))
+ goto cleanup;
+
+ if (virDomainSnapshotObjListNum(vm->snapshots, NULL, 0) > 0) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot create checkpoint while snapshot exists"));
+ goto cleanup;
+ }
+
+ if (!virDomainObjIsActive(vm)) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot create checkpoint for inactive domain"));
+ goto cleanup;
+ }
+
+ if (!(def = virDomainCheckpointDefParseString(xmlDesc, privconn->caps,
+ privconn->xmlopt, set_current,
+ parse_flags)))
+ goto cleanup;
+
+ if (redefine) {
+ if (virDomainCheckpointRedefinePrep(domain, vm, &def, &chk,
+ privconn->xmlopt,
+ &update_current) < 0)
+ goto cleanup;
+ } else {
+ if (!(def->parent.dom = virDomainDefCopy(vm->def,
+ privconn->caps,
+ privconn->xmlopt,
+ NULL,
+ true)))
+ goto cleanup;
+
+ if (virDomainCheckpointAlignDisks(def) < 0)
+ goto cleanup;
+ }
+
+ if (!chk) {
+ if (!(chk = virDomainCheckpointAssignDef(vm->checkpoints, def)))
+ goto cleanup;
+
+ def = NULL;
+ }
+
+ current = virDomainCheckpointGetCurrent(vm->checkpoints);
+ if (current) {
+ if (!redefine &&
+ VIR_STRDUP(chk->def->parent_name, current->def->name) < 0)
+ goto cleanup;
+ if (update_current)
+ virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
+ }
+
+ /* actually do the checkpoint - except the test driver has nothing
+ * to actually do here */
+
+ /* If we fail after this point, there's not a whole lot we can do;
+ * we've successfully created the checkpoint, so we have to go
+ * forward the best we can.
+ */
+ checkpoint = virGetDomainCheckpoint(domain, chk->def->name);
+
+ cleanup:
+ if (checkpoint && !(flags & VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA)) {
+ if (update_current)
+ virDomainCheckpointSetCurrent(vm->checkpoints, chk);
+ other = virDomainCheckpointFindByName(vm->checkpoints,
+ chk->def->parent_name);
+ virDomainMomentSetParent(chk, other);
+ } else if (chk) {
+ virDomainCheckpointObjListRemove(vm->checkpoints, chk);
+ }
+
+ virDomainObjEndAPI(&vm);
+ VIR_FREE(xml);
+ return checkpoint;
+}
+
+
+static int
+testDomainListAllCheckpoints(virDomainPtr domain,
+ virDomainCheckpointPtr **chks,
+ unsigned int flags)
+{
+ virDomainObjPtr vm = NULL;
+ int n = -1;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_LIST_ROOTS |
+ VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL |
+ VIR_DOMAIN_CHECKPOINT_FILTERS_ALL, -1);
+
+ if (!(vm = testDomObjFromDomain(domain)))
+ return -1;
+
+ n = virDomainListCheckpoints(vm->checkpoints, NULL, domain, chks, flags);
+
+ virDomainObjEndAPI(&vm);
+ return n;
+}
+
+
+static int
+testDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
+ virDomainCheckpointPtr **chks,
+ unsigned int flags)
+{
+ virDomainObjPtr vm = NULL;
+ virDomainMomentObjPtr chk = NULL;
+ int n = -1;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS |
+ VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL |
+ VIR_DOMAIN_CHECKPOINT_FILTERS_ALL, -1);
+
+ if (!(vm = testDomObjFromCheckpoint(checkpoint)))
+ return -1;
+
+ if (!(chk = testCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+
+ n = virDomainListCheckpoints(vm->checkpoints, chk, checkpoint->domain,
+ chks, flags);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return n;
+}
+
+
+static virDomainCheckpointPtr
+testDomainCheckpointLookupByName(virDomainPtr domain,
+ const char *name,
+ unsigned int flags)
+{
+ virDomainObjPtr vm;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+
+ virCheckFlags(0, NULL);
+
+ if (!(vm = testDomObjFromDomain(domain)))
+ return NULL;
+
+ if (!(chk = testCheckObjFromName(vm, name)))
+ goto cleanup;
+
+ checkpoint = virGetDomainCheckpoint(domain, chk->def->name);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return checkpoint;
+}
+
+
+static virDomainCheckpointPtr
+testDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virDomainObjPtr vm;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainCheckpointPtr parent = NULL;
+
+ virCheckFlags(0, NULL);
+
+ if (!(vm = testDomObjFromCheckpoint(checkpoint)))
+ return NULL;
+
+ if (!(chk = testCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+
+ if (!chk->def->parent_name) {
+ virReportError(VIR_ERR_NO_DOMAIN_CHECKPOINT,
+ _("checkpoint '%s' does not have a parent"),
+ chk->def->name);
+ goto cleanup;
+ }
+
+ parent = virGetDomainCheckpoint(checkpoint->domain, chk->def->parent_name);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return parent;
+}
+
+
+static char *
+testDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ testDriverPtr privconn = checkpoint->domain->conn->privateData;
+ virDomainObjPtr vm = NULL;
+ char *xml = NULL;
+ virDomainMomentObjPtr chk = NULL;
+ size_t i;
+ virDomainCheckpointDefPtr chkdef;
+ unsigned int format_flags;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_XML_SECURE |
+ VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN |
+ VIR_DOMAIN_CHECKPOINT_XML_SIZE, NULL);
+
+ if (!(vm = testDomObjFromCheckpoint(checkpoint)))
+ return NULL;
+
+ if (!(chk = testCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+ chkdef = virDomainCheckpointObjGetDef(chk);
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_XML_SIZE) {
+ if (virDomainObjCheckActive(vm) < 0)
+ goto cleanup;
+
+ for (i = 0; i < chkdef->ndisks; i++) {
+ virDomainCheckpointDiskDefPtr disk = &chkdef->disks[i];
+
+ if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP)
+ continue;
+ disk->size = 1024; /* Any number will do... */
+ }
+ }
+
+ format_flags = virDomainCheckpointFormatConvertXMLFlags(flags);
+ if (chk == virDomainCheckpointGetCurrent(vm->checkpoints))
+ format_flags |= VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT;
+ xml = virDomainCheckpointDefFormat(chkdef, privconn->caps,
+ privconn->xmlopt, format_flags);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return xml;
+}
+
+
+static int
+testDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virDomainObjPtr vm = NULL;
+ int ret = -1;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainMomentObjPtr parentchk = NULL;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN |
+ VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY |
+ VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY, -1);
+
+ if (!(vm = testDomObjFromCheckpoint(checkpoint)))
+ return -1;
+
+ if (!(chk = testCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+
+ if (flags & (VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN |
+ VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY)) {
+ testMomentRemoveData rem;
+
+ rem.vm = vm;
+ rem.current = false;
+ virDomainMomentForEachDescendant(chk, testDomainCheckpointDiscardAll,
+ &rem);
+ if (rem.current)
+ virDomainCheckpointSetCurrent(vm->checkpoints, chk);
+ } else if (chk->nchildren) {
+ testMomentReparentData rep;
+
+ rep.parent = chk->parent;
+ rep.vm = vm;
+ rep.err = 0;
+ virDomainMomentForEachChild(chk, testDomainMomentReparentChildren,
+ &rep);
+ if (rep.err < 0)
+ goto cleanup;
+ virDomainMomentMoveChildren(chk, chk->parent);
+ }
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY) {
+ virDomainMomentDropChildren(chk);
+ } else {
+ virDomainMomentDropParent(chk);
+ if (chk == virDomainCheckpointGetCurrent(vm->checkpoints)) {
+ if (chk->def->parent_name) {
+ parentchk = virDomainCheckpointFindByName(vm->checkpoints,
+ chk->def->parent_name);
+ if (!parentchk)
+ VIR_WARN("missing parent checkpoint matching name
'%s'",
+ chk->def->parent_name);
+ }
+ virDomainCheckpointSetCurrent(vm->checkpoints, parentchk);
+ }
+ virDomainCheckpointObjListRemove(vm->checkpoints, chk);
+ }
+
+ ret = 0;
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return ret;
+}
+
+/*
+ * Test driver
+ */
static virHypervisorDriver testHypervisorDriver = {
.name = "Test",
.connectOpen = testConnectOpen, /* 0.1.1 */
@@ -7686,6 +8068,14 @@ static virHypervisorDriver testHypervisorDriver = {
.domainSnapshotDelete = testDomainSnapshotDelete, /* 1.1.4 */
.connectBaselineCPU = testConnectBaselineCPU, /* 1.2.0 */
+ .domainCheckpointCreateXML = testDomainCheckpointCreateXML, /* 5.6.0 */
+ .domainCheckpointGetXMLDesc = testDomainCheckpointGetXMLDesc, /* 5.6.0 */
+
+ .domainListAllCheckpoints = testDomainListAllCheckpoints, /* 5.6.0 */
+ .domainCheckpointListAllChildren = testDomainCheckpointListAllChildren, /* 5.6.0 */
+ .domainCheckpointLookupByName = testDomainCheckpointLookupByName, /* 5.6.0 */
+ .domainCheckpointGetParent = testDomainCheckpointGetParent, /* 5.6.0 */
+ .domainCheckpointDelete = testDomainCheckpointDelete, /* 5.6.0 */
};
static virNetworkDriver testNetworkDriver = {
--
2.20.1
8:28 a.m.
New subject: [libvirt] [PATCH v9 09/13] backup: test: Implement metadata tracking for checkpoint APIs
On Sat, Jul 06, 2019 at 22:56:09 -0500, Eric Blake wrote:
A lot of this work heavily copies from the existing snapshot APIs.
The test driver doesn't really have to do anything more than just
expose an interface into libvirt metadata, making it possible to test
saving and restoring XML, and tracking relations between multiple
checkpoints.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/test/test_driver.c | 390 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 390 insertions(+)
ACK
8:30 a.m.
New subject: [libvirt] [PATCH v9 09/13] backup: test: Implement metadata tracking for checkpoint APIs
On Sat, Jul 06, 2019 at 22:56:09 -0500, Eric Blake wrote:
A lot of this work heavily copies from the existing snapshot APIs.
The test driver doesn't really have to do anything more than just
expose an interface into libvirt metadata, making it possible to test
saving and restoring XML, and tracking relations between multiple
checkpoints.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/test/test_driver.c | 390 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 390 insertions(+)
diff --git a/src/test/test_driver.c b/src/test/test_driver.c
index e7ad4dbbd7..ddc8867bdd 100644
--- a/src/test/test_driver.c
+++ b/src/test/test_driver.c
[...]
@@ -7174,6 +7176,12 @@ testDomainSnapshotCreateXML(virDomainPtr
domain,
if (!(vm = testDomObjFromDomain(domain)))
goto cleanup;
+ if (virDomainListCheckpoints(vm->checkpoints, NULL, domain, NULL, 0) > 0) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot create snapshot while checkpoint exists"));
+ goto cleanup;
+ }
+
Hmmm, I don't see much point in modeling this though ...
Especially since I don't think it will be removed once the qemu driver
gains the ability.
10:56 p.m.
New subject: [libvirt] [PATCH v9 10/13] backup: Add virsh-checkpoints test
Similar to virsh-snapshots (which also gets a minor tweak, to prove we
properly lock out one API from the other until later integration
efforts figure out the best way to proceed). Provides decent coverage
of the checkpoint API, the test driver implementation, and the virsh
access to the API.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
tests/Makefile.am | 1 +
tests/virsh-checkpoint | 181 +++++++++++++++++++++++++++++++++++++++++
tests/virsh-snapshot | 12 ++-
3 files changed, 193 insertions(+), 1 deletion(-)
create mode 100755 tests/virsh-checkpoint
diff --git a/tests/Makefile.am b/tests/Makefile.am
index 1fd698c2d2..0ae1e51e03 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -414,6 +414,7 @@ libvirtd_test_scripts = \
virsh-schedinfo \
virsh-self-test \
virt-admin-self-test \
+ virsh-checkpoint \
virsh-snapshot \
virsh-start \
virsh-undefine \
diff --git a/tests/virsh-checkpoint b/tests/virsh-checkpoint
new file mode 100755
index 0000000000..13888cf8eb
--- /dev/null
+++ b/tests/virsh-checkpoint
@@ -0,0 +1,181 @@
+#!/bin/sh
+# simple testing of checkpoint APIs on test driver
+
+# Copyright (C) 2019 Red Hat, Inc.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see
+# <http://www.gnu.org/licenses/>;.
+
+. "$(dirname $0)/test-lib.sh"
+
+if test "$VERBOSE" = yes; then
+ set -x
+ $abs_top_builddir/tools/virsh --version
+fi
+
+fail=0
+
+mock_xdg_ || framework_failure
+
+# The test driver loses states between restarts, so we perform a script
+# with some convenient markers for later post-processing of output.
+$abs_top_builddir/tools/virsh --connect test:///default >out 2>err '
+ # Create a series of checkpoints, with names that intentionally sort
+ # differently by topology than by name. For now, it is not possible
+ # to create fanout without hacking through redefines.
+ checkpoint-create-as test c1
+ checkpoint-create-as test c3
+ checkpoint-create-as test c2
+ # snapshots cannot be created while checkpoints exist
+ echo --err marker
+ snapshot-create-as test s1
+ echo --err marker
+ # Checking tree view (siblings sorted alphabetically)
+ checkpoint-list test --tree
+ # Demonstrate list filtering
+ checkpoint-list test --current
+ checkpoint-list test --current-only --name
+ checkpoint-list test --roots
+ checkpoint-list test --leaves
+ checkpoint-list test --parent --no-leaves
+ checkpoint-list test --from c3
+ checkpoint-list test --from c1 --descendants --name
+ # Now the tree is linear, so we have an unambiguous topological order
+ checkpoint-list test --name
+ checkpoint-list test --name --topological
+ checkpoint-list test --name --no-current
+ # Capture some XML for later redefine
+ checkpoint-delete test c1
+ echo "<!--MarkerA-->"
+ checkpoint-dumpxml test c3
+ echo "<!--MarkerB-->"
+ checkpoint-dumpxml test --current
+ echo "<!--MarkerC-->"
+ # Deleting current checkpoint moves current up to remaining parent
+ checkpoint-delete test --children-only c3
+ checkpoint-list test --current-only --name
+ checkpoint-delete test --children c3
+ checkpoint-list test --current-only --name
+ # All done
+' || fail=1
+
+# First part is expected output, --tree results in trailing spaces,
+# and checkpoint-list produces timestamps
+sed 's/ *$//; s/[0-9-]\{10\} [0-9:.]* .[0-9]\{4\}/TIMESTAMP/;
+ /MarkerA/,/MarkerC/d' < out > out.cooked || fail=1
+# Second part holds domain checkpoint XMLs
+sed -n '/MarkerA/,/MarkerB/p' < out > c3.xml || fail=1
+sed -n '/MarkerB/,/MarkerC/p' < out > c2.xml || fail=1
+
+cat <<\EOF > exp || fail=1
+Domain checkpoint c1 created
+Domain checkpoint c3 created
+Domain checkpoint c2 created
+
+
+
+c1
+ |
+ +- c3
+ |
+ +- c2
+
+
+ Name Creation Time
+-----------------------
+
+c2
+
+ Name Creation Time
+-----------------------------------
+ c1 TIMESTAMP
+
+ Name Creation Time
+-----------------------------------
+ c2 TIMESTAMP
+
+ Name Creation Time Parent
+--------------------------------------------
+ c1 TIMESTAMP
+ c3 TIMESTAMP c1
+
+ Name Creation Time
+-----------------------------------
+ c2 TIMESTAMP
+
+c2
+c3
+
+c1
+c2
+c3
+
+c1
+c3
+c2
+
+c1
+c3
+
+Domain checkpoint c1 deleted
+
+Domain checkpoint c3 children deleted
+
+c3
+
+Domain checkpoint c3 deleted
+
+
+EOF
+compare exp out.cooked || fail=1
+
+cat <<EOF > exp || fail=1
+error: marker
+error: Operation not supported: cannot create snapshot while checkpoint exists
+error: marker
+EOF
+compare exp err || fail=1
+
+# Restore state with redefine
+$abs_top_builddir/tools/virsh -c test:///default >out 2>err <<EOF || fail=1
+ # Redefine must be in topological order; this will fail
+ checkpoint-create test --redefine c2.xml
+ echo --err marker
+ # This is the right order
+ checkpoint-create test --redefine c3.xml
+ checkpoint-create test --redefine c2.xml
+ checkpoint-info test --current
+EOF
+
+cat <<\EOF > exp || fail=1
+
+
+Domain checkpoint s3 created from 's3.xml'
+Domain checkpoint s2 created from 's2.xml'
+Name: s2
+Domain: test
+Current: yes
+Parent: s3
+Children: 0
+Descendants: 0
+
+EOF
+
+cat <<EOF > exp || fail=1
+error: invalid argument: parent c3 for moment c2 not found
+error: marker
+EOF
+compare exp err || fail=1
+
+(exit $fail); exit $fail
diff --git a/tests/virsh-snapshot b/tests/virsh-snapshot
index 8b0813233f..feb2f097e4 100755
--- a/tests/virsh-snapshot
+++ b/tests/virsh-snapshot
@@ -44,6 +44,10 @@ $abs_top_builddir/tools/virsh --connect test:///default >out
2>err '
snapshot-revert test s1
snapshot-create-as test s7
snapshot-create-as test s8
+ # checkpoints cannot be created while snapshots exist
+ echo --err marker
+ checkpoint-create-as test c1
+ echo --err marker
# Checking tree view (siblings sorted alphabetically)
snapshot-list test --tree
# Current was last one created, but we can change that
@@ -86,7 +90,7 @@ $abs_top_builddir/tools/virsh --connect test:///default >out 2>err
'
# and snapshot-list produces timestamps
sed 's/ *$//; s/[0-9-]\{10\} [0-9:.]* .[0-9]\{4\}/TIMESTAMP/;
/MarkerA/,/MarkerC/d' < out > out.cooked || fail=1
-# Second part holds domain XMLs
+# Second part holds domain snapshot XMLs
sed -n '/MarkerA/,/MarkerB/p' < out > s3.xml || fail=1
sed -n '/MarkerB/,/MarkerC/p' < out > s2.xml || fail=1
@@ -102,6 +106,9 @@ Domain snapshot s4 created
Domain snapshot s7 created
Domain snapshot s8 created
+
+
+
s1
|
+- s3
@@ -178,6 +185,9 @@ compare exp out.cooked || fail=1
cat <<EOF > exp || fail=1
error: marker
+error: Operation not supported: cannot create checkpoint while snapshot exists
+error: marker
+error: marker
error: domain 'test' has no current snapshot
error: marker
EOF
--
2.20.1
8:32 a.m.
New subject: [libvirt] [PATCH v9 10/13] backup: Add virsh-checkpoints test
On Sat, Jul 06, 2019 at 22:56:10 -0500, Eric Blake wrote:
Similar to virsh-snapshots (which also gets a minor tweak, to prove
we
properly lock out one API from the other until later integration
efforts figure out the best way to proceed). Provides decent coverage
of the checkpoint API, the test driver implementation, and the virsh
access to the API.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
tests/Makefile.am | 1 +
tests/virsh-checkpoint | 181 +++++++++++++++++++++++++++++++++++++++++
tests/virsh-snapshot | 12 ++-
ACK, although as noted in review for 9/13 I don't see a point in
modelling the interlocking with snapshots in the test driver as there
are no technical reasons preventing it.
10:56 p.m.
New subject: [libvirt] [PATCH v9 11/13] backup: qemu: Implement metadata tracking for checkpoint APIs
A lot of this work heavily copies from the existing snapshot
APIs. The interaction with qemu during create/delete still
needs to be implemented, but this takes care of all the libvirt
metadata (saving and restoring XML, and tracking the relations
between multiple checkpoints).
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/qemu/qemu_block.h | 3 +
src/qemu/qemu_conf.h | 2 +
src/qemu/qemu_domain.h | 15 +
src/qemu/qemu_block.c | 12 +
src/qemu/qemu_conf.c | 5 +
src/qemu/qemu_domain.c | 133 ++++++++
src/qemu/qemu_driver.c | 675 +++++++++++++++++++++++++++++++++++++++++
7 files changed, 845 insertions(+)
diff --git a/src/qemu/qemu_block.h b/src/qemu/qemu_block.h
index 934a1f125d..768a7cfc2e 100644
--- a/src/qemu/qemu_block.h
+++ b/src/qemu/qemu_block.h
@@ -159,3 +159,6 @@ qemuBlockSnapshotAddLegacy(virJSONValuePtr actions,
virDomainDiskDefPtr disk,
virStorageSourcePtr newsrc,
bool reuse);
+
+const char *
+qemuBlockNodeLookup(virDomainObjPtr vm, const char *disk);
diff --git a/src/qemu/qemu_conf.h b/src/qemu/qemu_conf.h
index e51514a344..da0735775c 100644
--- a/src/qemu/qemu_conf.h
+++ b/src/qemu/qemu_conf.h
@@ -28,6 +28,7 @@
#include "capabilities.h"
#include "network_conf.h"
#include "domain_conf.h"
+#include "checkpoint_conf.h"
#include "snapshot_conf.h"
#include "domain_event.h"
#include "virthread.h"
@@ -101,6 +102,7 @@ struct _virQEMUDriverConfig {
char *cacheDir;
char *saveDir;
char *snapshotDir;
+ char *checkpointDir;
char *channelTargetDir;
char *nvramDir;
char *swtpmStorageDir;
diff --git a/src/qemu/qemu_domain.h b/src/qemu/qemu_domain.h
index 3eea8b0f96..b1ec4af82f 100644
--- a/src/qemu/qemu_domain.h
+++ b/src/qemu/qemu_domain.h
@@ -748,6 +748,21 @@ int qemuDomainMomentDiscardAll(void *payload,
int qemuDomainSnapshotDiscardAllMetadata(virQEMUDriverPtr driver,
virDomainObjPtr vm);
+int qemuDomainCheckpointWriteMetadata(virDomainObjPtr vm,
+ virDomainMomentObjPtr checkpoint,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ const char *checkpointDir);
+
+int qemuDomainCheckpointDiscard(virQEMUDriverPtr driver,
+ virDomainObjPtr vm,
+ virDomainMomentObjPtr chk,
+ bool update_current,
+ bool metadata_only);
+
+int qemuDomainCheckpointDiscardAllMetadata(virQEMUDriverPtr driver,
+ virDomainObjPtr vm);
+
void qemuDomainRemoveInactive(virQEMUDriverPtr driver,
virDomainObjPtr vm);
diff --git a/src/qemu/qemu_block.c b/src/qemu/qemu_block.c
index 0a6522577d..5f5e330479 100644
--- a/src/qemu/qemu_block.c
+++ b/src/qemu/qemu_block.c
@@ -1821,3 +1821,15 @@ qemuBlockStorageGetCopyOnReadProps(virDomainDiskDefPtr disk)
return ret;
}
+
+const char *
+qemuBlockNodeLookup(virDomainObjPtr vm, const char *disk)
+{
+ size_t i;
+
+ for (i = 0; i < vm->def->ndisks; i++) {
+ if (STREQ(vm->def->disks[i]->dst, disk))
+ return vm->def->disks[i]->src->nodeformat;
+ }
+ return NULL;
+}
diff --git a/src/qemu/qemu_conf.c b/src/qemu/qemu_conf.c
index e0195dac29..7a02ea5b07 100644
--- a/src/qemu/qemu_conf.c
+++ b/src/qemu/qemu_conf.c
@@ -160,6 +160,8 @@ virQEMUDriverConfigPtr virQEMUDriverConfigNew(bool privileged)
goto error;
if (virAsprintf(&cfg->snapshotDir, "%s/snapshot",
cfg->libDir) < 0)
goto error;
+ if (virAsprintf(&cfg->checkpointDir, "%s/checkpoint",
cfg->libDir) < 0)
+ goto error;
if (virAsprintf(&cfg->autoDumpPath, "%s/dump", cfg->libDir)
< 0)
goto error;
if (virAsprintf(&cfg->channelTargetDir,
@@ -223,6 +225,8 @@ virQEMUDriverConfigPtr virQEMUDriverConfigNew(bool privileged)
goto error;
if (virAsprintf(&cfg->snapshotDir, "%s/qemu/snapshot",
cfg->configBaseDir) < 0)
goto error;
+ if (virAsprintf(&cfg->checkpointDir, "%s/qemu/checkpoint",
cfg->configBaseDir) < 0)
+ goto error;
if (virAsprintf(&cfg->autoDumpPath, "%s/qemu/dump",
cfg->configBaseDir) < 0)
goto error;
if (virAsprintf(&cfg->channelTargetDir,
@@ -335,6 +339,7 @@ static void virQEMUDriverConfigDispose(void *obj)
VIR_FREE(cfg->cacheDir);
VIR_FREE(cfg->saveDir);
VIR_FREE(cfg->snapshotDir);
+ VIR_FREE(cfg->checkpointDir);
VIR_FREE(cfg->channelTargetDir);
VIR_FREE(cfg->nvramDir);
diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c
index 6225ac23e2..03a143a228 100644
--- a/src/qemu/qemu_domain.c
+++ b/src/qemu/qemu_domain.c
@@ -55,6 +55,7 @@
#include "logging/log_manager.h"
#include "locking/domain_lock.h"
#include "virdomainsnapshotobjlist.h"
+#include "virdomaincheckpointobjlist.h"
#ifdef MAJOR_IN_MKDEV
# include <sys/mkdev.h>
@@ -8719,6 +8720,39 @@ qemuDomainSnapshotWriteMetadata(virDomainObjPtr vm,
return ret;
}
+int
+qemuDomainCheckpointWriteMetadata(virDomainObjPtr vm,
+ virDomainMomentObjPtr checkpoint,
+ virCapsPtr caps,
+ virDomainXMLOptionPtr xmlopt,
+ const char *checkpointDir)
+{
+ unsigned int flags = VIR_DOMAIN_CHECKPOINT_FORMAT_SECURE;
+ virDomainCheckpointDefPtr def = virDomainCheckpointObjGetDef(checkpoint);
+ VIR_AUTOFREE(char *) newxml = NULL;
+ VIR_AUTOFREE(char *) chkDir = NULL;
+ VIR_AUTOFREE(char *) chkFile = NULL;
+
+ if (virDomainCheckpointGetCurrent(vm->checkpoints) == checkpoint)
+ flags |= VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT;
+ newxml = virDomainCheckpointDefFormat(def, caps, xmlopt, flags);
+ if (newxml == NULL)
+ return -1;
+
+ if (virAsprintf(&chkDir, "%s/%s", checkpointDir, vm->def->name)
< 0)
+ return -1;
+ if (virFileMakePath(chkDir) < 0) {
+ virReportSystemError(errno, _("cannot create checkpoint directory
'%s'"),
+ chkDir);
+ return -1;
+ }
+
+ if (virAsprintf(&chkFile, "%s/%s.xml", chkDir, def->parent.name)
< 0)
+ return -1;
+
+ return virXMLSaveFile(chkFile, NULL, "checkpoint-edit", newxml);
+}
+
/* The domain is expected to be locked and inactive. Return -1 on normal
* failure, 1 if we skipped a disk due to try_all. */
static int
@@ -8915,12 +8949,100 @@ qemuDomainSnapshotDiscardAllMetadata(virQEMUDriverPtr driver,
}
+/* Discard one checkpoint (or its metadata), without reparenting any children. */
+int
+qemuDomainCheckpointDiscard(virQEMUDriverPtr driver,
+ virDomainObjPtr vm,
+ virDomainMomentObjPtr chk,
+ bool update_parent,
+ bool metadata_only)
+{
+ char *chkFile = NULL;
+ int ret = -1;
+ virDomainMomentObjPtr parentchk = NULL;
+ virQEMUDriverConfigPtr cfg = virQEMUDriverGetConfig(driver);
+
+ if (!metadata_only) {
+ if (!virDomainObjIsActive(vm)) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot remove checkpoint from inactive
domain"));
+ goto cleanup;
+ } else {
+ /* TODO: Implement QMP sequence to merge bitmaps */
+ // qemuDomainObjPrivatePtr priv;
+ // priv = vm->privateData;
+ // qemuDomainObjEnterMonitor(driver, vm);
+ // /* we continue on even in the face of error */
+ // qemuMonitorDeleteCheckpoint(priv->mon, chk->def->name);
+ // ignore_value(qemuDomainObjExitMonitor(driver, vm));
+ }
+ }
+
+ if (virAsprintf(&chkFile, "%s/%s/%s.xml", cfg->checkpointDir,
+ vm->def->name, chk->def->name) < 0)
+ goto cleanup;
+
+ if (chk == virDomainCheckpointGetCurrent(vm->checkpoints)) {
+ virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
+ if (update_parent && chk->def->parent_name) {
+ parentchk = virDomainCheckpointFindByName(vm->checkpoints,
+ chk->def->parent_name);
+ if (!parentchk) {
+ VIR_WARN("missing parent checkpoint matching name
'%s'",
+ chk->def->parent_name);
+ } else {
+ virDomainCheckpointSetCurrent(vm->checkpoints, parentchk);
+ if (qemuDomainCheckpointWriteMetadata(vm, parentchk, driver->caps,
+ driver->xmlopt,
+ cfg->checkpointDir) < 0) {
+ VIR_WARN("failed to set parent checkpoint '%s' as
current",
+ chk->def->parent_name);
+ virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
+ }
+ }
+ }
+ }
+
+ if (unlink(chkFile) < 0)
+ VIR_WARN("Failed to unlink %s", chkFile);
+ if (update_parent)
+ virDomainMomentDropParent(chk);
+ virDomainCheckpointObjListRemove(vm->checkpoints, chk);
+
+ ret = 0;
+
+ cleanup:
+ VIR_FREE(chkFile);
+ virObjectUnref(cfg);
+ return ret;
+}
+
+int
+qemuDomainCheckpointDiscardAllMetadata(virQEMUDriverPtr driver,
+ virDomainObjPtr vm)
+{
+ virQEMUMomentRemove rem = {
+ .driver = driver,
+ .vm = vm,
+ .metadata_only = true,
+ .momentDiscard = qemuDomainCheckpointDiscard,
+ };
+
+ virDomainCheckpointForEach(vm->checkpoints, qemuDomainMomentDiscardAll,
+ &rem);
+ virDomainCheckpointObjListRemoveAll(vm->checkpoints);
+
+ return rem.err;
+}
+
+
static void
qemuDomainRemoveInactiveCommon(virQEMUDriverPtr driver,
virDomainObjPtr vm)
{
virQEMUDriverConfigPtr cfg;
VIR_AUTOFREE(char *) snapDir = NULL;
+ VIR_AUTOFREE(char *) chkDir = NULL;
cfg = virQEMUDriverGetConfig(driver);
@@ -8935,6 +9057,17 @@ qemuDomainRemoveInactiveCommon(virQEMUDriverPtr driver,
} else if (rmdir(snapDir) < 0 && errno != ENOENT) {
VIR_WARN("unable to remove snapshot directory %s", snapDir);
}
+ /* Remove any checkpoint metadata prior to removing the domain */
+ if (qemuDomainCheckpointDiscardAllMetadata(driver, vm) < 0) {
+ VIR_WARN("unable to remove all checkpoints for domain %s",
+ vm->def->name);
+ } else if (virAsprintf(&chkDir, "%s/%s", cfg->checkpointDir,
+ vm->def->name) < 0) {
+ VIR_WARN("unable to remove checkpoint directory %s/%s",
+ cfg->checkpointDir, vm->def->name);
+ } else if (rmdir(chkDir) < 0 && errno != ENOENT) {
+ VIR_WARN("unable to remove checkpoint directory %s", chkDir);
+ }
qemuExtDevicesCleanupHost(driver, vm->def);
virObjectUnref(cfg);
diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c
index 97f3d7f786..702a715902 100644
--- a/src/qemu/qemu_driver.c
+++ b/src/qemu/qemu_driver.c
@@ -102,6 +102,7 @@
#include "virqemu.h"
#include "virdomainsnapshotobjlist.h"
#include "virenum.h"
+#include "virdomaincheckpointobjlist.h"
#define VIR_FROM_THIS VIR_FROM_QEMU
@@ -221,6 +222,40 @@ qemuSnapObjFromSnapshot(virDomainObjPtr vm,
return qemuSnapObjFromName(vm, snapshot->name);
}
+/* Looks up the domain object from checkpoint and unlocks the
+ * driver. The returned domain object is locked and ref'd and the
+ * caller must call virDomainObjEndAPI() on it. */
+static virDomainObjPtr
+qemuDomObjFromCheckpoint(virDomainCheckpointPtr checkpoint)
+{
+ return qemuDomObjFromDomain(checkpoint->domain);
+}
+
+
+/* Looks up checkpoint object from VM and name */
+static virDomainMomentObjPtr
+qemuCheckObjFromName(virDomainObjPtr vm,
+ const char *name)
+{
+ virDomainMomentObjPtr chk = NULL;
+ chk = virDomainCheckpointFindByName(vm->checkpoints, name);
+ if (!chk)
+ virReportError(VIR_ERR_NO_DOMAIN_CHECKPOINT,
+ _("no domain checkpoint with matching name
'%s'"),
+ name);
+
+ return chk;
+}
+
+
+/* Looks up checkpoint object from VM and checkpointPtr */
+static virDomainMomentObjPtr
+qemuCheckObjFromCheckpoint(virDomainObjPtr vm,
+ virDomainCheckpointPtr checkpoint)
+{
+ return qemuCheckObjFromName(vm, checkpoint->name);
+}
+
static int
qemuAutostartDomain(virDomainObjPtr vm,
void *opaque)
@@ -524,6 +559,123 @@ qemuDomainSnapshotLoad(virDomainObjPtr vm,
}
+static int
+qemuDomainCheckpointLoad(virDomainObjPtr vm,
+ void *data)
+{
+ char *baseDir = (char *)data;
+ char *chkDir = NULL;
+ DIR *dir = NULL;
+ struct dirent *entry;
+ char *xmlStr;
+ char *fullpath;
+ virDomainCheckpointDefPtr def = NULL;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainMomentObjPtr current = NULL;
+ bool cur;
+ unsigned int flags = VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE;
+ int ret = -1;
+ virCapsPtr caps = NULL;
+ int direrr;
+
+ virObjectLock(vm);
+ if (virAsprintf(&chkDir, "%s/%s", baseDir, vm->def->name) < 0)
{
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to allocate memory for "
+ "checkpoint directory for domain %s"),
+ vm->def->name);
+ goto cleanup;
+ }
+
+ if (!(caps = virQEMUDriverGetCapabilities(qemu_driver, false)))
+ goto cleanup;
+
+ VIR_INFO("Scanning for checkpoints for domain %s in %s",
vm->def->name,
+ chkDir);
+
+ if (virDirOpenIfExists(&dir, chkDir) <= 0)
+ goto cleanup;
+
+ while ((direrr = virDirRead(dir, &entry, NULL)) > 0) {
+ /* NB: ignoring errors, so one malformed config doesn't
+ kill the whole process */
+ VIR_INFO("Loading checkpoint file '%s'", entry->d_name);
+
+ if (virAsprintf(&fullpath, "%s/%s", chkDir, entry->d_name) <
0) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("Failed to allocate memory for path"));
+ continue;
+ }
+
+ if (virFileReadAll(fullpath, 1024*1024*1, &xmlStr) < 0) {
+ /* Nothing we can do here, skip this one */
+ virReportSystemError(errno,
+ _("Failed to read checkpoint file %s"),
+ fullpath);
+ VIR_FREE(fullpath);
+ continue;
+ }
+
+ def = virDomainCheckpointDefParseString(xmlStr, caps,
+ qemu_driver->xmlopt, &cur,
+ flags);
+ if (!def || virDomainCheckpointAlignDisks(def) < 0) {
+ /* Nothing we can do here, skip this one */
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to parse checkpoint XML from file
'%s'"),
+ fullpath);
+ VIR_FREE(fullpath);
+ VIR_FREE(xmlStr);
+ continue;
+ }
+
+ chk = virDomainCheckpointAssignDef(vm->checkpoints, def);
+ if (chk == NULL) {
+ virObjectUnref(def);
+ } else if (cur) {
+ if (current)
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Too many checkpoints claiming to be current for
domain %s"),
+ vm->def->name);
+ current = chk;
+ }
+
+ VIR_FREE(fullpath);
+ VIR_FREE(xmlStr);
+ }
+ if (direrr < 0)
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to fully read directory %s"),
+ chkDir);
+
+ virDomainCheckpointSetCurrent(vm->checkpoints, current);
+
+ if (virDomainCheckpointUpdateRelations(vm->checkpoints) < 0)
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Checkpoints have inconsistent relations for domain
%s"),
+ vm->def->name);
+
+ /* FIXME: qemu keeps internal track of bitmaps, which form the
+ * basis for checkpoints; it would be nice if we could update our
+ * internal state to reflect that information automatically. But
+ * qemu 3.0 did not have access to this via qemu-img for offline
+ * images (you have to use QMP commands on a running guest), and
+ * it also does not track <parent> relations which we find
+ * important in our metadata.
+ */
+
+ virResetLastError();
+
+ ret = 0;
+ cleanup:
+ VIR_DIR_CLOSE(dir);
+ VIR_FREE(chkDir);
+ virObjectUnref(caps);
+ virObjectUnlock(vm);
+ return ret;
+}
+
+
static int
qemuDomainNetsRestart(virDomainObjPtr vm,
void *data ATTRIBUTE_UNUSED)
@@ -652,6 +804,11 @@ qemuStateInitialize(bool privileged,
cfg->snapshotDir);
goto error;
}
+ if (virFileMakePath(cfg->checkpointDir) < 0) {
+ virReportSystemError(errno, _("Failed to create checkpoint dir %s"),
+ cfg->checkpointDir);
+ goto error;
+ }
if (virFileMakePath(cfg->autoDumpPath) < 0) {
virReportSystemError(errno, _("Failed to create dump dir %s"),
cfg->autoDumpPath);
@@ -759,6 +916,13 @@ qemuStateInitialize(bool privileged,
(int)cfg->group);
goto error;
}
+ if (chown(cfg->checkpointDir, cfg->user, cfg->group) < 0) {
+ virReportSystemError(errno,
+ _("unable to set ownership of '%s' to
%d:%d"),
+ cfg->checkpointDir, (int)cfg->user,
+ (int)cfg->group);
+ goto error;
+ }
if (chown(cfg->autoDumpPath, cfg->user, cfg->group) < 0) {
virReportSystemError(errno,
_("unable to set ownership of '%s' to
%d:%d"),
@@ -892,6 +1056,10 @@ qemuStateInitialize(bool privileged,
qemuDomainSnapshotLoad,
cfg->snapshotDir);
+ virDomainObjListForEach(qemu_driver->domains,
+ qemuDomainCheckpointLoad,
+ cfg->checkpointDir);
+
virDomainObjListForEach(qemu_driver->domains,
qemuDomainManagedSaveLoad,
qemu_driver);
@@ -7710,6 +7878,7 @@ qemuDomainUndefineFlags(virDomainPtr dom,
if (qemuDomainSnapshotDiscardAllMetadata(driver, vm) < 0)
goto endjob;
}
+ /* TODO: Restrict deletion if checkpoints exist? */
name = qemuDomainManagedSavePath(driver, vm);
if (name == NULL)
@@ -15527,6 +15696,12 @@ qemuDomainSnapshotCreateXML(virDomainPtr domain,
if (!(vm = qemuDomObjFromDomain(domain)))
goto cleanup;
+ if (virDomainListCheckpoints(vm->checkpoints, NULL, domain, NULL, 0) > 0) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot create snapshot while checkpoint exists"));
+ goto cleanup;
+ }
+
cfg = virQEMUDriverGetConfig(driver);
if (virDomainSnapshotCreateXMLEnsureACL(domain->conn, vm->def, flags) < 0)
@@ -16728,6 +16903,492 @@ qemuDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
return ret;
}
+
+/* Called prior to job lock */
+static virDomainCheckpointDefPtr
+qemuDomainCheckpointDefParseString(virQEMUDriverPtr driver, virCapsPtr caps,
+ const char *xmlDesc, bool *current,
+ unsigned int flags)
+{
+ virDomainCheckpointDefPtr ret = NULL;
+ unsigned int parse_flags = 0;
+ VIR_AUTOUNREF(virDomainCheckpointDefPtr) def = NULL;
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE)
+ parse_flags |= VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE;
+ if (!(def = virDomainCheckpointDefParseString(xmlDesc, caps, driver->xmlopt,
+ current, parse_flags)))
+ return NULL;
+
+ /* reject checkpoint names containing slashes or starting with dot as
+ * checkpoint definitions are saved in files named by the checkpoint name */
+ if (!(flags & VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA)) {
+ if (strchr(def->parent.name, '/')) {
+ virReportError(VIR_ERR_XML_DETAIL,
+ _("invalid checkpoint name '%s': "
+ "name can't contain '/'"),
+ def->parent.name);
+ return NULL;
+ }
+
+ if (def->parent.name[0] == '.') {
+ virReportError(VIR_ERR_XML_DETAIL,
+ _("invalid checkpoint name '%s': "
+ "name can't start with '.'"),
+ def->parent.name);
+ return NULL;
+ }
+ }
+
+ VIR_STEAL_PTR(ret, def);
+ return ret;
+}
+
+
+/* Called inside job lock */
+static int
+qemuDomainCheckpointPrepare(virQEMUDriverPtr driver, virCapsPtr caps,
+ virDomainObjPtr vm,
+ virDomainCheckpointDefPtr def)
+{
+ int ret = -1;
+ size_t i;
+ char *xml = NULL;
+ qemuDomainObjPrivatePtr priv = vm->privateData;
+
+ /* Easiest way to clone inactive portion of vm->def is via
+ * conversion in and back out of xml. */
+ if (!(xml = qemuDomainDefFormatLive(driver, vm->def, priv->origCPU,
+ true, true)) ||
+ !(def->parent.dom = virDomainDefParseString(xml, caps, driver->xmlopt,
NULL,
+ VIR_DOMAIN_DEF_PARSE_INACTIVE |
+
VIR_DOMAIN_DEF_PARSE_SKIP_VALIDATE)))
+ goto cleanup;
+
+ if (virDomainCheckpointAlignDisks(def) < 0 ||
+ qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0)
+ goto cleanup;
+
+ for (i = 0; i < def->ndisks; i++) {
+ virDomainCheckpointDiskDefPtr disk = &def->disks[i];
+
+ if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP)
+ continue;
+
+ if (vm->def->disks[i]->src->format > 0 &&
+ vm->def->disks[i]->src->format != VIR_STORAGE_FILE_QCOW2) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("checkpoint for disk %s unsupported "
+ "for storage type %s"),
+ disk->name,
+ virStorageFileFormatTypeToString(
+ vm->def->disks[i]->src->format));
+ goto cleanup;
+ }
+ }
+
+ ret = 0;
+
+ cleanup:
+ VIR_FREE(xml);
+ return ret;
+}
+
+
+static virDomainCheckpointPtr
+qemuDomainCheckpointCreateXML(virDomainPtr domain,
+ const char *xmlDesc,
+ unsigned int flags)
+{
+ virQEMUDriverPtr driver = domain->conn->privateData;
+ virDomainObjPtr vm = NULL;
+ char *xml = NULL;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+ virDomainMomentObjPtr current = NULL;
+ bool update_current = true;
+ bool *set_current = NULL;
+ bool redefine = flags & VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE;
+ virDomainMomentObjPtr other = NULL;
+ virQEMUDriverConfigPtr cfg = NULL;
+ virCapsPtr caps = NULL;
+ VIR_AUTOUNREF(virDomainCheckpointDefPtr) def = NULL;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE |
+ VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA, NULL);
+ /* TODO: VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE */
+ /* TODO: Defer NO_METADATA */
+
+ if (redefine)
+ set_current = &update_current;
+ if (redefine || (flags & VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA))
+ update_current = false;
+
+ if (!(vm = qemuDomObjFromDomain(domain)))
+ goto cleanup;
+
+ if (virDomainSnapshotObjListNum(vm->snapshots, NULL, 0) > 0) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot create checkpoint while snapshot exists"));
+ goto cleanup;
+ }
+
+ cfg = virQEMUDriverGetConfig(driver);
+
+ if (virDomainCheckpointCreateXMLEnsureACL(domain->conn, vm->def, flags) <
0)
+ goto cleanup;
+
+ if (!(caps = virQEMUDriverGetCapabilities(driver, false)))
+ goto cleanup;
+
+ if (qemuProcessAutoDestroyActive(driver, vm)) {
+ virReportError(VIR_ERR_OPERATION_INVALID,
+ "%s", _("domain is marked for auto
destroy"));
+ goto cleanup;
+ }
+
+ if (!virDomainObjIsActive(vm)) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot create checkpoint for inactive domain"));
+ goto cleanup;
+ }
+
+ if (!(def = qemuDomainCheckpointDefParseString(driver, caps, xmlDesc,
+ set_current, flags)))
+ goto cleanup;
+
+ /* We are going to modify the domain below. */
+ if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0)
+ goto cleanup;
+
+ if (redefine) {
+ if (virDomainCheckpointRedefinePrep(domain, vm, &def, &chk,
+ driver->xmlopt,
+ &update_current) < 0)
+ goto endjob;
+ } else if (qemuDomainCheckpointPrepare(driver, caps, vm, def) < 0) {
+ goto endjob;
+ }
+
+ if (!chk) {
+ if (!(chk = virDomainCheckpointAssignDef(vm->checkpoints, def)))
+ goto endjob;
+
+ def = NULL;
+ }
+
+ current = virDomainCheckpointGetCurrent(vm->checkpoints);
+ if (current) {
+ if (!redefine &&
+ VIR_STRDUP(chk->def->parent_name, current->def->name) < 0)
+ goto endjob;
+ if (update_current) {
+ virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
+ if (qemuDomainCheckpointWriteMetadata(vm, current,
+ driver->caps, driver->xmlopt,
+ cfg->checkpointDir) < 0)
+ goto endjob;
+ }
+ }
+
+ /* actually do the checkpoint */
+ if (redefine) {
+ /* XXX Should we validate that the redefined checkpoint even
+ * makes sense, such as checking that qemu-img recognizes the
+ * checkpoint bitmap name in at least one of the domain's disks? */
+ } else {
+ /* TODO: issue QMP transaction command */
+ }
+
+ /* If we fail after this point, there's not a whole lot we can do;
+ * we've successfully created the checkpoint, so we have to go
+ * forward the best we can.
+ */
+ checkpoint = virGetDomainCheckpoint(domain, chk->def->name);
+
+ endjob:
+ if (checkpoint && !(flags & VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA)) {
+ if (update_current)
+ virDomainCheckpointSetCurrent(vm->checkpoints, chk);
+ if (qemuDomainCheckpointWriteMetadata(vm, chk, driver->caps,
+ driver->xmlopt,
+ cfg->checkpointDir) < 0) {
+ /* if writing of metadata fails, error out rather than trying
+ * to silently carry on without completing the checkpoint */
+ virObjectUnref(checkpoint);
+ checkpoint = NULL;
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("unable to save metadata for checkpoint %s"),
+ chk->def->name);
+ virDomainCheckpointObjListRemove(vm->checkpoints, chk);
+ } else {
+ other = virDomainCheckpointFindByName(vm->checkpoints,
+ chk->def->parent_name);
+ virDomainMomentSetParent(chk, other);
+ }
+ } else if (chk) {
+ virDomainCheckpointObjListRemove(vm->checkpoints, chk);
+ }
+
+ qemuDomainObjEndJob(driver, vm);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ VIR_FREE(xml);
+ virObjectUnref(caps);
+ virObjectUnref(cfg);
+ return checkpoint;
+}
+
+
+static int
+qemuDomainListAllCheckpoints(virDomainPtr domain,
+ virDomainCheckpointPtr **chks,
+ unsigned int flags)
+{
+ virDomainObjPtr vm = NULL;
+ int n = -1;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_LIST_ROOTS |
+ VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL |
+ VIR_DOMAIN_CHECKPOINT_FILTERS_ALL, -1);
+
+ if (!(vm = qemuDomObjFromDomain(domain)))
+ return -1;
+
+ if (virDomainListAllCheckpointsEnsureACL(domain->conn, vm->def) < 0)
+ goto cleanup;
+
+ n = virDomainListCheckpoints(vm->checkpoints, NULL, domain, chks, flags);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return n;
+}
+
+
+static int
+qemuDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
+ virDomainCheckpointPtr **chks,
+ unsigned int flags)
+{
+ virDomainObjPtr vm = NULL;
+ virDomainMomentObjPtr chk = NULL;
+ int n = -1;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS |
+ VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL |
+ VIR_DOMAIN_CHECKPOINT_FILTERS_ALL, -1);
+
+ if (!(vm = qemuDomObjFromCheckpoint(checkpoint)))
+ return -1;
+
+ if (virDomainCheckpointListAllChildrenEnsureACL(checkpoint->domain->conn,
+ vm->def) < 0)
+ goto cleanup;
+
+ if (!(chk = qemuCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+
+ n = virDomainListCheckpoints(vm->checkpoints, chk, checkpoint->domain,
+ chks, flags);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return n;
+}
+
+
+static virDomainCheckpointPtr
+qemuDomainCheckpointLookupByName(virDomainPtr domain,
+ const char *name,
+ unsigned int flags)
+{
+ virDomainObjPtr vm;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainCheckpointPtr checkpoint = NULL;
+
+ virCheckFlags(0, NULL);
+
+ if (!(vm = qemuDomObjFromDomain(domain)))
+ return NULL;
+
+ if (virDomainCheckpointLookupByNameEnsureACL(domain->conn, vm->def) < 0)
+ goto cleanup;
+
+ if (!(chk = qemuCheckObjFromName(vm, name)))
+ goto cleanup;
+
+ checkpoint = virGetDomainCheckpoint(domain, chk->def->name);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return checkpoint;
+}
+
+
+static virDomainCheckpointPtr
+qemuDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virDomainObjPtr vm;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainCheckpointPtr parent = NULL;
+
+ virCheckFlags(0, NULL);
+
+ if (!(vm = qemuDomObjFromCheckpoint(checkpoint)))
+ return NULL;
+
+ if (virDomainCheckpointGetParentEnsureACL(checkpoint->domain->conn, vm->def)
< 0)
+ goto cleanup;
+
+ if (!(chk = qemuCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+
+ if (!chk->def->parent_name) {
+ virReportError(VIR_ERR_NO_DOMAIN_CHECKPOINT,
+ _("checkpoint '%s' does not have a parent"),
+ chk->def->name);
+ goto cleanup;
+ }
+
+ parent = virGetDomainCheckpoint(checkpoint->domain, chk->def->parent_name);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return parent;
+}
+
+
+static char *
+qemuDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virQEMUDriverPtr driver = checkpoint->domain->conn->privateData;
+ virDomainObjPtr vm = NULL;
+ char *xml = NULL;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainCheckpointDefPtr chkdef;
+ unsigned int format_flags;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_XML_SECURE |
+ VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN, NULL);
+
+ if (!(vm = qemuDomObjFromCheckpoint(checkpoint)))
+ return NULL;
+
+ if (virDomainCheckpointGetXMLDescEnsureACL(checkpoint->domain->conn,
vm->def, flags) < 0)
+ goto cleanup;
+
+ if (!(chk = qemuCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+ chkdef = virDomainCheckpointObjGetDef(chk);
+
+ format_flags = virDomainCheckpointFormatConvertXMLFlags(flags);
+ if (chk == virDomainCheckpointGetCurrent(vm->checkpoints))
+ format_flags |= VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT;
+ xml = virDomainCheckpointDefFormat(chkdef, driver->caps, driver->xmlopt,
+ format_flags);
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_XML_SIZE)
+ qemuDomainObjEndJob(driver, vm);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return xml;
+}
+
+
+static int
+qemuDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virQEMUDriverPtr driver = checkpoint->domain->conn->privateData;
+ virDomainObjPtr vm = NULL;
+ int ret = -1;
+ virDomainMomentObjPtr chk = NULL;
+ virQEMUMomentRemove rem;
+ virQEMUMomentReparent rep;
+ bool metadata_only = !!(flags & VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY);
+ virQEMUDriverConfigPtr cfg = NULL;
+
+ virCheckFlags(VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN |
+ VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY |
+ VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY, -1);
+
+ if (!(vm = qemuDomObjFromCheckpoint(checkpoint)))
+ return -1;
+
+ cfg = virQEMUDriverGetConfig(driver);
+
+ if (virDomainCheckpointDeleteEnsureACL(checkpoint->domain->conn, vm->def)
< 0)
+ goto cleanup;
+
+ if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0)
+ goto cleanup;
+
+ if (!(chk = qemuCheckObjFromCheckpoint(vm, checkpoint)))
+ goto endjob;
+
+ if (flags & (VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN |
+ VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY)) {
+ rem.driver = driver;
+ rem.vm = vm;
+ rem.metadata_only = metadata_only;
+ rem.err = 0;
+ rem.current = virDomainCheckpointGetCurrent(vm->checkpoints);
+ rem.found = false;
+ rem.momentDiscard = qemuDomainCheckpointDiscard;
+ virDomainMomentForEachDescendant(chk, qemuDomainMomentDiscardAll,
+ &rem);
+ if (rem.err < 0)
+ goto endjob;
+ if (rem.found) {
+ virDomainCheckpointSetCurrent(vm->checkpoints, chk);
+ if (flags & VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY) {
+ if (qemuDomainCheckpointWriteMetadata(vm, chk, driver->caps,
+ driver->xmlopt,
+ cfg->checkpointDir) < 0) {
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("failed to set checkpoint '%s' as
current"),
+ chk->def->name);
+ virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
+ goto endjob;
+ }
+ }
+ }
+ } else if (chk->nchildren) {
+ rep.dir = cfg->checkpointDir;
+ rep.parent = chk->parent;
+ rep.vm = vm;
+ rep.err = 0;
+ rep.caps = driver->caps;
+ rep.xmlopt = driver->xmlopt;
+ rep.writeMetadata = qemuDomainCheckpointWriteMetadata;
+ virDomainMomentForEachChild(chk, qemuDomainMomentReparentChildren,
+ &rep);
+ if (rep.err < 0)
+ goto endjob;
+ virDomainMomentMoveChildren(chk, chk->parent);
+ }
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY) {
+ virDomainMomentDropChildren(chk);
+ ret = 0;
+ } else {
+ ret = qemuDomainCheckpointDiscard(driver, vm, chk, true, metadata_only);
+ }
+
+ endjob:
+ qemuDomainObjEndJob(driver, vm);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ virObjectUnref(cfg);
+ return ret;
+}
+
static int qemuDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd,
char **result, unsigned int flags)
{
@@ -21595,6 +22256,12 @@ static int qemuDomainRename(virDomainPtr dom,
goto endjob;
}
+ if (virDomainListCheckpoints(vm->checkpoints, NULL, dom, NULL, flags) > 0) {
+ virReportError(VIR_ERR_OPERATION_INVALID,
+ "%s", _("cannot rename domain with
checkpoints"));
+ goto endjob;
+ }
+
if (virDomainObjListRename(driver->domains, vm, new_name, flags,
qemuDomainRenameCallback, driver) < 0)
goto endjob;
@@ -22415,6 +23082,14 @@ static virHypervisorDriver qemuHypervisorDriver = {
.connectBaselineHypervisorCPU = qemuConnectBaselineHypervisorCPU, /* 4.4.0 */
.nodeGetSEVInfo = qemuNodeGetSEVInfo, /* 4.5.0 */
.domainGetLaunchSecurityInfo = qemuDomainGetLaunchSecurityInfo, /* 4.5.0 */
+ .domainCheckpointCreateXML = qemuDomainCheckpointCreateXML, /* 5.6.0 */
+ .domainCheckpointGetXMLDesc = qemuDomainCheckpointGetXMLDesc, /* 5.6.0 */
+
+ .domainListAllCheckpoints = qemuDomainListAllCheckpoints, /* 5.6.0 */
+ .domainCheckpointListAllChildren = qemuDomainCheckpointListAllChildren, /* 5.6.0 */
+ .domainCheckpointLookupByName = qemuDomainCheckpointLookupByName, /* 5.6.0 */
+ .domainCheckpointGetParent = qemuDomainCheckpointGetParent, /* 5.6.0 */
+ .domainCheckpointDelete = qemuDomainCheckpointDelete, /* 5.6.0 */
};
--
2.20.1
11:33 a.m.
New subject: [libvirt] [PATCH v9 11/13] backup: qemu: Implement metadata tracking for checkpoint APIs
On Sat, Jul 06, 2019 at 22:56:11 -0500, Eric Blake wrote:
A lot of this work heavily copies from the existing snapshot
APIs. The interaction with qemu during create/delete still
needs to be implemented, but this takes care of all the libvirt
metadata (saving and restoring XML, and tracking the relations
between multiple checkpoints).
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/qemu/qemu_block.h | 3 +
src/qemu/qemu_conf.h | 2 +
src/qemu/qemu_domain.h | 15 +
src/qemu/qemu_block.c | 12 +
src/qemu/qemu_conf.c | 5 +
src/qemu/qemu_domain.c | 133 ++++++++
src/qemu/qemu_driver.c | 675 +++++++++++++++++++++++++++++++++++++++++
7 files changed, 845 insertions(+)
[...]
diff --git a/src/qemu/qemu_block.c b/src/qemu/qemu_block.c
index 0a6522577d..5f5e330479 100644
--- a/src/qemu/qemu_block.c
+++ b/src/qemu/qemu_block.c
@@ -1821,3 +1821,15 @@ qemuBlockStorageGetCopyOnReadProps(virDomainDiskDefPtr disk)
return ret;
}
+
+const char *
+qemuBlockNodeLookup(virDomainObjPtr vm, const char *disk)
This looks like it belongs more into qemu_domain.c since it primarily
looks up the disk and not the node name.
+{
+ size_t i;
+
+ for (i = 0; i < vm->def->ndisks; i++) {
+ if (STREQ(vm->def->disks[i]->dst, disk))
+ return vm->def->disks[i]->src->nodeformat;
+ }
+ return NULL;
+}
[...]
diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c
index 97f3d7f786..702a715902 100644
--- a/src/qemu/qemu_driver.c
+++ b/src/qemu/qemu_driver.c
[...]
@@ -221,6 +222,40 @@ qemuSnapObjFromSnapshot(virDomainObjPtr vm,
return qemuSnapObjFromName(vm, snapshot->name);
}
+/* Looks up the domain object from checkpoint and unlocks the
+ * driver. The returned domain object is locked and ref'd and the
+ * caller must call virDomainObjEndAPI() on it. */
+static virDomainObjPtr
+qemuDomObjFromCheckpoint(virDomainCheckpointPtr checkpoint)
+{
+ return qemuDomObjFromDomain(checkpoint->domain);
+}
+
+
+/* Looks up checkpoint object from VM and name */
+static virDomainMomentObjPtr
+qemuCheckObjFromName(virDomainObjPtr vm,
+ const char *name)
+{
+ virDomainMomentObjPtr chk = NULL;
+ chk = virDomainCheckpointFindByName(vm->checkpoints, name);
+ if (!chk)
+ virReportError(VIR_ERR_NO_DOMAIN_CHECKPOINT,
+ _("no domain checkpoint with matching name
'%s'"),
+ name);
+
+ return chk;
+}
+
+
+/* Looks up checkpoint object from VM and checkpointPtr */
+static virDomainMomentObjPtr
+qemuCheckObjFromCheckpoint(virDomainObjPtr vm,
+ virDomainCheckpointPtr checkpoint)
Both of the function above contain 'Check' which looks more like a verb
than a noun. Could you please expand it?
+{
+ return qemuCheckObjFromName(vm, checkpoint->name);
+}
+
static int
qemuAutostartDomain(virDomainObjPtr vm,
void *opaque)
@@ -524,6 +559,123 @@ qemuDomainSnapshotLoad(virDomainObjPtr vm,
}
+static int
+qemuDomainCheckpointLoad(virDomainObjPtr vm,
+ void *data)
+{
+ char *baseDir = (char *)data;
+ char *chkDir = NULL;
+ DIR *dir = NULL;
+ struct dirent *entry;
+ char *xmlStr;
+ char *fullpath;
+ virDomainCheckpointDefPtr def = NULL;
+ virDomainMomentObjPtr chk = NULL;
+ virDomainMomentObjPtr current = NULL;
+ bool cur;
+ unsigned int flags = VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE;
+ int ret = -1;
+ virCapsPtr caps = NULL;
+ int direrr;
+
+ virObjectLock(vm);
+ if (virAsprintf(&chkDir, "%s/%s", baseDir, vm->def->name) <
0) {
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to allocate memory for "
+ "checkpoint directory for domain %s"),
+ vm->def->name);
+ goto cleanup;
+ }
+
+ if (!(caps = virQEMUDriverGetCapabilities(qemu_driver, false)))
+ goto cleanup;
+
+ VIR_INFO("Scanning for checkpoints for domain %s in %s",
vm->def->name,
+ chkDir);
+
+ if (virDirOpenIfExists(&dir, chkDir) <= 0)
+ goto cleanup;
+
+ while ((direrr = virDirRead(dir, &entry, NULL)) > 0) {
+ /* NB: ignoring errors, so one malformed config doesn't
+ kill the whole process */
+ VIR_INFO("Loading checkpoint file '%s'", entry->d_name);
+
+ if (virAsprintf(&fullpath, "%s/%s", chkDir, entry->d_name) <
0) {
+ virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+ _("Failed to allocate memory for path"));
+ continue;
+ }
+
+ if (virFileReadAll(fullpath, 1024*1024*1, &xmlStr) < 0) {
+ /* Nothing we can do here, skip this one */
+ virReportSystemError(errno,
+ _("Failed to read checkpoint file %s"),
+ fullpath);
+ VIR_FREE(fullpath);
+ continue;
+ }
+
+ def = virDomainCheckpointDefParseString(xmlStr, caps,
+ qemu_driver->xmlopt, &cur,
+ flags);
+ if (!def || virDomainCheckpointAlignDisks(def) < 0) {
+ /* Nothing we can do here, skip this one */
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to parse checkpoint XML from file
'%s'"),
+ fullpath);
+ VIR_FREE(fullpath);
+ VIR_FREE(xmlStr);
leaks 'def'
+ continue;
+ }
+
+ chk = virDomainCheckpointAssignDef(vm->checkpoints, def);
+ if (chk == NULL) {
+ virObjectUnref(def);
+ } else if (cur) {
+ if (current)
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Too many checkpoints claiming to be current for
domain %s"),
+ vm->def->name);
+ current = chk;
+ }
+
+ VIR_FREE(fullpath);
+ VIR_FREE(xmlStr);
+ }
+ if (direrr < 0)
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to fully read directory %s"),
+ chkDir);
+
+ virDomainCheckpointSetCurrent(vm->checkpoints, current);
+
+ if (virDomainCheckpointUpdateRelations(vm->checkpoints) < 0)
+ virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Checkpoints have inconsistent relations for domain
%s"),
+ vm->def->name);
+
+ /* FIXME: qemu keeps internal track of bitmaps, which form the
+ * basis for checkpoints; it would be nice if we could update our
+ * internal state to reflect that information automatically. But
+ * qemu 3.0 did not have access to this via qemu-img for offline
+ * images (you have to use QMP commands on a running guest), and
+ * it also does not track <parent> relations which we find
+ * important in our metadata.
+ */
That would be pointless to do if qemu is not running because users can
modify the files behind our back anyways and since we don't have inotify
on all the possible files (which would be impossible) we'd have to redo
all of this anyways when starting the vm. Thus probably drop this
comment.
+
+ virResetLastError();
+
+ ret = 0;
+ cleanup:
+ VIR_DIR_CLOSE(dir);
+ VIR_FREE(chkDir);
+ virObjectUnref(caps);
+ virObjectUnlock(vm);
+ return ret;
+}
+
+
static int
qemuDomainNetsRestart(virDomainObjPtr vm,
void *data ATTRIBUTE_UNUSED)
[...]
@@ -7710,6 +7878,7 @@ qemuDomainUndefineFlags(virDomainPtr dom,
if (qemuDomainSnapshotDiscardAllMetadata(driver, vm) < 0)
goto endjob;
}
+ /* TODO: Restrict deletion if checkpoints exist? */
This should be fairly easy since you've done a similar thing in
qemuDomainRename.
name = qemuDomainManagedSavePath(driver, vm);
if (name == NULL)
[...]
@@ -16728,6 +16903,492 @@
qemuDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
return ret;
}
+
+/* Called prior to job lock */
+static virDomainCheckpointDefPtr
+qemuDomainCheckpointDefParseString(virQEMUDriverPtr driver, virCapsPtr caps,
+ const char *xmlDesc, bool *current,
+ unsigned int flags)
+{
+ virDomainCheckpointDefPtr ret = NULL;
+ unsigned int parse_flags = 0;
+ VIR_AUTOUNREF(virDomainCheckpointDefPtr) def = NULL;
+
+ if (flags & VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE)
+ parse_flags |= VIR_DOMAIN_CHECKPOINT_PARSE_REDEFINE;
+ if (!(def = virDomainCheckpointDefParseString(xmlDesc, caps, driver->xmlopt,
+ current, parse_flags)))
+ return NULL;
+
+ /* reject checkpoint names containing slashes or starting with dot as
+ * checkpoint definitions are saved in files named by the checkpoint name */
+ if (!(flags & VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA)) {
+ if (strchr(def->parent.name, '/')) {
+ virReportError(VIR_ERR_XML_DETAIL,
+ _("invalid checkpoint name '%s': "
+ "name can't contain '/'"),
+ def->parent.name);
That's the job for the validator.
+ return NULL;
+ }
+
+ if (def->parent.name[0] == '.') {
+ virReportError(VIR_ERR_XML_DETAIL,
+ _("invalid checkpoint name '%s': "
+ "name can't start with '.'"),
+ def->parent.name);
+ return NULL;
+ }
+ }
+
+ VIR_STEAL_PTR(ret, def);
+ return ret;
+}
[...]
+static int
+qemuDomainCheckpointPrepare(virQEMUDriverPtr driver, virCapsPtr caps,
+ virDomainObjPtr vm,
+ virDomainCheckpointDefPtr def)
+{
+ int ret = -1;
+ size_t i;
+ char *xml = NULL;
+ qemuDomainObjPrivatePtr priv = vm->privateData;
+
+ /* Easiest way to clone inactive portion of vm->def is via
+ * conversion in and back out of xml. */
+ if (!(xml = qemuDomainDefFormatLive(driver, vm->def, priv->origCPU,
+ true, true)) ||
+ !(def->parent.dom = virDomainDefParseString(xml, caps, driver->xmlopt,
NULL,
+ VIR_DOMAIN_DEF_PARSE_INACTIVE |
+
VIR_DOMAIN_DEF_PARSE_SKIP_VALIDATE)))
+ goto cleanup;
+
+ if (virDomainCheckpointAlignDisks(def) < 0 ||
+ qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0)
As I've pointed out multiple times already, calling qemuBlockNodeNamesDetect
should not be necessary with -drive and MUST not be done with
QEMU_CAPS_BLOCKDEV. This will mess up the libvirt metadata about the
backing chain!!!
+ goto cleanup;
+
+ for (i = 0; i < def->ndisks; i++) {
+ virDomainCheckpointDiskDefPtr disk = &def->disks[i];
+
+ if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP)
+ continue;
+
+ if (vm->def->disks[i]->src->format > 0 &&
+ vm->def->disks[i]->src->format != VIR_STORAGE_FILE_QCOW2) {
I'd ignore the possibility of format AUTO in this case. It should not
even be possible.
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
+ _("checkpoint for disk %s unsupported "
+ "for storage type %s"),
+ disk->name,
+ virStorageFileFormatTypeToString(
+ vm->def->disks[i]->src->format));
The rest looks good to me, but I want to see a fixed version of this
which does not call qemuBlockNodeNamesDetect needlessly before giving my
final ACK.
12:22 a.m.
New subject: [libvirt] [PATCH v9 11/13] backup: qemu: Implement metadata tracking for checkpoint APIs
On 7/8/19 11:33 AM, Peter Krempa wrote:
On Sat, Jul 06, 2019 at 22:56:11 -0500, Eric Blake wrote:
> A lot of this work heavily copies from the existing snapshot
> APIs. The interaction with qemu during create/delete still
> needs to be implemented, but this takes care of all the libvirt
> metadata (saving and restoring XML, and tracking the relations
> between multiple checkpoints).
>
> Signed-off-by: Eric Blake <eblake(a)redhat.com>
> ---
> +/* Looks up checkpoint object from VM and checkpointPtr */
> +static virDomainMomentObjPtr
> +qemuCheckObjFromCheckpoint(virDomainObjPtr vm,
> + virDomainCheckpointPtr checkpoint)
Both of the function above contain 'Check' which looks more like a verb
than a noun. Could you please expand it?
Consider it done.
> + if (!def || virDomainCheckpointAlignDisks(def) < 0)
{
> + /* Nothing we can do here, skip this one */
> + virReportError(VIR_ERR_INTERNAL_ERROR,
> + _("Failed to parse checkpoint XML from file
'%s'"),
> + fullpath);
> + VIR_FREE(fullpath);
> + VIR_FREE(xmlStr);
leaks 'def'
> + continue;
> + }
Indeed; fixed for v10.
> +
> + /* reject checkpoint names containing slashes or starting with dot as
> + * checkpoint definitions are saved in files named by the checkpoint name */
> + if (!(flags & VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA)) {
> + if (strchr(def->parent.name, '/')) {
> + virReportError(VIR_ERR_XML_DETAIL,
> + _("invalid checkpoint name '%s': "
> + "name can't contain '/'"),
> + def->parent.name);
That's the job for the validator.
And thanks to forced RNG validation, this whole function goes away.
> + /* Easiest way to clone inactive portion of vm->def is
via
> + * conversion in and back out of xml. */
> + if (!(xml = qemuDomainDefFormatLive(driver, vm->def, priv->origCPU,
> + true, true)) ||
> + !(def->parent.dom = virDomainDefParseString(xml, caps, driver->xmlopt,
NULL,
> + VIR_DOMAIN_DEF_PARSE_INACTIVE |
> +
VIR_DOMAIN_DEF_PARSE_SKIP_VALIDATE)))
> + goto cleanup;
> +
> + if (virDomainCheckpointAlignDisks(def) < 0 ||
> + qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0)
As I've pointed out multiple times already, calling qemuBlockNodeNamesDetect
should not be necessary with -drive and MUST not be done with
QEMU_CAPS_BLOCKDEV. This will mess up the libvirt metadata about the
backing chain!!!
Well, it _was_ necessary with -drive if you had just done 'virsh start
$dom', but not necessary for libvirtd restarted with an already running
domain. I have a patch for that in v10. I suspect we may also have
problems with hot-plug or media changes (floppies and cdroms), which may
need to update node names when not CAPS_BLOCKDEV, but I didn't spend
time chasing those down so far.
> + goto cleanup;
> +
> + for (i = 0; i < def->ndisks; i++) {
> + virDomainCheckpointDiskDefPtr disk = &def->disks[i];
> +
> + if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP)
> + continue;
> +
> + if (vm->def->disks[i]->src->format > 0 &&
> + vm->def->disks[i]->src->format != VIR_STORAGE_FILE_QCOW2) {
I'd ignore the possibility of format AUTO in this case. It should not
even be possible.
Okay.
> + virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
> + _("checkpoint for disk %s unsupported "
> + "for storage type %s"),
> + disk->name,
> + virStorageFileFormatTypeToString(
> + vm->def->disks[i]->src->format));
The rest looks good to me, but I want to see a fixed version of this
which does not call qemuBlockNodeNamesDetect needlessly before giving my
final ACK.
v10 should be landing on the list shortly.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org
10:56 p.m.
New subject: [libvirt] [PATCH v9 12/13] backup: Wire up qemu checkpoint commands over QMP
Time to actually issue the QMP transactions that create and
delete persistent checkpoints. For create, we only need one
transaction: inside, we visit all disks affected by the
checkpoint, and create a new enabled bitmap, as well as
disabling the bitmap of the parent checkpoint (if any). For
deletion, we need multiple calls: if the checkpoint to be
deleted is active, we must enable the parent; then we must
merge the existing checkpoint into the parent, and finally
we can delete the checkpoint.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/qemu/qemu_domain.c | 105 ++++++++++++++++++++++++++++++-----------
src/qemu/qemu_driver.c | 92 ++++++++++++++++++++++++++++++++++--
2 files changed, 165 insertions(+), 32 deletions(-)
diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c
index 03a143a228..2fca7bd0b8 100644
--- a/src/qemu/qemu_domain.c
+++ b/src/qemu/qemu_domain.c
@@ -8960,45 +8960,93 @@ qemuDomainCheckpointDiscard(virQEMUDriverPtr driver,
char *chkFile = NULL;
int ret = -1;
virDomainMomentObjPtr parentchk = NULL;
+ virDomainCheckpointDefPtr parentdef = NULL;
virQEMUDriverConfigPtr cfg = virQEMUDriverGetConfig(driver);
+ size_t i, j;
+ virJSONValuePtr arr = NULL;
- if (!metadata_only) {
- if (!virDomainObjIsActive(vm)) {
- virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
- _("cannot remove checkpoint from inactive
domain"));
- goto cleanup;
- } else {
- /* TODO: Implement QMP sequence to merge bitmaps */
- // qemuDomainObjPrivatePtr priv;
- // priv = vm->privateData;
- // qemuDomainObjEnterMonitor(driver, vm);
- // /* we continue on even in the face of error */
- // qemuMonitorDeleteCheckpoint(priv->mon, chk->def->name);
- // ignore_value(qemuDomainObjExitMonitor(driver, vm));
- }
+ if (!metadata_only && !virDomainObjIsActive(vm)) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot remove checkpoint from inactive domain"));
+ goto cleanup;
}
if (virAsprintf(&chkFile, "%s/%s/%s.xml", cfg->checkpointDir,
vm->def->name, chk->def->name) < 0)
goto cleanup;
+ if (chk->def->parent_name) {
+ parentchk = virDomainCheckpointFindByName(vm->checkpoints,
+ chk->def->parent_name);
+ if (!parentchk) {
+ VIR_WARN("missing parent checkpoint matching name '%s'",
+ chk->def->parent_name);
+ }
+ parentdef = virDomainCheckpointObjGetDef(parentchk);
+ }
+
+ if (!metadata_only) {
+ qemuDomainObjPrivatePtr priv = vm->privateData;
+ bool success = true;
+ virDomainCheckpointDefPtr chkdef = virDomainCheckpointObjGetDef(chk);
+
+ if (qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0)
+ goto cleanup;
+ qemuDomainObjEnterMonitor(driver, vm);
+ for (i = 0; i < chkdef->ndisks; i++) {
+ virDomainCheckpointDiskDef *disk = &chkdef->disks[i];
+ const char *node;
+
+ if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP)
+ continue;
+
+ node = qemuBlockNodeLookup(vm, disk->name);
+ if (parentchk) {
+ arr = virJSONValueNewArray();
+ if (!arr ||
+ virJSONValueArrayAppendString(arr, disk->bitmap) < 0) {
+ success = false;
+ break;
+ }
+
+ for (j = 0; j < parentdef->ndisks; j++) {
+ virDomainCheckpointDiskDef *disk2;
+
+ disk2 = &parentdef->disks[j];
+ if (STRNEQ(disk->name, disk2->name))
+ continue;
+ if (chk == virDomainCheckpointGetCurrent(vm->checkpoints)
&&
+ qemuMonitorEnableBitmap(priv->mon, node,
+ disk2->bitmap) < 0) {
+ success = false;
+ break;
+ }
+ if (qemuMonitorMergeBitmaps(priv->mon, node,
+ disk2->bitmap, &arr) < 0) {
+ success = false;
+ break;
+ }
+ }
+ }
+ if (qemuMonitorDeleteBitmap(priv->mon, node, disk->bitmap) < 0) {
+ success = false;
+ break;
+ }
+ }
+ if (qemuDomainObjExitMonitor(driver, vm) < 0 || !success)
+ goto cleanup;
+ }
+
if (chk == virDomainCheckpointGetCurrent(vm->checkpoints)) {
virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
- if (update_parent && chk->def->parent_name) {
- parentchk = virDomainCheckpointFindByName(vm->checkpoints,
- chk->def->parent_name);
- if (!parentchk) {
- VIR_WARN("missing parent checkpoint matching name
'%s'",
+ if (update_parent && parentchk) {
+ virDomainCheckpointSetCurrent(vm->checkpoints, parentchk);
+ if (qemuDomainCheckpointWriteMetadata(vm, parentchk, driver->caps,
+ driver->xmlopt,
+ cfg->checkpointDir) < 0) {
+ VIR_WARN("failed to set parent checkpoint '%s' as
current",
chk->def->parent_name);
- } else {
- virDomainCheckpointSetCurrent(vm->checkpoints, parentchk);
- if (qemuDomainCheckpointWriteMetadata(vm, parentchk, driver->caps,
- driver->xmlopt,
- cfg->checkpointDir) < 0) {
- VIR_WARN("failed to set parent checkpoint '%s' as
current",
- chk->def->parent_name);
- virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
- }
+ virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
}
}
}
@@ -9014,6 +9062,7 @@ qemuDomainCheckpointDiscard(virQEMUDriverPtr driver,
cleanup:
VIR_FREE(chkFile);
virObjectUnref(cfg);
+ virJSONValueFree(arr);
return ret;
}
diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c
index 702a715902..b37307abc7 100644
--- a/src/qemu/qemu_driver.c
+++ b/src/qemu/qemu_driver.c
@@ -47,6 +47,7 @@
#include "qemu_hostdev.h"
#include "qemu_hotplug.h"
#include "qemu_monitor.h"
+#include "qemu_monitor_json.h"
#include "qemu_process.h"
#include "qemu_migration.h"
#include "qemu_migration_params.h"
@@ -16994,6 +16995,53 @@ qemuDomainCheckpointPrepare(virQEMUDriverPtr driver, virCapsPtr
caps,
return ret;
}
+static int
+qemuDomainCheckpointAddActions(virDomainObjPtr vm,
+ virJSONValuePtr actions,
+ virDomainMomentObjPtr old_current,
+ virDomainCheckpointDefPtr def)
+{
+ size_t i, j;
+ int ret = -1;
+ virDomainCheckpointDefPtr olddef;
+
+ olddef = virDomainCheckpointObjGetDef(old_current);
+ for (i = 0; i < def->ndisks; i++) {
+ virDomainCheckpointDiskDef *disk = &def->disks[i];
+ const char *node;
+
+ if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP)
+ continue;
+ node = qemuBlockNodeLookup(vm, disk->name);
+ if (qemuMonitorJSONTransactionAdd(actions,
+ "block-dirty-bitmap-add",
+ "s:node", node,
+ "s:name", disk->bitmap,
+ "b:persistent", true,
+ NULL) < 0)
+ goto cleanup;
+ if (old_current) {
+ for (j = 0; j < olddef->ndisks; j++) {
+ virDomainCheckpointDiskDef *disk2;
+
+ disk2 = &olddef->disks[j];
+ if (STRNEQ(disk->name, disk2->name))
+ continue;
+ if (disk2->type == VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP &&
+ qemuMonitorJSONTransactionAdd(actions,
+
"block-dirty-bitmap-disable",
+ "s:node", node,
+ "s:name", disk2->bitmap,
+ NULL) < 0)
+ goto cleanup;
+ }
+ }
+ }
+ ret = 0;
+
+ cleanup:
+ return ret;
+}
static virDomainCheckpointPtr
qemuDomainCheckpointCreateXML(virDomainPtr domain,
@@ -17012,6 +17060,9 @@ qemuDomainCheckpointCreateXML(virDomainPtr domain,
virDomainMomentObjPtr other = NULL;
virQEMUDriverConfigPtr cfg = NULL;
virCapsPtr caps = NULL;
+ qemuDomainObjPrivatePtr priv;
+ virJSONValuePtr actions = NULL;
+ int ret;
VIR_AUTOUNREF(virDomainCheckpointDefPtr) def = NULL;
virCheckFlags(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE |
@@ -17033,11 +17084,18 @@ qemuDomainCheckpointCreateXML(virDomainPtr domain,
goto cleanup;
}
+ priv = vm->privateData;
cfg = virQEMUDriverGetConfig(driver);
if (virDomainCheckpointCreateXMLEnsureACL(domain->conn, vm->def, flags) <
0)
goto cleanup;
+ if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_BITMAP_MERGE)) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s",
+ _("qemu binary lacks persistent bitmaps support"));
+ goto cleanup;
+ }
+
if (!(caps = virQEMUDriverGetCapabilities(driver, false)))
goto cleanup;
@@ -17077,10 +17135,10 @@ qemuDomainCheckpointCreateXML(virDomainPtr domain,
def = NULL;
}
- current = virDomainCheckpointGetCurrent(vm->checkpoints);
- if (current) {
+ other = virDomainCheckpointGetCurrent(vm->checkpoints);
+ if (other) {
if (!redefine &&
- VIR_STRDUP(chk->def->parent_name, current->def->name) < 0)
+ VIR_STRDUP(chk->def->parent_name, other->def->name) < 0)
goto endjob;
if (update_current) {
virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
@@ -17097,7 +17155,15 @@ qemuDomainCheckpointCreateXML(virDomainPtr domain,
* makes sense, such as checking that qemu-img recognizes the
* checkpoint bitmap name in at least one of the domain's disks? */
} else {
- /* TODO: issue QMP transaction command */
+ if (!(actions = virJSONValueNewArray()))
+ goto endjob;
+ if (qemuDomainCheckpointAddActions(vm, actions, other,
+ virDomainCheckpointObjGetDef(chk)) < 0)
+ goto endjob;
+ qemuDomainObjEnterMonitor(driver, vm);
+ ret = qemuMonitorTransaction(priv->mon, &actions);
+ if (qemuDomainObjExitMonitor(driver, vm) < 0 || ret < 0)
+ goto endjob;
}
/* If we fail after this point, there's not a whole lot we can do;
@@ -17133,6 +17199,7 @@ qemuDomainCheckpointCreateXML(virDomainPtr domain,
qemuDomainObjEndJob(driver, vm);
cleanup:
+ virJSONValueFree(actions);
virDomainObjEndAPI(&vm);
VIR_FREE(xml);
virObjectUnref(caps);
@@ -17306,6 +17373,7 @@ qemuDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
{
virQEMUDriverPtr driver = checkpoint->domain->conn->privateData;
virDomainObjPtr vm = NULL;
+ qemuDomainObjPrivatePtr priv;
int ret = -1;
virDomainMomentObjPtr chk = NULL;
virQEMUMomentRemove rem;
@@ -17328,6 +17396,22 @@ qemuDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0)
goto cleanup;
+ priv = vm->privateData;
+ if (!metadata_only) {
+ /* Until qemu-img supports offline bitmap deletion, we are stuck
+ * with requiring a running guest */
+ if (!virDomainObjIsActive(vm)) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot delete checkpoint for inactive domain"));
+ goto endjob;
+ }
+ if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_BITMAP_MERGE)) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s",
+ _("qemu binary lacks persistent bitmaps support"));
+ goto endjob;
+ }
+ }
+
if (!(chk = qemuCheckObjFromCheckpoint(vm, checkpoint)))
goto endjob;
--
2.20.1
4 p.m.
New subject: [libvirt] [PATCH v9 12/13] backup: Wire up qemu checkpoint commands over QMP
On Sat, Jul 06, 2019 at 22:56:12 -0500, Eric Blake wrote:
Time to actually issue the QMP transactions that create and
delete persistent checkpoints. For create, we only need one
transaction: inside, we visit all disks affected by the
checkpoint, and create a new enabled bitmap, as well as
disabling the bitmap of the parent checkpoint (if any). For
deletion, we need multiple calls: if the checkpoint to be
deleted is active, we must enable the parent; then we must
merge the existing checkpoint into the parent, and finally
we can delete the checkpoint.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/qemu/qemu_domain.c | 105 ++++++++++++++++++++++++++++++-----------
src/qemu/qemu_driver.c | 92 ++++++++++++++++++++++++++++++++++--
2 files changed, 165 insertions(+), 32 deletions(-)
[...]
diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c
index 03a143a228..2fca7bd0b8 100644
--- a/src/qemu/qemu_domain.c
+++ b/src/qemu/qemu_domain.c
@@ -8960,45 +8960,93 @@ qemuDomainCheckpointDiscard(virQEMUDriverPtr driver,
char *chkFile = NULL;
int ret = -1;
virDomainMomentObjPtr parentchk = NULL;
+ virDomainCheckpointDefPtr parentdef = NULL;
virQEMUDriverConfigPtr cfg = virQEMUDriverGetConfig(driver);
+ size_t i, j;
+ virJSONValuePtr arr = NULL;
- if (!metadata_only) {
- if (!virDomainObjIsActive(vm)) {
- virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
- _("cannot remove checkpoint from inactive
domain"));
- goto cleanup;
- } else {
- /* TODO: Implement QMP sequence to merge bitmaps */
- // qemuDomainObjPrivatePtr priv;
- // priv = vm->privateData;
- // qemuDomainObjEnterMonitor(driver, vm);
- // /* we continue on even in the face of error */
- // qemuMonitorDeleteCheckpoint(priv->mon, chk->def->name);
- // ignore_value(qemuDomainObjExitMonitor(driver, vm));
- }
+ if (!metadata_only && !virDomainObjIsActive(vm)) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot remove checkpoint from inactive domain"));
+ goto cleanup;
}
if (virAsprintf(&chkFile, "%s/%s/%s.xml", cfg->checkpointDir,
vm->def->name, chk->def->name) < 0)
goto cleanup;
+ if (chk->def->parent_name) {
+ parentchk = virDomainCheckpointFindByName(vm->checkpoints,
+ chk->def->parent_name);
+ if (!parentchk) {
+ VIR_WARN("missing parent checkpoint matching name '%s'",
+ chk->def->parent_name);
+ }
+ parentdef = virDomainCheckpointObjGetDef(parentchk);
+ }
+
+ if (!metadata_only) {
+ qemuDomainObjPrivatePtr priv = vm->privateData;
+ bool success = true;
+ virDomainCheckpointDefPtr chkdef = virDomainCheckpointObjGetDef(chk);
+
+ if (qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0)
+ goto cleanup;
As described in previous patch, this is undesired.
+ qemuDomainObjEnterMonitor(driver, vm);
+ for (i = 0; i < chkdef->ndisks; i++) {
+ virDomainCheckpointDiskDef *disk = &chkdef->disks[i];
+ const char *node;
+
+ if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP)
+ continue;
+
+ node = qemuBlockNodeLookup(vm, disk->name);
+ if (parentchk) {
+ arr = virJSONValueNewArray();
+ if (!arr ||
+ virJSONValueArrayAppendString(arr, disk->bitmap) < 0) {
+ success = false;
+ break;
+ }
+
+ for (j = 0; j < parentdef->ndisks; j++) {
+ virDomainCheckpointDiskDef *disk2;
+
+ disk2 = &parentdef->disks[j];
+ if (STRNEQ(disk->name, disk2->name))
+ continue;
+ if (chk == virDomainCheckpointGetCurrent(vm->checkpoints)
&&
As outlined before in reviews to previous patches and also discussed on
IRC, the "current" checkpoint may not be the only one with active
bitmaps, so this might not work as expected.
+ qemuMonitorEnableBitmap(priv->mon, node,
+ disk2->bitmap) < 0) {
+ success = false;
+ break;
+ }
+ if (qemuMonitorMergeBitmaps(priv->mon, node,
+ disk2->bitmap, &arr) < 0) {
+ success = false;
+ break;
+ }
+ }
+ }
+ if (qemuMonitorDeleteBitmap(priv->mon, node, disk->bitmap) < 0) {
+ success = false;
+ break;
+ }
+ }
+ if (qemuDomainObjExitMonitor(driver, vm) < 0 || !success)
+ goto cleanup;
+ }
+
if (chk == virDomainCheckpointGetCurrent(vm->checkpoints)) {
virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
- if (update_parent && chk->def->parent_name) {
- parentchk = virDomainCheckpointFindByName(vm->checkpoints,
- chk->def->parent_name);
- if (!parentchk) {
- VIR_WARN("missing parent checkpoint matching name
'%s'",
+ if (update_parent && parentchk) {
+ virDomainCheckpointSetCurrent(vm->checkpoints, parentchk);
+ if (qemuDomainCheckpointWriteMetadata(vm, parentchk, driver->caps,
+ driver->xmlopt,
+ cfg->checkpointDir) < 0) {
+ VIR_WARN("failed to set parent checkpoint '%s' as
current",
chk->def->parent_name);
- } else {
- virDomainCheckpointSetCurrent(vm->checkpoints, parentchk);
- if (qemuDomainCheckpointWriteMetadata(vm, parentchk, driver->caps,
- driver->xmlopt,
- cfg->checkpointDir) < 0) {
- VIR_WARN("failed to set parent checkpoint '%s' as
current",
- chk->def->parent_name);
- virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
- }
+ virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
}
}
}
@@ -9014,6 +9062,7 @@ qemuDomainCheckpointDiscard(virQEMUDriverPtr driver,
cleanup:
VIR_FREE(chkFile);
virObjectUnref(cfg);
+ virJSONValueFree(arr);
return ret;
}
diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c
index 702a715902..b37307abc7 100644
--- a/src/qemu/qemu_driver.c
+++ b/src/qemu/qemu_driver.c
@@ -47,6 +47,7 @@
#include "qemu_hostdev.h"
#include "qemu_hotplug.h"
#include "qemu_monitor.h"
+#include "qemu_monitor_json.h"
I'd prefer if you not include this header directly here but I'm ashamed
of myself for including it in qemu_block.c
#include "qemu_process.h"
#include "qemu_migration.h"
#include "qemu_migration_params.h"
@@ -16994,6 +16995,53 @@ qemuDomainCheckpointPrepare(virQEMUDriverPtr driver, virCapsPtr
caps,
return ret;
}
+static int
+qemuDomainCheckpointAddActions(virDomainObjPtr vm,
+ virJSONValuePtr actions,
+ virDomainMomentObjPtr old_current,
+ virDomainCheckpointDefPtr def)
+{
+ size_t i, j;
+ int ret = -1;
+ virDomainCheckpointDefPtr olddef;
+
+ olddef = virDomainCheckpointObjGetDef(old_current);
+ for (i = 0; i < def->ndisks; i++) {
+ virDomainCheckpointDiskDef *disk = &def->disks[i];
+ const char *node;
+
+ if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP)
+ continue;
+ node = qemuBlockNodeLookup(vm, disk->name);
+ if (qemuMonitorJSONTransactionAdd(actions,
+ "block-dirty-bitmap-add",
+ "s:node", node,
+ "s:name", disk->bitmap,
+ "b:persistent", true,
+ NULL) < 0)
+ goto cleanup;
+ if (old_current) {
+ for (j = 0; j < olddef->ndisks; j++) {
+ virDomainCheckpointDiskDef *disk2;
+
+ disk2 = &olddef->disks[j];
+ if (STRNEQ(disk->name, disk2->name))
+ continue;
+ if (disk2->type == VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP &&
+ qemuMonitorJSONTransactionAdd(actions,
+
"block-dirty-bitmap-disable",
As we've discussed on IRC I think that this is an unnecessary
complication of things while we don't really know what the implications
of handling bitmaps accross multiple backing files are.
As long as you are okay to work around the implications and complex
lookup of the correct bitmap I don't mind adding it this way though.
+
"s:node", node,
+ "s:name", disk2->bitmap,
+ NULL) < 0)
+ goto cleanup;
+ }
+ }
+ }
+ ret = 0;
+
+ cleanup:
+ return ret;
+}
static virDomainCheckpointPtr
qemuDomainCheckpointCreateXML(virDomainPtr domain,
[...]
@@ -17077,10 +17135,10 @@ qemuDomainCheckpointCreateXML(virDomainPtr
domain,
def = NULL;
}
- current = virDomainCheckpointGetCurrent(vm->checkpoints);
- if (current) {
+ other = virDomainCheckpointGetCurrent(vm->checkpoints);
+ if (other) {
if (!redefine &&
- VIR_STRDUP(chk->def->parent_name, current->def->name) < 0)
+ VIR_STRDUP(chk->def->parent_name, other->def->name) < 0)
goto endjob;
if (update_current) {
virDomainCheckpointSetCurrent(vm->checkpoints, NULL);
Does this hunk belong to the previous patch?
[...]
@@ -17328,6 +17396,22 @@
qemuDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0)
goto cleanup;
+ priv = vm->privateData;
+ if (!metadata_only) {
+ /* Until qemu-img supports offline bitmap deletion, we are stuck
+ * with requiring a running guest */
+ if (!virDomainObjIsActive(vm)) {
+ virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+ _("cannot delete checkpoint for inactive
domain"));
+ goto endjob;
+ }
+ if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_BITMAP_MERGE)) {
+ virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s",
+ _("qemu binary lacks persistent bitmaps
support"));
+ goto endjob;
+ }
+ }
+
if (!(chk = qemuCheckObjFromCheckpoint(vm, checkpoint)))
goto endjob;
The rest looks good, but here this does too much with the "current"
snapshot which in my opinion will not work properly, thus I'd like to
see a fixed version of this.
10:56 p.m.
New subject: [libvirt] [PATCH v9 13/13] backup: Add virDomainCheckpointIsCurrent API
It is possible, but tedious, to tell if a checkpoint is current by
parsing XML. As this operation may be performed with some frequency,
it is worth an additional API (comparable to the existing
virDomainCheckpointGetParent that duplicates what can be learned from
XML, or the counterpart virDomainSnapshotIsCurrent although snapshots
don't currently expose whether they are current in public XML).
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
include/libvirt/libvirt-domain-checkpoint.h | 4 +++
src/driver-hypervisor.h | 5 +++
src/libvirt-domain-checkpoint.c | 38 +++++++++++++++++++++
src/libvirt_public.syms | 1 +
src/qemu/qemu_driver.c | 28 +++++++++++++++
src/remote/remote_driver.c | 1 +
src/remote/remote_protocol.x | 18 +++++++++-
src/remote_protocol-structs | 8 +++++
src/test/test_driver.c | 25 ++++++++++++++
tools/virsh-checkpoint.c | 21 +++---------
10 files changed, 132 insertions(+), 17 deletions(-)
diff --git a/include/libvirt/libvirt-domain-checkpoint.h
b/include/libvirt/libvirt-domain-checkpoint.h
index b2d5c5758b..b03e0f8328 100644
--- a/include/libvirt/libvirt-domain-checkpoint.h
+++ b/include/libvirt/libvirt-domain-checkpoint.h
@@ -127,6 +127,10 @@ virDomainCheckpointPtr virDomainCheckpointLookupByName(virDomainPtr
domain,
virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
unsigned int flags);
+/* Determine if a checkpoint is current */
+int virDomainCheckpointIsCurrent(virDomainCheckpointPtr checkpoint,
+ unsigned int flags);
+
/* Delete a checkpoint */
typedef enum {
VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = (1 << 0), /* Also delete children
*/
diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h
index c1632ae4c6..395b710a26 100644
--- a/src/driver-hypervisor.h
+++ b/src/driver-hypervisor.h
@@ -1355,6 +1355,10 @@ typedef virDomainCheckpointPtr
(*virDrvDomainCheckpointGetParent)(virDomainCheckpointPtr checkpoint,
unsigned int flags);
+typedef int
+(*virDrvDomainCheckpointIsCurrent)(virDomainCheckpointPtr checkpoint,
+ unsigned int flags);
+
typedef int
(*virDrvDomainCheckpointDelete)(virDomainCheckpointPtr checkpoint,
unsigned int flags);
@@ -1617,4 +1621,5 @@ struct _virHypervisorDriver {
virDrvDomainCheckpointLookupByName domainCheckpointLookupByName;
virDrvDomainCheckpointGetParent domainCheckpointGetParent;
virDrvDomainCheckpointDelete domainCheckpointDelete;
+ virDrvDomainCheckpointIsCurrent domainCheckpointIsCurrent;
};
diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c
index ab82d8422b..e1fd81ede0 100644
--- a/src/libvirt-domain-checkpoint.c
+++ b/src/libvirt-domain-checkpoint.c
@@ -471,6 +471,44 @@ virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
}
+/**
+ * virDomainCheckpointIsCurrent:
+ * @checkpoint: a checkpoint object
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Determine if the given checkpoint is the domain's current checkpoint. See
+ * also virDomainCheckpointCurrent().
+ *
+ * Returns 1 if current, 0 if not current, or -1 on error.
+ */
+int
+virDomainCheckpointIsCurrent(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virConnectPtr conn;
+
+ VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags);
+
+ virResetLastError();
+
+ virCheckDomainCheckpointReturn(checkpoint, -1);
+ conn = checkpoint->domain->conn;
+
+ if (conn->driver->domainCheckpointIsCurrent) {
+ int ret;
+ ret = conn->driver->domainCheckpointIsCurrent(checkpoint, flags);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+ error:
+ virDispatchError(conn);
+ return -1;
+}
+
+
/**
* virDomainCheckpointDelete:
* @checkpoint: the checkpoint to remove
diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index 54256b6317..6401916a81 100644
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -846,6 +846,7 @@ LIBVIRT_5.6.0 {
virDomainCheckpointGetName;
virDomainCheckpointGetParent;
virDomainCheckpointGetXMLDesc;
+ virDomainCheckpointIsCurrent;
virDomainCheckpointListAllChildren;
virDomainCheckpointLookupByName;
virDomainCheckpointRef;
diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c
index b37307abc7..4131367245 100644
--- a/src/qemu/qemu_driver.c
+++ b/src/qemu/qemu_driver.c
@@ -17328,6 +17328,33 @@ qemuDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
}
+static int
+qemuDomainCheckpointIsCurrent(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virDomainObjPtr vm;
+ int ret = -1;
+ virDomainMomentObjPtr chk = NULL;
+
+ virCheckFlags(0, -1);
+
+ if (!(vm = qemuDomObjFromCheckpoint(checkpoint)))
+ return -1;
+
+ if (virDomainCheckpointIsCurrentEnsureACL(checkpoint->domain->conn, vm->def)
< 0)
+ goto cleanup;
+
+ if (!(chk = qemuCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+
+ ret = chk == virDomainCheckpointGetCurrent(vm->checkpoints);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return ret;
+}
+
+
static char *
qemuDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
unsigned int flags)
@@ -23174,6 +23201,7 @@ static virHypervisorDriver qemuHypervisorDriver = {
.domainCheckpointLookupByName = qemuDomainCheckpointLookupByName, /* 5.6.0 */
.domainCheckpointGetParent = qemuDomainCheckpointGetParent, /* 5.6.0 */
.domainCheckpointDelete = qemuDomainCheckpointDelete, /* 5.6.0 */
+ .domainCheckpointIsCurrent = qemuDomainCheckpointIsCurrent, /* 5.6.0 */
};
diff --git a/src/remote/remote_driver.c b/src/remote/remote_driver.c
index 72c2336b7a..9145aa91ff 100644
--- a/src/remote/remote_driver.c
+++ b/src/remote/remote_driver.c
@@ -8596,6 +8596,7 @@ static virHypervisorDriver hypervisor_driver = {
.domainCheckpointLookupByName = remoteDomainCheckpointLookupByName, /* 5.6.0 */
.domainCheckpointGetParent = remoteDomainCheckpointGetParent, /* 5.6.0 */
.domainCheckpointDelete = remoteDomainCheckpointDelete, /* 5.6.0 */
+ .domainCheckpointIsCurrent = remoteDomainCheckpointIsCurrent, /* 5.6.0 */
};
static virNetworkDriver network_driver = {
diff --git a/src/remote/remote_protocol.x b/src/remote/remote_protocol.x
index 2f91bd1921..a2bd30360f 100644
--- a/src/remote/remote_protocol.x
+++ b/src/remote/remote_protocol.x
@@ -3718,6 +3718,15 @@ struct remote_domain_checkpoint_get_parent_ret {
remote_nonnull_domain_checkpoint parent;
};
+struct remote_domain_checkpoint_is_current_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ unsigned int flags;
+};
+
+struct remote_domain_checkpoint_is_current_ret {
+ int current;
+};
+
struct remote_domain_checkpoint_delete_args {
remote_nonnull_domain_checkpoint checkpoint;
unsigned int flags;
@@ -6584,5 +6593,12 @@ enum remote_procedure {
* @generate: both
* @acl: domain:checkpoint
*/
- REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 417
+ REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 417,
+
+ /**
+ * @generate: both
+ * @priority: high
+ * @acl: domain:read
+ */
+ REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT = 418
};
diff --git a/src/remote_protocol-structs b/src/remote_protocol-structs
index a42b4a9671..ba4337b1bd 100644
--- a/src/remote_protocol-structs
+++ b/src/remote_protocol-structs
@@ -3101,6 +3101,13 @@ struct remote_domain_checkpoint_get_parent_args {
struct remote_domain_checkpoint_get_parent_ret {
remote_nonnull_domain_checkpoint parent;
};
+struct remote_domain_checkpoint_is_current_args {
+ remote_nonnull_domain_checkpoint checkpoint;
+ u_int flags;
+};
+struct remote_domain_checkpoint_is_current_ret {
+ int current;
+};
struct remote_domain_checkpoint_delete_args {
remote_nonnull_domain_checkpoint checkpoint;
u_int flags;
@@ -3523,4 +3530,5 @@ enum remote_procedure {
REMOTE_PROC_DOMAIN_CHECKPOINT_LOOKUP_BY_NAME = 415,
REMOTE_PROC_DOMAIN_CHECKPOINT_GET_PARENT = 416,
REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 417,
+ REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT = 418,
};
diff --git a/src/test/test_driver.c b/src/test/test_driver.c
index ddc8867bdd..0c3505b038 100644
--- a/src/test/test_driver.c
+++ b/src/test/test_driver.c
@@ -7880,6 +7880,30 @@ testDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
}
+static int
+testDomainCheckpointIsCurrent(virDomainCheckpointPtr checkpoint,
+ unsigned int flags)
+{
+ virDomainObjPtr vm = NULL;
+ int ret = -1;
+ virDomainMomentObjPtr chk = NULL;
+
+ virCheckFlags(0, -1);
+
+ if (!(vm = testDomObjFromCheckpoint(checkpoint)))
+ return -1;
+
+ if (!(chk = testCheckObjFromCheckpoint(vm, checkpoint)))
+ goto cleanup;
+
+ ret = chk == virDomainCheckpointGetCurrent(vm->checkpoints);
+
+ cleanup:
+ virDomainObjEndAPI(&vm);
+ return ret;
+}
+
+
static int
testDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
unsigned int flags)
@@ -8076,6 +8100,7 @@ static virHypervisorDriver testHypervisorDriver = {
.domainCheckpointLookupByName = testDomainCheckpointLookupByName, /* 5.6.0 */
.domainCheckpointGetParent = testDomainCheckpointGetParent, /* 5.6.0 */
.domainCheckpointDelete = testDomainCheckpointDelete, /* 5.6.0 */
+ .domainCheckpointIsCurrent = testDomainCheckpointIsCurrent, /* 5.6.0 */
};
static virNetworkDriver testNetworkDriver = {
diff --git a/tools/virsh-checkpoint.c b/tools/virsh-checkpoint.c
index 8200687f8a..a2d34f2102 100644
--- a/tools/virsh-checkpoint.c
+++ b/tools/virsh-checkpoint.c
@@ -522,9 +522,6 @@ cmdCheckpointInfo(vshControl *ctl,
virDomainCheckpointPtr checkpoint = NULL;
const char *name;
char *parent = NULL;
- char *xml = NULL;
- xmlDocPtr xmldoc = NULL;
- xmlXPathContextPtr ctxt = NULL;
bool ret = false;
int count;
unsigned int flags;
@@ -542,17 +539,12 @@ cmdCheckpointInfo(vshControl *ctl,
vshPrint(ctl, "%-15s %s\n", _("Domain:"),
virDomainGetName(dom));
/* Determine if checkpoint is current. */
- xml = virDomainCheckpointGetXMLDesc(checkpoint,
- VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN);
- if (!xml)
- goto cleanup;
-
- xmldoc = virXMLParseStringCtxt(xml, _("(domain_checkpoint)"), &ctxt);
- if (!xmldoc)
- goto cleanup;
-
- if (virXPathInt("string(/domaincheckpoint/current)", ctxt, ¤t)
< 0)
+ current = virDomainCheckpointIsCurrent(checkpoint, 0);
+ if (current < 0) {
+ vshError(ctl, "%s",
+ _("unexpected problem querying checkpoint state"));
goto cleanup;
+ }
vshPrint(ctl, "%-15s %s\n", _("Current:"),
current > 0 ? _("yes") : _("no"));
@@ -583,9 +575,6 @@ cmdCheckpointInfo(vshControl *ctl,
ret = true;
cleanup:
- xmlXPathFreeContext(ctxt);
- xmlFreeDoc(xmldoc);
- VIR_FREE(xml);
VIR_FREE(parent);
virshDomainCheckpointFree(checkpoint);
virshDomainFree(dom);
--
2.20.1
4:02 p.m.
New subject: [libvirt] [PATCH v9 13/13] backup: Add virDomainCheckpointIsCurrent API
On Sat, Jul 06, 2019 at 22:56:13 -0500, Eric Blake wrote:
It is possible, but tedious, to tell if a checkpoint is current by
parsing XML. As this operation may be performed with some frequency,
As I've pointed out that there may be multiple and only partially active
checkpoints, generalizing it to 'current' does not make sense in my
opinion. Also I doubt that this information would be useful, and thus I
think this patch does not make sense at this point.
1952
days inactive
1969
days old
30 comments
3 participants
participants (3)
-
Cole Robinson -
Eric Blake -
Peter Krempa