From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1539321031760592.2545173770555; Thu, 11 Oct 2018 22:10:31 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id E2FDF3081D0B; Fri, 12 Oct 2018 05:10:28 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 72A7111A0F3; Fri, 12 Oct 2018 05:10:28 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 215D74CA95; Fri, 12 Oct 2018 05:10:25 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5AOLb007008 for ; Fri, 12 Oct 2018 01:10:24 -0400 Received: by smtp.corp.redhat.com (Postfix) id 637DF11A0F2; Fri, 12 Oct 2018 05:10:24 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id 09A4911A0EE; Fri, 12 Oct 2018 05:10:22 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:03 -0500 Message-Id: <20181012051011.1398546-2-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 1/9] snapshots: Avoid term 'checkpoint' for full system snapshot X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.43]); Fri, 12 Oct 2018 05:10:29 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" Upcoming patches plan to introduce virDomainCheckpointPtr as a new object for use in incremental backups, along with documentation on how incremental backups differ from snapshots. But first, we need to rename any existing mention of a 'system checkpoint' to instead be a 'full system snapshot', so that we aren't overloading the term checkpoint. Signed-off-by: Eric Blake --- v2: wording improvements based on review --- include/libvirt/libvirt-domain-snapshot.h | 2 +- docs/formatsnapshot.html.in | 31 +++++++++++------------ src/conf/snapshot_conf.c | 4 +-- src/libvirt-domain-snapshot.c | 7 ++--- src/qemu/qemu_driver.c | 12 ++++----- tools/virsh-snapshot.c | 2 +- tools/virsh.pod | 14 +++++----- 7 files changed, 36 insertions(+), 36 deletions(-) diff --git a/include/libvirt/libvirt-domain-snapshot.h b/include/libvirt/li= bvirt-domain-snapshot.h index 20771f9b1e..00954a0d3a 100644 --- a/include/libvirt/libvirt-domain-snapshot.h +++ b/include/libvirt/libvirt-domain-snapshot.h @@ -60,7 +60,7 @@ typedef enum { VIR_DOMAIN_SNAPSHOT_CREATE_HALT =3D (1 << 3), /* Stop running g= uest after snapshot */ VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY =3D (1 << 4), /* disk snapshot,= not - system checkpoin= t */ + full system */ VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT =3D (1 << 5), /* reuse any exis= ting external files */ VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE =3D (1 << 6), /* use guest agen= t to diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in index fbbecfd242..c60b4fb7c9 100644 --- a/docs/formatsnapshot.html.in +++ b/docs/formatsnapshot.html.in @@ -33,7 +33,7 @@ resume in a consistent state; but if the disks are modified externally in the meantime, this is likely to lead to data corruption. -
system checkpoint
+
full system
A combination of disk snapshots for all disks as well as VM memory state, which can be used to resume the guest from where it left off with symptoms similar to hibernation (that is, TCP @@ -55,11 +55,12 @@ as virDomainSaveImageGetXMLDesc() to work with those files.

-

System checkpoints are created - by virDomainSnapshotCreateXML() with no flags, and +

Full system snapshots are created + by virDomainSnapshotCreateXML() with no flags, while disk snapshots are created by the same function with - the VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY flag; in - both cases, they are restored by + the VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY + flag. Regardless of the flags provided, restoration of the + snapshot is handled by the virDomainRevertToSnapshot() function. For these types of snapshots, libvirt tracks each snapshot as a separate virDomainSnapshotPtr object, and maintains @@ -128,13 +129,10 @@ what file name is created in an external snapshot. On output, this is fully populated to show the state of each disk in the snapshot, including any properties that were generated by the - hypervisor defaults. For system checkpoints, this field is - ignored on input and omitted on output (a system checkpoint - implies that all disks participate in the snapshot process, - and since the current implementation only does internal system - checkpoints, there are no extra details to add); a future - release may allow the use of disks with a system - checkpoint. This element has a list of disk + hypervisor defaults. For full system snapshots, this field is + ignored on input and omitted on output (a full system snapshot + implies that all disks participate in the snapshot process). + This element has a list of disk sub-elements, describing anywhere from zero to all of the disks associated with the domain. Since 0.9.5 @@ -206,11 +204,12 @@

state
The state of the domain at the time this snapshot was taken. - If the snapshot was created as a system checkpoint, then this - is the state of the domain at that time; when the domain is + If a full system snapshot was created, then this + is the state of the domain at that time. When the domain is reverted to this snapshot, the domain's state will default to - whatever is in this field unless additional flags are passed - to virDomainRevertToSnapshot(). Additionally, + this state, unless overridden + by virDomainRevertToSnapshot() flags to revert to + a running or paused state. Additionally, this field can be the value "disk-snapshot" (since 0.9.5) when it represents only a disk snapshot (no VM memory state), and reverting to this diff --git a/src/conf/snapshot_conf.c b/src/conf/snapshot_conf.c index adba149241..f89048e3f1 100644 --- a/src/conf/snapshot_conf.c +++ b/src/conf/snapshot_conf.c @@ -1302,8 +1302,8 @@ virDomainSnapshotRedefinePrep(virDomainPtr domain, if ((other->def->state =3D=3D VIR_DOMAIN_DISK_SNAPSHOT) !=3D (def->state =3D=3D VIR_DOMAIN_DISK_SNAPSHOT)) { virReportError(VIR_ERR_INVALID_ARG, - _("cannot change between disk snapshot and " - "system checkpoint in snapshot %s"), + _("cannot change between disk only and " + "full system in snapshot %s"), def->name); goto cleanup; } diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c index 100326a5e7..1cc0188928 100644 --- a/src/libvirt-domain-snapshot.c +++ b/src/libvirt-domain-snapshot.c @@ -105,8 +105,9 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapsh= ot) * contained in xmlDesc. * * If @flags is 0, the domain can be active, in which case the - * snapshot will be a system checkpoint (both disk state and runtime - * VM state such as RAM contents), where reverting to the snapshot is + * snapshot will be a full system snapshot (capturing both disk state, + * and runtime VM state such as RAM contents), where reverting to the + * snapshot is * the same as resuming from hibernation (TCP connections may have * timed out, but everything else picks up where it left off); or * the domain can be inactive, in which case the snapshot includes @@ -149,7 +150,7 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapsh= ot) * is not paused while creating the snapshot. This increases the size * of the memory dump file, but reduces downtime of the guest while * taking the snapshot. Some hypervisors only support this flag during - * external checkpoints. + * external snapshots. * * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY, then the * snapshot will be limited to the disks described in @xmlDesc, and no diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index a52e2495d5..707773c1e3 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -2153,7 +2153,7 @@ qemuDomainReset(virDomainPtr dom, unsigned int flags) } -/* Count how many snapshots in a set are external snapshots or checkpoints= . */ +/* Count how many snapshots in a set are external snapshots. */ static int qemuDomainSnapshotCountExternal(void *payload, const void *name ATTRIBUTE_UNUSED, @@ -14713,7 +14713,7 @@ qemuDomainSnapshotPrepare(virDomainObjPtr vm, if ((def->memory =3D=3D VIR_DOMAIN_SNAPSHOT_LOCATION_INTERNAL && !foun= d_internal) || (found_internal && forbid_internal)) { virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", - _("internal snapshots and checkpoints require all " + _("internal and full system snapshots require all " "disks to be selected for snapshot")); goto cleanup; } @@ -15163,7 +15163,7 @@ qemuDomainSnapshotCreateActiveExternal(virQEMUDrive= rPtr driver, if (virDomainObjGetState(vm, NULL) =3D=3D VIR_DOMAIN_PMSUSPENDED) { pmsuspended =3D true; } else if (virDomainObjGetState(vm, NULL) =3D=3D VIR_DOMAIN_RUNNING) { - /* For external checkpoints (those with memory), the guest + /* For full system external snapshots (those with memory), the gue= st * must pause (either by libvirt up front, or by qemu after * _LIVE converges). */ if (memory) @@ -15391,7 +15391,7 @@ qemuDomainSnapshotCreateXML(virDomainPtr domain, redefine)) { virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", _("live snapshot creation is supported only " - "with external checkpoints")); + "during full system snapshots")); goto cleanup; } @@ -15511,12 +15511,12 @@ qemuDomainSnapshotCreateXML(virDomainPtr domain, } else if (virDomainObjIsActive(vm)) { if (flags & VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY || snap->def->memory =3D=3D VIR_DOMAIN_SNAPSHOT_LOCATION_EXTERNAL= ) { - /* external checkpoint or disk snapshot */ + /* external full system or disk snapshot */ if (qemuDomainSnapshotCreateActiveExternal(driver, vm, snap, flags) < = 0) goto endjob; } else { - /* internal checkpoint */ + /* internal full system */ if (qemuDomainSnapshotCreateActiveInternal(driver, vm, snap, flags) < = 0) goto endjob; diff --git a/tools/virsh-snapshot.c b/tools/virsh-snapshot.c index 73861957ba..7b340162f3 100644 --- a/tools/virsh-snapshot.c +++ b/tools/virsh-snapshot.c @@ -1427,7 +1427,7 @@ static const vshCmdOptDef opts_snapshot_list[] =3D { }, {.name =3D "active", .type =3D VSH_OT_BOOL, - .help =3D N_("filter by snapshots taken while active (system checkpoi= nts)") + .help =3D N_("filter by snapshots taken while active (full system sna= pshots)") }, {.name =3D "disk-only", .type =3D VSH_OT_BOOL, diff --git a/tools/virsh.pod b/tools/virsh.pod index 86c041d575..58ab9a090b 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -4490,8 +4490,8 @@ If I<--halt> is specified, the domain will be left in= an inactive state after the snapshot is created. If I<--disk-only> is specified, the snapshot will only include disk -state rather than the usual system checkpoint with vm state. Disk -snapshots are faster than full system checkpoints, but reverting to a +content rather than the usual full system snapshot with vm state. Disk +snapshots are captured faster than full system snapshots, but reverting to= a disk snapshot may require fsck or journal replays, since it is like the disk state at the point when the power cord is abruptly pulled; and mixing I<--halt> and I<--disk-only> loses any data that was not @@ -4530,10 +4530,10 @@ this. If this flag is not specified, then some hyp= ervisors may fail after partially performing the action, and B must be used to see whether any partial changes occurred. -If I<--live> is specified, libvirt takes the snapshot (checkpoint) while +If I<--live> is specified, libvirt takes the snapshot while the guest is running. Both disk snapshot and domain memory snapshot are taken. This increases the size of the memory image of the external -checkpoint. This is currently supported only for external checkpoints. +snapshot. This is currently supported only for full system external snapsh= ots. Existence of snapshot metadata will prevent attempts to B a persistent domain. However, for transient domains, snapshot @@ -4553,7 +4553,7 @@ Otherwise, if I<--halt> is specified, the domain will= be left in an inactive state after the snapshot is created, and if I<--disk-only> is specified, the snapshot will not include vm state. -The I<--memspec> option can be used to control whether a checkpoint +The I<--memspec> option can be used to control whether a full system snaps= hot is internal or external. The I<--memspec> flag is mandatory, followed by a B of the form B<[file=3D]name[,snapshot=3Dtype]>, where type can be B, B, or B. To include a literal @@ -4561,7 +4561,7 @@ comma in B, escape it with a second comm= a. I<--memspec> cannot be used together with I<--disk-only>. The I<--diskspec> option can be used to control how I<--disk-only> and -external checkpoints create external files. This option can occur +external full system snapshots create external files. This option can occ= ur multiple times, according to the number of elements in the domain xml. Each is in the form B. A I @@ -4601,7 +4601,7 @@ see whether any partial changes occurred. 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 -checkpoint. This is currently supported only for external checkpoints. +snapshot. This is currently supported only for external full system snapsh= ots. =3Ditem B I {[I<--name>] | [I<--security-info>] | [I]} --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1539321048485202.00130857854708; Thu, 11 Oct 2018 22:10:48 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 5803B307D943; Fri, 12 Oct 2018 05:10:46 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 1418411A1D2; Fri, 12 Oct 2018 05:10:46 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id AB167180B61F; Fri, 12 Oct 2018 05:10:45 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5ARlN007020 for ; Fri, 12 Oct 2018 01:10:27 -0400 Received: by smtp.corp.redhat.com (Postfix) id F2AB911A0F2; Fri, 12 Oct 2018 05:10:26 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id A88F311A0EE; Fri, 12 Oct 2018 05:10:24 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:04 -0500 Message-Id: <20181012051011.1398546-3-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 2/9] domain_conf: Expose virDomainStorageNetworkParseHost X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.48]); Fri, 12 Oct 2018 05:10:47 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" An upcoming patch wants to reuse XML parsing of both unix and tcp network host descriptions in the context of setting up a backup NBD server. Make that easier by refactoring the existing parser. Signed-off-by: Eric Blake --- src/conf/domain_conf.h | 2 ++ src/conf/domain_conf.c | 43 ++++++++++++++++++++-------------------- src/libvirt_private.syms | 1 + 3 files changed, 25 insertions(+), 21 deletions(-) diff --git a/src/conf/domain_conf.h b/src/conf/domain_conf.h index e30a4b2fe7..785786c9b9 100644 --- a/src/conf/domain_conf.h +++ b/src/conf/domain_conf.h @@ -3143,6 +3143,8 @@ int virDomainDiskInsert(virDomainDefPtr def, ATTRIBUTE_RETURN_CHECK; void virDomainDiskInsertPreAlloced(virDomainDefPtr def, virDomainDiskDefPtr disk); +int virDomainStorageNetworkParseHost(xmlNodePtr hostnode, + virStorageNetHostDefPtr host); int virDomainDiskDefAssignAddress(virDomainXMLOptionPtr xmlopt, virDomainDiskDefPtr def, const virDomainDef *vmdef); diff --git a/src/conf/domain_conf.c b/src/conf/domain_conf.c index 9911d56130..0fd6004c48 100644 --- a/src/conf/domain_conf.c +++ b/src/conf/domain_conf.c @@ -7122,23 +7122,21 @@ virDomainHostdevSubsysPCIDefParseXML(xmlNodePtr nod= e, } -static int +int virDomainStorageNetworkParseHost(xmlNodePtr hostnode, - virStorageNetHostDefPtr *hosts, - size_t *nhosts) + virStorageNetHostDefPtr host) { int ret =3D -1; char *transport =3D NULL; char *port =3D NULL; - virStorageNetHostDef host; - memset(&host, 0, sizeof(host)); - host.transport =3D VIR_STORAGE_NET_HOST_TRANS_TCP; + memset(host, 0, sizeof(*host)); + host->transport =3D VIR_STORAGE_NET_HOST_TRANS_TCP; /* transport can be tcp (default), unix or rdma. */ if ((transport =3D virXMLPropString(hostnode, "transport"))) { - host.transport =3D virStorageNetHostTransportTypeFromString(transp= ort); - if (host.transport < 0) { + host->transport =3D virStorageNetHostTransportTypeFromString(trans= port); + if (host->transport < 0) { virReportError(VIR_ERR_CONFIG_UNSUPPORTED, _("unknown protocol transport type '%s'"), transport); @@ -7146,17 +7144,17 @@ virDomainStorageNetworkParseHost(xmlNodePtr hostnod= e, } } - host.socket =3D virXMLPropString(hostnode, "socket"); + host->socket =3D virXMLPropString(hostnode, "socket"); - if (host.transport =3D=3D VIR_STORAGE_NET_HOST_TRANS_UNIX && - host.socket =3D=3D NULL) { + if (host->transport =3D=3D VIR_STORAGE_NET_HOST_TRANS_UNIX && + host->socket =3D=3D NULL) { virReportError(VIR_ERR_XML_ERROR, "%s", _("missing socket for unix transport")); goto cleanup; } - if (host.transport !=3D VIR_STORAGE_NET_HOST_TRANS_UNIX && - host.socket !=3D NULL) { + if (host->transport !=3D VIR_STORAGE_NET_HOST_TRANS_UNIX && + host->socket !=3D NULL) { virReportError(VIR_ERR_XML_ERROR, _("transport '%s' does not support " "socket attribute"), @@ -7164,26 +7162,24 @@ virDomainStorageNetworkParseHost(xmlNodePtr hostnod= e, goto cleanup; } - if (host.transport !=3D VIR_STORAGE_NET_HOST_TRANS_UNIX) { - if (!(host.name =3D virXMLPropString(hostnode, "name"))) { + if (host->transport !=3D VIR_STORAGE_NET_HOST_TRANS_UNIX) { + if (!(host->name =3D virXMLPropString(hostnode, "name"))) { virReportError(VIR_ERR_XML_ERROR, "%s", _("missing name for host")); goto cleanup; } if ((port =3D virXMLPropString(hostnode, "port"))) { - if (virStringParsePort(port, &host.port) < 0) + if (virStringParsePort(port, &host->port) < 0) goto cleanup; } } - if (VIR_APPEND_ELEMENT(*hosts, *nhosts, host) < 0) - goto cleanup; - ret =3D 0; cleanup: - virStorageNetHostDefClear(&host); + if (ret < 0) + virStorageNetHostDefClear(host); VIR_FREE(transport); VIR_FREE(port); return ret; @@ -7200,9 +7196,14 @@ virDomainStorageNetworkParseHosts(xmlNodePtr node, for (child =3D node->children; child; child =3D child->next) { if (child->type =3D=3D XML_ELEMENT_NODE && virXMLNodeNameEqual(child, "host")) { + virStorageNetHostDef host; - if (virDomainStorageNetworkParseHost(child, hosts, nhosts) < 0) + if (virDomainStorageNetworkParseHost(child, &host) < 0) return -1; + if (VIR_APPEND_ELEMENT(*hosts, *nhosts, host) < 0) { + virStorageNetHostDefClear(&host); + return -1; + } } } diff --git a/src/libvirt_private.syms b/src/libvirt_private.syms index 335210c31d..eb1ad579d9 100644 --- a/src/libvirt_private.syms +++ b/src/libvirt_private.syms @@ -545,6 +545,7 @@ virDomainStateReasonFromString; virDomainStateReasonToString; virDomainStateTypeFromString; virDomainStateTypeToString; +virDomainStorageNetworkParseHost; virDomainStorageSourceFormat; virDomainStorageSourceParse; virDomainTaintTypeFromString; --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1539321053171381.91535428417774; Thu, 11 Oct 2018 22:10:53 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 52CC5A5D9A; Fri, 12 Oct 2018 05:10:51 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 14A887663E; Fri, 12 Oct 2018 05:10:51 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id AC18F18005B4; Fri, 12 Oct 2018 05:10:50 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5ASCP007030 for ; Fri, 12 Oct 2018 01:10:28 -0400 Received: by smtp.corp.redhat.com (Postfix) id 83AAB11A0F5; Fri, 12 Oct 2018 05:10:28 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3D27311A0EC; Fri, 12 Oct 2018 05:10:27 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:05 -0500 Message-Id: <20181012051011.1398546-4-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 3/9] backup: Document nuances between different state capture APIs X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.26]); Fri, 12 Oct 2018 05:10:52 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" Upcoming patches will add support for incremental backups via a new API; but first, we need 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 --- v2: wording improvements based on review --- docs/docs.html.in | 5 + docs/domainstatecapture.html.in | 314 ++++++++++++++++++++++++++++++++ docs/formatsnapshot.html.in | 2 + 3 files changed, 321 insertions(+) create mode 100644 docs/domainstatecapture.html.in diff --git a/docs/docs.html.in b/docs/docs.html.in index 40e0e3b82e..4c46b74980 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -120,6 +120,11 @@
Secure usage
Secure usage of the libvirt APIs
+ +
Domain state + capture
+
Comparison between different methods of capturing domain + state
diff --git a/docs/domainstatecapture.html.in b/docs/domainstatecapture.html= .in new file mode 100644 index 0000000000..f7f2fe0b98 --- /dev/null +++ b/docs/domainstatecapture.html.in @@ -0,0 +1,314 @@ + + + + + +

Domain state capture using Libvirt

+ +
    + +

    + 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. +

    + +

    + 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. Some of the topics presented below may relate to inactive + state collection, but it is not the primary focus of this page. +

    + +

    State capture trade-offs

    + +

    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. +

    + +

    + 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: +

    + +
    +
    Duration
    +
    Capturing state can be a lengthy process, so while the + captured state ideally represents an atomic point in time + correpsonding 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. +
    + +
    Amount of state
    +
    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. +
    + +
    Quiescing of data
    +
    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. +
    + +
    Quantity of files
    +
    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. +
    + +
    Impact to guest definition
    +
    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. +
    + +
    Third-party integration
    +
    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.
    + +
    Full vs. incremental
    +
    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.
    + +
    Local vs. remote
    +
    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.
    + +
    Network latency
    +
    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.
    +
    + +

    + 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. +

    + +

    State capture APIs

    +

    With those definitions, the following libvirt APIs related to + state capture have these properties:

    +
    +
    virDomainManagedSave
    +
    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.
    + +
    virDomainSave
    +
    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.
    + +
    virDomainSnapshotCreateXML()
    +
    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 virDomainBlockCommit() 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 XML details used with + this command.
    + +
    virDomainFSFreeze(), virDomainFSThaw()
    +
    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.
    + +
    virDomainBlockCopy()
    +
    This API wraps approaches for capturing the disk state (but + not memory) of a running guest, but does not track + accompanying guest memory state, but can only operate on one + block device per job. To get a consistent copy of multiple + disks, multiple jobs just 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.
    + +
    virDomainCheckpointCreateXML()
    +
    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 virDomainBackupBegin(), since a + second incremental backup is most useful when using the + checkpoint created during the first.
    + +
    virDomainBackupBegin(), virDomainBackupEnd()
    +
    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.
    +
    + +

    Examples

    +

    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.

    + +

    1. Backup via temporary snapshot + 

    +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
+

    + +

    2. Direct backup + 

    +virDomainFSFreeze()
+virDomainBackupBegin()
+virDomainFSThaw()
+wait for push mode event, or pull data over NBD # most time spent here
+virDomainBackeupEnd()
+

    + + + diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in index c60b4fb7c9..9ee355198f 100644 --- a/docs/formatsnapshot.html.in +++ b/docs/formatsnapshot.html.in @@ -9,6 +9,8 @@

    Snapshot XML

    + Snapshots are one form + of domain state capture. There are several types of snapshots:

    --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1539321059201885.3827400306769; Thu, 11 Oct 2018 22:10:59 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id B0F1130832D2; Fri, 12 Oct 2018 05:10:56 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 6F5FD28DF6; Fri, 12 Oct 2018 05:10:56 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 227744CAA7; Fri, 12 Oct 2018 05:10:56 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5AUao007043 for ; Fri, 12 Oct 2018 01:10:30 -0400 Received: by smtp.corp.redhat.com (Postfix) id 06CF811A0FA; Fri, 12 Oct 2018 05:10:30 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id C0A1811A0EC; Fri, 12 Oct 2018 05:10:28 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:06 -0500 Message-Id: <20181012051011.1398546-5-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 4/9] backup: Introduce virDomainCheckpointPtr X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.44]); Fri, 12 Oct 2018 05:10:57 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" Prepare for introducing a bunch of new public APIs related to backup checkpoints by first introducing a new internal type and errors associated with that type. 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. Signed-off-by: Eric Blake --- v2: fix copy-and-paste issue in virerror.c [John] --- include/libvirt/virterror.h | 6 +++- src/util/virerror.c | 21 ++++++++++++- include/libvirt/libvirt.h | 2 ++ src/datatypes.h | 31 ++++++++++++++++++- src/datatypes.c | 62 ++++++++++++++++++++++++++++++++++++- src/libvirt_private.syms | 2 ++ 6 files changed, 120 insertions(+), 4 deletions(-) diff --git a/include/libvirt/virterror.h b/include/libvirt/virterror.h index 57aadb8d16..65efc458a5 100644 --- a/include/libvirt/virterror.h +++ b/include/libvirt/virterror.h @@ -4,7 +4,7 @@ * Description: Provides the interfaces of the libvirt library to handle * errors raised while using the library. * - * Copyright (C) 2006-2016 Red Hat, Inc. + * Copyright (C) 2006-2018 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 @@ -133,6 +133,7 @@ typedef enum { VIR_FROM_PERF =3D 65, /* Error from perf */ VIR_FROM_LIBSSH =3D 66, /* Error from libssh connection transpor= t */ VIR_FROM_RESCTRL =3D 67, /* Error from resource control */ + VIR_FROM_DOMAIN_CHECKPOINT =3D 68,/* Error from domain checkpoint */ # ifdef VIR_ENUM_SENTINELS VIR_ERR_DOMAIN_LAST @@ -323,6 +324,9 @@ typedef enum { VIR_ERR_DEVICE_MISSING =3D 99, /* fail to find the desired devi= ce */ VIR_ERR_INVALID_NWFILTER_BINDING =3D 100, /* invalid nwfilter binding= */ VIR_ERR_NO_NWFILTER_BINDING =3D 101, /* no nwfilter binding */ + VIR_ERR_INVALID_DOMAIN_CHECKPOINT =3D 102,/* invalid domain checkpoint= */ + VIR_ERR_NO_DOMAIN_CHECKPOINT =3D 103, /* domain checkpoint not found */ + VIR_ERR_NO_DOMAIN_BACKUP =3D 104, /* domain backup job id not foun= d */ } virErrorNumber; /** diff --git a/src/util/virerror.c b/src/util/virerror.c index 683e51aa19..34a4960a73 100644 --- a/src/util/virerror.c +++ b/src/util/virerror.c @@ -1,7 +1,7 @@ /* * virerror.c: error handling and reporting code for libvirt * - * Copyright (C) 2006, 2008-2016 Red Hat, Inc. + * Copyright (C) 2006, 2008-2018 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 @@ -136,6 +136,7 @@ VIR_ENUM_IMPL(virErrorDomain, VIR_ERR_DOMAIN_LAST, "Perf", /* 65 */ "Libssh transport layer", "Resource control", + "Domain Checkpoint", ) @@ -1509,6 +1510,24 @@ virErrorMsg(virErrorNumber error, const char *info) else errmsg =3D _("Network filter binding not found: %s"); break; + case VIR_ERR_INVALID_DOMAIN_CHECKPOINT: + if (info =3D=3D NULL) + errmsg =3D _("Invalid checkpoint"); + else + errmsg =3D _("Invalid checkpoint: %s"); + break; + case VIR_ERR_NO_DOMAIN_CHECKPOINT: + if (info =3D=3D NULL) + errmsg =3D _("Domain checkpoint not found"); + else + errmsg =3D _("Domain checkpoint not found: %s"); + break; + case VIR_ERR_NO_DOMAIN_BACKUP: + if (info =3D=3D NULL) + errmsg =3D _("Domain backup job id not found"); + else + errmsg =3D _("Domain backup job id not found: %s"); + break; } return errmsg; } diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h index 36f6d60775..26887a40e7 100644 --- a/include/libvirt/libvirt.h +++ b/include/libvirt/libvirt.h @@ -36,6 +36,8 @@ extern "C" { # include # include # include +typedef struct _virDomainCheckpoint virDomainCheckpoint; +typedef virDomainCheckpoint *virDomainCheckpointPtr; # include # include # include diff --git a/src/datatypes.h b/src/datatypes.h index e1b38706dc..c27ac98437 100644 --- a/src/datatypes.h +++ b/src/datatypes.h @@ -1,7 +1,7 @@ /* * datatypes.h: management of structs for public data types * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2018 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 @@ -31,6 +31,7 @@ extern virClassPtr virConnectClass; extern virClassPtr virDomainClass; +extern virClassPtr virDomainCheckpointClass; extern virClassPtr virDomainSnapshotClass; extern virClassPtr virInterfaceClass; extern virClassPtr virNetworkClass; @@ -307,6 +308,21 @@ extern virClassPtr virAdmClientClass; } \ } while (0) +# define virCheckDomainCheckpointReturn(obj, retval) \ + do { \ + virDomainCheckpointPtr _check =3D (obj); \ + if (!virObjectIsClass(_check, virDomainCheckpointClass) || \ + !virObjectIsClass(_check->domain, virDomainClass) || \ + !virObjectIsClass(_check->domain->conn, virConnectClass)) { \ + virReportErrorHelper(VIR_FROM_DOMAIN_CHECKPOINT, \ + VIR_ERR_INVALID_DOMAIN_CHECKPOINT, \ + __FILE__, __FUNCTION__, __LINE__, \ + __FUNCTION__); \ + virDispatchError(NULL); \ + return retval; \ + } \ + } while (0) + /* Helper macros to implement VIR_DOMAIN_DEBUG using just C99. This * assumes you pass fewer than 15 arguments to VIR_DOMAIN_DEBUG, but @@ -667,6 +683,17 @@ struct _virStream { void *privateData; }; +/** + * _virDomainCheckpoint + * + * Internal structure associated with a domain checkpoint + */ +struct _virDomainCheckpoint { + virObject parent; + char *name; + virDomainPtr domain; +}; + /** * _virDomainSnapshot * @@ -743,6 +770,8 @@ virNWFilterPtr virGetNWFilter(virConnectPtr conn, virNWFilterBindingPtr virGetNWFilterBinding(virConnectPtr conn, const char *portdev, const char *filtername); +virDomainCheckpointPtr virGetDomainCheckpoint(virDomainPtr domain, + const char *name); virDomainSnapshotPtr virGetDomainSnapshot(virDomainPtr domain, const char *name); diff --git a/src/datatypes.c b/src/datatypes.c index caf035f178..108de20b20 100644 --- a/src/datatypes.c +++ b/src/datatypes.c @@ -1,7 +1,7 @@ /* * datatypes.c: management of structs for public data types * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2018 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 @@ -36,6 +36,7 @@ VIR_LOG_INIT("datatypes"); virClassPtr virConnectClass; virClassPtr virConnectCloseCallbackDataClass; virClassPtr virDomainClass; +virClassPtr virDomainCheckpointClass; virClassPtr virDomainSnapshotClass; virClassPtr virInterfaceClass; virClassPtr virNetworkClass; @@ -50,6 +51,7 @@ virClassPtr virStoragePoolClass; static void virConnectDispose(void *obj); static void virConnectCloseCallbackDataDispose(void *obj); static void virDomainDispose(void *obj); +static void virDomainCheckpointDispose(void *obj); static void virDomainSnapshotDispose(void *obj); static void virInterfaceDispose(void *obj); static void virNetworkDispose(void *obj); @@ -86,6 +88,7 @@ virDataTypesOnceInit(void) DECLARE_CLASS_LOCKABLE(virConnect); DECLARE_CLASS_LOCKABLE(virConnectCloseCallbackData); DECLARE_CLASS(virDomain); + DECLARE_CLASS(virDomainCheckpoint); DECLARE_CLASS(virDomainSnapshot); DECLARE_CLASS(virInterface); DECLARE_CLASS(virNetwork); @@ -955,6 +958,63 @@ virDomainSnapshotDispose(void *obj) } +/** + * virGetDomainCheckpoint: + * @domain: the domain to checkpoint + * @name: pointer to the domain checkpoint name + * + * Allocates a new domain checkpoint object. When the object is no longer = needed, + * virObjectUnref() must be called in order to not leak data. + * + * Returns a pointer to the domain checkpoint object, or NULL on error. + */ +virDomainCheckpointPtr +virGetDomainCheckpoint(virDomainPtr domain, const char *name) +{ + virDomainCheckpointPtr ret =3D NULL; + + if (virDataTypesInitialize() < 0) + return NULL; + + virCheckDomainGoto(domain, error); + virCheckNonNullArgGoto(name, error); + + if (!(ret =3D virObjectNew(virDomainCheckpointClass))) + goto error; + if (VIR_STRDUP(ret->name, name) < 0) + goto error; + + ret->domain =3D virObjectRef(domain); + + return ret; + + error: + virObjectUnref(ret); + return NULL; +} + + +/** + * virDomainCheckpointDispose: + * @obj: the domain checkpoint to release + * + * Unconditionally release all memory associated with a checkpoint. + * The checkpoint object must not be used once this method returns. + * + * It will also unreference the associated connection object, + * which may also be released if its ref count hits zero. + */ +static void +virDomainCheckpointDispose(void *obj) +{ + virDomainCheckpointPtr checkpoint =3D obj; + VIR_DEBUG("release checkpoint %p %s", checkpoint, checkpoint->name); + + VIR_FREE(checkpoint->name); + virObjectUnref(checkpoint->domain); +} + + virAdmConnectPtr virAdmConnectNew(void) { diff --git a/src/libvirt_private.syms b/src/libvirt_private.syms index eb1ad579d9..4d79ec7adb 100644 --- a/src/libvirt_private.syms +++ b/src/libvirt_private.syms @@ -1207,10 +1207,12 @@ virConnectCloseCallbackDataClass; virConnectCloseCallbackDataGetCallback; virConnectCloseCallbackDataRegister; virConnectCloseCallbackDataUnregister; +virDomainCheckpointClass; virDomainClass; virDomainSnapshotClass; virGetConnect; virGetDomain; +virGetDomainCheckpoint; virGetDomainSnapshot; virGetInterface; virGetNetwork; --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1539321063889699.4612972035253; Thu, 11 Oct 2018 22:11:03 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id E7551307D984; Fri, 12 Oct 2018 05:11:01 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id A373511A0EC; Fri, 12 Oct 2018 05:11:01 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 3CC45180BAD2; Fri, 12 Oct 2018 05:11:01 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5AgcV007067 for ; Fri, 12 Oct 2018 01:10:42 -0400 Received: by smtp.corp.redhat.com (Postfix) id AEA5B11A0FA; Fri, 12 Oct 2018 05:10:42 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8885111A098; Fri, 12 Oct 2018 05:10:30 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:07 -0500 Message-Id: <20181012051011.1398546-6-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 5/9] backup: Document new XML for backups X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.48]); Fri, 12 Oct 2018 05:11:02 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" Prepare for new checkpoint and backup APIs by describing the XML that will represent a checkpoint and backup. The checkpoint XML is modeled heavily after virDomainSnapshotPtr, since both represent a point in time of the guest (however, a snapshot exists with the intent to roll back to that point, while a checkpoint exists to facilitate later incremental backups). Meanwhile, the backup XML has enough information to represent both push model (the hypervisor writes the backup file to a location of the user's choice) and the pull model (the hypervisor needs local temporary storage, and also creates an NBD server that the user can use to read the backup via a third-party client).. But while a snapshot exists with the intent of rolling back to that state, a checkpoint instead makes it possible to create an incremental backup at a later time. Add testsuite coverage for some minimal uses of both XML. Ultimately, I'd love for push model backups to target a network driver rather than just a local file or block device; but doing that got hairy (while uses as the description of a host or network resource, I picked as the description of a push model backup target [defaults to qcow2 but can also be raw or any other format], and as the description of a pull model backup scratch space [must be qcow2]). The ideal refactoring would be a way to parameterize RNG to accept ... so that the name of the subelement can be for domain, or or as needed for backups. Future patches may improve this area of code. Signed-off-by: Eric Blake --- v2: apply (some) wording changes from review --- docs/docs.html.in | 3 +- docs/domainstatecapture.html.in | 4 +- docs/format.html.in | 1 + docs/formatcheckpoint.html.in | 285 +++++++++++++++++++ docs/index.html.in | 3 +- docs/schemas/domainbackup.rng | 185 ++++++++++++ docs/schemas/domaincheckpoint.rng | 94 ++++++ libvirt.spec.in | 2 + mingw-libvirt.spec.in | 4 + tests/Makefile.am | 6 +- tests/domainbackupxml2xmlin/backup-pull.xml | 9 + tests/domainbackupxml2xmlin/backup-push.xml | 9 + tests/domainbackupxml2xmlin/empty.xml | 1 + tests/domainbackupxml2xmlout/backup-pull.xml | 9 + tests/domainbackupxml2xmlout/backup-push.xml | 9 + tests/domainbackupxml2xmlout/empty.xml | 7 + tests/domaincheckpointxml2xmlin/empty.xml | 1 + tests/domaincheckpointxml2xmlin/sample.xml | 7 + tests/domaincheckpointxml2xmlout/empty.xml | 10 + tests/domaincheckpointxml2xmlout/sample.xml | 16 ++ tests/virschematest.c | 4 + 21 files changed, 664 insertions(+), 5 deletions(-) create mode 100644 docs/formatcheckpoint.html.in create mode 100644 docs/schemas/domainbackup.rng create mode 100644 docs/schemas/domaincheckpoint.rng create mode 100644 tests/domainbackupxml2xmlin/backup-pull.xml create mode 100644 tests/domainbackupxml2xmlin/backup-push.xml create mode 100644 tests/domainbackupxml2xmlin/empty.xml create mode 100644 tests/domainbackupxml2xmlout/backup-pull.xml create mode 100644 tests/domainbackupxml2xmlout/backup-push.xml create mode 100644 tests/domainbackupxml2xmlout/empty.xml create mode 100644 tests/domaincheckpointxml2xmlin/empty.xml create mode 100644 tests/domaincheckpointxml2xmlin/sample.xml create mode 100644 tests/domaincheckpointxml2xmlout/empty.xml create mode 100644 tests/domaincheckpointxml2xmlout/sample.xml diff --git a/docs/docs.html.in b/docs/docs.html.in index 4c46b74980..4914e7dbed 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -79,7 +79,8 @@ domain capabilities, node devices, secrets, - snapshots + snapshots, + backups and checkpoints
    URI format
    The URI formats used for connecting to libvirt
    diff --git a/docs/domainstatecapture.html.in b/docs/domainstatecapture.html= .in index f7f2fe0b98..9b890b4c0c 100644 --- a/docs/domainstatecapture.html.in +++ b/docs/domainstatecapture.html.in @@ -259,9 +259,9 @@ a checkpoint as a side-effect of starting a new incremental backup with virDomainBackupBegin(), since a second incremental backup is most useful when using the - checkpoint created during the first. + this command.
    virDomainBackupBegin(), virDomainBackupEnd()
    This API wraps approaches for capturing the state of disks diff --git a/docs/format.html.in b/docs/format.html.in index 22b23e3fc7..8c4e15e079 100644 --- a/docs/format.html.in +++ b/docs/format.html.in @@ -24,6 +24,7 @@
  • Node devices
  • Secrets
  • Snapshots
    • +
  • Backups and checkpoints

    Command line validation

    diff --git a/docs/formatcheckpoint.html.in b/docs/formatcheckpoint.html.in new file mode 100644 index 0000000000..f32516894f --- /dev/null +++ b/docs/formatcheckpoint.html.in @@ -0,0 +1,285 @@ + + + + +

    Checkpoint and Backup XML format

    + +
      + +

      Checkpoint XML

      + +

      + One method of capturing domain disk backups is via the use of + incremental backups. Right now, incremental backups are only + supported for the qemu hypervisor when using qcow2 disks at the + active layer; if other disk formats are in use, capturing disk + backups requires different libvirt APIs + (see domain state capture + for a comparison between APIs). +

      +

      + Libvirt is able to facilitate incremental backups by tracking + disk checkpoints, which are points in time against which it is + easy to compute which portion of the disk has changed. Given a + full backup (a backup created from the creation of the disk to a + given point in time), coupled with the creation of a disk + checkpoint at that time, and an incremental backup (a backup + created from just the dirty portion of the disk between the + first checkpoint and the second backup operation), it is + possible to do an offline reconstruction of the state of the + disk at the time of the second backup without having to copy as + much data as a second full backup would require. Most disk + checkpoints are created in concert with a backup + via virDomainBackupBegin(); however, libvirt also + exposes enough support to create disk checkpoints independently + from a backup operation + via virDomainCheckpointCreateXML(). +

      +

      + Attributes of libvirt checkpoints are stored as child elements + of the domaincheckpoint element. At checkpoint + creation time, normally only + the name, description, + and disks elements are settable. The rest of the + fields are ignored on creation and will be filled in by libvirt + in for informational purposes + by virDomainCheckpointGetXMLDesc(). However, when + redefining a checkpoint, with + the VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE flag + of virDomainCheckpointCreateXML(), all of the XML + fields described here are relevant. +

      +

      + Checkpoints are maintained in a hierarchy. A domain can have a + current checkpoint, which is the most recent checkpoint compared to + the current state of the domain (although a domain might have + checkpoints without a current checkpoint, if checkpoints have been + deleted in the meantime). Creating or reverting to a checkpoint + sets that checkpoint as current, and the prior current checkpoint is + the parent of the new checkpoint. Branches in the hierarchy can + be formed by reverting to a checkpoint with a child, then creating + another checkpoint. +

      +

      + The top-level domaincheckpoint element may contain + the following elements: +

      +
      +
      name
      +
      The name for this checkpoint. If the name is specified when + initially creating the checkpoint, then the checkpoint will have + that particular name. If the name is omitted when initially + creating the checkpoint, then libvirt will make up a name for + the checkpoint, based on the time when it was created. +
      +
      description
      +
      A human-readable description of the checkpoint. If the + description is omitted when initially creating the checkpoint, + then this field will be empty. +
      +
      disks
      +
      On input, this is an optional listing of specific + instructions for disk checkpoints; it is needed when making a + checkpoint on only a subset of the disks associated with a + domain (in particular, since qemu checkpoints require qcow2 + disks, this element may be needed on input for excluding guest + disks that are not in qcow2 format); if the entire element was + omitted on input, then all disks participate in the + checkpoint, but if individual disks were omitted from the + element, they will not be part of the checkpoint. On output, + this is fully populated to show the state of each disk in the + checkpoint. This element has a list of disk + sub-elements, describing anywhere from one to all of the disks + associated with the domain. +
      +
      disk
      +
      This sub-element describes the checkpoint properties of + a specific disk. The attribute name is + mandatory, and must match either the <target + dev=3D'name'/> or an unambiguous <source + file=3D'name'/> of one of + the disk + devices specified for the domain at the time of the + checkpoint. The attribute checkpoint is + optional on input; possible values are no + when the disk does not participate in this checkpoint; + or bitmap if the disk will track all changes + since the creation of this checkpoint via a bitmap, in + which case another attribute bitmap will be + the name of the tracking bitmap (defaulting to the + checkpoint name). On output, an additional + attribute size may be present if + the VIR_DOMAIN_CHECKPOINT_XML_SIZE flag was + used to perform a dynamic query of the estimated size in + bytes of the changes made since the checkpoint was created. +
      +
      +
      +
      creationTime
      +
      The time this checkpoint was created. The time is specified + in seconds since the Epoch, UTC (i.e. Unix time). Readonly. +
      +
      parent
      +
      The parent of this checkpoint. If present, this element + contains exactly one child element, name. This specifies the + name of the parent checkpoint of this one, and is used to + represent trees of checkpoints. Readonly. +
      +
      domain
      +
      The inactive domain + configuration at the time the checkpoint was created. + Readonly. +
      +
      + +

      Backup XML

      + +

      + Creating a backup, whether full or incremental, is done + via virDomainBackupBegin(), which takes an XML + description of the actions to perform. There are two general + modes for backups: a push mode (where the hypervisor writes out + the data to the destination file, which may be local or remote), + and a pull mode (where the hypervisor creates an NBD server that + a third-party client can then read as needed, and which requires + the use of temporary storage, typically local, until the backup + is complete). +

      +

      + The instructions for beginning a backup job are provided as + attributes and elements of the + top-level domainbackup element. This element + includes an optional attribute mode which can be + either "push" or "pull" (default push). Where elements are + optional on creation, virDomainBackupGetXMLDesc() + can be used to see the actual values selected (for example, + learning which port the NBD server is using in the pull model, + or what file names libvirt generated when none were supplied). + The following child elements are supported: +

      +
      +
      incremental
      +
      Optional. If this element is present, it must name an + existing checkpoint of the domain, which will be used to make + this backup an incremental one (in the push model, only + changes since the checkpoint are written to the destination; + in the pull model, the NBD server uses the + NBD_OPT_SET_META_CONTEXT extension to advertise to the client + which portions of the export contain changes since the + checkpoint). If omitted, a full backup is performed. +
      +
      server
      +
      Present only for a pull mode backup. Contains the same + attributes as the protocol element of a disk + attached via NBD in the domain (such as transport, socket, + name, port, or tls), necessary to set up an NBD server that + exposes the content of each disk at the time the backup + started. +
      +
      disks
      +
      This is an optional listing of instructions for disks + participating in the backup (if omitted, all disks + participate, and libvirt attempts to generate filenames by + appending the current timestamp as a suffix). When provided on + input, disks omitted from the list do not participate in the + backup. On output, the list is present but contains only the + disks participating in the backup job. This element has a + list of disk sub-elements, describing anywhere + from one to all of the disks associated with the domain. +
      +
      disk
      +
      This sub-element describes the checkpoint properties of + a specific disk. The attribute name is + mandatory, and must match either the <target + dev=3D'name'/> or an unambiguous <source + file=3D'name'/> of one of + the disk + devices specified for the domain at the time of the + checkpoint. The optional attribute type can + be file, block, + or network, similar to a disk declaration for + a domain, controls what additional sub-elements are needed + to describe the destination (such as protocol + for a network destination). In push mode backups, the + primary sub-element is target; in pull mode, + the primary sub-element is scratch; but + either way, the primary sub-element describes the file + name to be used during the backup operation, similar to + the source sub-element of a domain disk. In + push mode, an optional sub-element driver can + also be used to specify a destination format different + from qcow2. +
      +
      +
      +
      + +

      Examples

      + +

      Using this XML to create a checkpoint of just vda on a qemu + domain with two disks and a prior checkpoint:

      + 
      +<domaincheckpoint>
+  <description>Completion of updates after OS install</descriptio=
n>
+  <disks>
+    <disk name=3D'vda' checkpoint=3D'bitmap'/>
+    <disk name=3D'vdb' checkpoint=3D'no'/>
+  </disks>
+</domaincheckpoint>
      + +

      will result in XML similar to this from + virDomainCheckpointGetXMLDesc():

      + 
      +<domaincheckpoint>
+  <name>1525889631</name>
+  <description>Completion of updates after OS install</descriptio=
n>
+  <creationTime>1525889631</creationTime>
+  <parent>
+    <name>1525111885</name>
+  </parent>
+  <disks>
+    <disk name=3D'vda' checkpoint=3D'bitmap' bitmap=3D'1525889631'/>
+    <disk name=3D'vdb' checkpoint=3D'no'/>
+  </disks>
+  <domain type=3D'qemu'>
+    <name>fedora</name>
+    <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
+    <memory>1048576</memory>
+    ...
+    <devices>
+      <disk type=3D'file' device=3D'disk'>
+        <driver name=3D'qemu' type=3D'qcow2'/>
+        <source file=3D'/path/to/file1'/>
+        <target dev=3D'vda' bus=3D'virtio'/>
+      </disk>
+      <disk type=3D'file' device=3D'disk' snapshot=3D'external'>
+        <driver name=3D'qemu' type=3D'raw'/>
+        <source file=3D'/path/to/file2'/>
+        <target dev=3D'vdb' bus=3D'virtio'/>
+      </disk>
+      ...
+    </devices>
+  </domain>
+</domaincheckpoint>
      + +

      With that checkpoint created, the qcow2 image is now tracking + all changes that occur in the image since the checkpoint via + the persistent bitmap named 1525889631. Now, we + can make a subsequent call + to virDomainBackupBegin() to perform an incremental + backup of just this data, using the following XML to start a + pull model NBD export of the vda disk: +

      + 
      +<domainbackup mode=3D"pull">
+  <incremental>1525889631</incremental>
+  <server transport=3D"unix" socket=3D"/path/to/server"/>
+  <disks/>
+    <disk name=3D'vda' type=3D'file'>
+      <scratch file=3D'/path/to/file1.scratch'/>
+    </disk>
+  </disks/>
+</domainbackup>
+
      + + diff --git a/docs/index.html.in b/docs/index.html.in index 1f9f448399..6c5d3a6dc3 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -68,7 +68,8 @@ domain capabilities, node devices, secrets, - snapshots
      • + snapshots, + backups and checkpoints
      Wiki
      Read further community contributed content
      diff --git a/docs/schemas/domainbackup.rng b/docs/schemas/domainbackup.rng new file mode 100644 index 0000000000..edc68a37cf --- /dev/null +++ b/docs/schemas/domainbackup.rng @@ -0,0 +1,185 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + push + + + + + + + pull + + + + + + + + tcp + + + + + + + + + + + + + + + + + + unix + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + file + + + + + + + + + + + + + + + + disk + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + file + + + + + + + + + + + + + disk + + + + + + + + + + + + + + + + + diff --git a/docs/schemas/domaincheckpoint.rng b/docs/schemas/domaincheckpo= int.rng new file mode 100644 index 0000000000..d8dfda9f1c --- /dev/null +++ b/docs/schemas/domaincheckpoint.rng @@ -0,0 +1,94 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + no + + + + + bitmap + + + + + + + + + + + + + + + + + + diff --git a/libvirt.spec.in b/libvirt.spec.in index 90daefe6f1..5c30a45f62 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -1834,7 +1834,9 @@ exit 0 %{_datadir}/libvirt/schemas/capability.rng %{_datadir}/libvirt/schemas/cputypes.rng %{_datadir}/libvirt/schemas/domain.rng +%{_datadir}/libvirt/schemas/domainbackup.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 b28e40f7f7..65a48ed960 100644 --- a/mingw-libvirt.spec.in +++ b/mingw-libvirt.spec.in @@ -240,7 +240,9 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-gue= sts.sh %{mingw32_datadir}/libvirt/schemas/capability.rng %{mingw32_datadir}/libvirt/schemas/cputypes.rng %{mingw32_datadir}/libvirt/schemas/domain.rng +%{mingw32_datadir}/libvirt/schemas/domainbackup.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 @@ -327,7 +329,9 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-gue= sts.sh %{mingw64_datadir}/libvirt/schemas/capability.rng %{mingw64_datadir}/libvirt/schemas/cputypes.rng %{mingw64_datadir}/libvirt/schemas/domain.rng +%{mingw64_datadir}/libvirt/schemas/domainbackup.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 d7ec7e3a6f..9ba6f50118 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with automake to produce Makefile.in -## Copyright (C) 2005-2015 Red Hat, Inc. +## Copyright (C) 2005-2018 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 @@ -92,7 +92,11 @@ EXTRA_DIST =3D \ capabilityschemadata \ commanddata \ cputestdata \ + domainbackupxml2xmlin \ + domainbackupxml2xmlout \ domaincapsschemadata \ + domaincheckpointxml2xmlin \ + domaincheckpointxml2xmlout \ domainconfdata \ domainschemadata \ domainsnapshotxml2xmlin \ diff --git a/tests/domainbackupxml2xmlin/backup-pull.xml b/tests/domainback= upxml2xmlin/backup-pull.xml new file mode 100644 index 0000000000..2ce5cd6711 --- /dev/null +++ b/tests/domainbackupxml2xmlin/backup-pull.xml @@ -0,0 +1,9 @@ + + 1525889631 + + + + + + + diff --git a/tests/domainbackupxml2xmlin/backup-push.xml b/tests/domainback= upxml2xmlin/backup-push.xml new file mode 100644 index 0000000000..1b7d3061fd --- /dev/null +++ b/tests/domainbackupxml2xmlin/backup-push.xml @@ -0,0 +1,9 @@ + + 1525889631 + + + + + + + diff --git a/tests/domainbackupxml2xmlin/empty.xml b/tests/domainbackupxml2= xmlin/empty.xml new file mode 100644 index 0000000000..7ed511f97b --- /dev/null +++ b/tests/domainbackupxml2xmlin/empty.xml @@ -0,0 +1 @@ + diff --git a/tests/domainbackupxml2xmlout/backup-pull.xml b/tests/domainbac= kupxml2xmlout/backup-pull.xml new file mode 100644 index 0000000000..2ce5cd6711 --- /dev/null +++ b/tests/domainbackupxml2xmlout/backup-pull.xml @@ -0,0 +1,9 @@ + + 1525889631 + + + + + + + diff --git a/tests/domainbackupxml2xmlout/backup-push.xml b/tests/domainbac= kupxml2xmlout/backup-push.xml new file mode 100644 index 0000000000..1b7d3061fd --- /dev/null +++ b/tests/domainbackupxml2xmlout/backup-push.xml @@ -0,0 +1,9 @@ + + 1525889631 + + + + + + + diff --git a/tests/domainbackupxml2xmlout/empty.xml b/tests/domainbackupxml= 2xmlout/empty.xml new file mode 100644 index 0000000000..13600fbb1c --- /dev/null +++ b/tests/domainbackupxml2xmlout/empty.xml @@ -0,0 +1,7 @@ + + + + + + + diff --git a/tests/domaincheckpointxml2xmlin/empty.xml b/tests/domaincheckp= ointxml2xmlin/empty.xml new file mode 100644 index 0000000000..dc36449142 --- /dev/null +++ b/tests/domaincheckpointxml2xmlin/empty.xml @@ -0,0 +1 @@ + diff --git a/tests/domaincheckpointxml2xmlin/sample.xml b/tests/domaincheck= pointxml2xmlin/sample.xml new file mode 100644 index 0000000000..70ed964e1e --- /dev/null +++ b/tests/domaincheckpointxml2xmlin/sample.xml @@ -0,0 +1,7 @@ + + Completion of updates after OS install + + + + + diff --git a/tests/domaincheckpointxml2xmlout/empty.xml b/tests/domaincheck= pointxml2xmlout/empty.xml new file mode 100644 index 0000000000..a26c7caab0 --- /dev/null +++ b/tests/domaincheckpointxml2xmlout/empty.xml @@ -0,0 +1,10 @@ + + 1525889631 + 1525889631 + + + + + 9d37b878-a7cc-9f9a-b78f-49b3abad25a8 + + diff --git a/tests/domaincheckpointxml2xmlout/sample.xml b/tests/domainchec= kpointxml2xmlout/sample.xml new file mode 100644 index 0000000000..559b29c8c1 --- /dev/null +++ b/tests/domaincheckpointxml2xmlout/sample.xml @@ -0,0 +1,16 @@ + + 1525889631 + Completion of updates after OS install + 1525889631 + + 1525111885 + + + + + + + fedora + 93a5c045-6457-2c09-e56c-927cdf34e178 + + diff --git a/tests/virschematest.c b/tests/virschematest.c index 7dda14e336..768182b4e4 100644 --- a/tests/virschematest.c +++ b/tests/virschematest.c @@ -221,7 +221,11 @@ mymain(void) "lxcxml2xmloutdata", "bhyvexml2argvdata", "genericxml2xmli= ndata", "genericxml2xmloutdata", "xlconfigdata", "libxlxml2domconf= igdata", "qemuhotplugtestdomains"); + DO_TEST_DIR("domainbackup.rng", "domainbackupxml2xmlin", + "domainbackupxml2xmlout"); DO_TEST_DIR("domaincaps.rng", "domaincapsschemadata"); + DO_TEST_DIR("domaincheckpoint.rng", "domaincheckpointxml2xmlin", + "domaincheckpointxml2xmlout"); DO_TEST_DIR("domainsnapshot.rng", "domainsnapshotxml2xmlin", "domainsnapshotxml2xmlout"); DO_TEST_DIR("interface.rng", "interfaceschemadata"); --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1539321050120502.89256533631965; Thu, 11 Oct 2018 22:10:50 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id B1D3211532; Fri, 12 Oct 2018 05:10:46 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 677A88CCF0; Fri, 12 Oct 2018 05:10:46 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 0D29E4CAAE; Fri, 12 Oct 2018 05:10:46 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5AinH007076 for ; Fri, 12 Oct 2018 01:10:44 -0400 Received: by smtp.corp.redhat.com (Postfix) id 5C45911A0EF; Fri, 12 Oct 2018 05:10:44 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id E838711A098; Fri, 12 Oct 2018 05:10:42 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:08 -0500 Message-Id: <20181012051011.1398546-7-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 6/9] backup: Introduce virDomainCheckpoint APIs X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.26]); Fri, 12 Oct 2018 05:10:48 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" 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. The full list of new API: virDomainCheckpointCreateXML; virDomainCheckpointCurrent; virDomainCheckpointDelete; virDomainCheckpointFree; virDomainCheckpointGetConnect; virDomainCheckpointGetDomain; virDomainCheckpointGetParent; virDomainCheckpointGetXMLDesc; virDomainCheckpointHasMetadata; virDomainCheckpointIsCurrent; virDomainCheckpointListChildren; virDomainCheckpointLookupByName; virDomainCheckpointRef; virDomainHasCurrentCheckpoint; virDomainListCheckpoints; virDomainCheckpointGetName; Signed-off-by: Eric Blake --- include/libvirt/libvirt-domain-checkpoint.h | 156 +++++ include/libvirt/libvirt.h | 5 +- src/driver-hypervisor.h | 60 +- 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 | 723 ++++++++++++++++++++ src/libvirt_public.syms | 20 + 12 files changed, 972 insertions(+), 4 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..cfca8f4b7f --- /dev/null +++ b/include/libvirt/libvirt-domain-checkpoint.h @@ -0,0 +1,156 @@ +/* + * libvirt-domain-checkpoint.h + * Summary: APIs for management of domain checkpoints + * Description: Provides APIs for the management of domain checkpoints + * Author: Eric Blake + * + * Copyright (C) 2006-2018 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 + * . + */ + +#ifndef __VIR_LIBVIRT_DOMAIN_CHECKPOINT_H__ +# define __VIR_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 checkpoin= t); +virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpo= int); + +typedef enum { + VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE =3D (1 << 0), /* Restore or a= lter + metadata */ + VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT =3D (1 << 1), /* With redefin= e, make + checkpoint cur= rent */ + VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA =3D (1 << 2), /* Make checkpo= int without + remembering it= */ + /* TODO: VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE */ +} 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 =3D (1 << 0), /* Include sensitive= data */ + VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN =3D (1 << 1), /* Suppress + subelement */ + VIR_DOMAIN_CHECKPOINT_XML_SIZE =3D (1 << 2), /* Include dynamic + per- size */ +} virDomainCheckpointXMLFlags; + +/* Dump the XML of a checkpoint */ +char *virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/** + * virDomainCheckpointListFlags: + * + * Flags valid for virDomainListCheckpoints() and + * virDomainCheckpointListChildren(). 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 =3D (1 << 0), /* Filter by chec= kpoints + with no parents,= when + listing a domain= */ + VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS =3D (1 << 0), /* List all desce= ndants, + not just childre= n, when + listing a checkp= oint */ + + VIR_DOMAIN_CHECKPOINT_LIST_LEAVES =3D (1 << 1), /* Filter by chec= kpoints + with no children= */ + VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES =3D (1 << 2), /* Filter by chec= kpoints + that have childr= en */ + + VIR_DOMAIN_CHECKPOINT_LIST_METADATA =3D (1 << 3), /* Filter by chec= kpoints + which have metad= ata */ + VIR_DOMAIN_CHECKPOINT_LIST_NO_METADATA =3D (1 << 4), /* Filter by chec= kpoints + with no metadata= */ +} virDomainCheckpointListFlags; + +/* Get all checkpoint objects for this domain */ +int virDomainListCheckpoints(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags); + +/* Get all checkpoint object children for this checkpoint */ +int virDomainCheckpointListChildren(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags); + +/* Get a handle to a named checkpoint */ +virDomainCheckpointPtr virDomainCheckpointLookupByName(virDomainPtr domain, + const char *name, + unsigned int flags); + +/* Check whether a domain has a checkpoint which is currently used */ +int virDomainHasCurrentCheckpoint(virDomainPtr domain, unsigned int flags); + +/* Get a handle to the current checkpoint */ +virDomainCheckpointPtr virDomainCheckpointCurrent(virDomainPtr domain, + unsigned int flags); + +/* Get a handle to the parent checkpoint, if one exists */ +virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr= checkpoint, + unsigned int flags); + +/* Determine if a checkpoint is the current checkpoint of its domain. */ +int virDomainCheckpointIsCurrent(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/* Determine if checkpoint has metadata that would prevent domain deletion= . */ +int virDomainCheckpointHasMetadata(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/* Delete a checkpoint */ +typedef enum { + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN =3D (1 << 0), /* Also delet= e children */ + VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY =3D (1 << 1), /* Delete jus= t metadata */ + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY =3D (1 << 2), /* Delete jus= t children */ +} virDomainCheckpointDeleteFlags; + +int virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +int virDomainCheckpointRef(virDomainCheckpointPtr checkpoint); +int virDomainCheckpointFree(virDomainCheckpointPtr checkpoint); + +#endif /* __VIR_LIBVIRT_DOMAIN_CHECKPOINT_H__ */ diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h index 26887a40e7..4e7da0afc4 100644 --- a/include/libvirt/libvirt.h +++ b/include/libvirt/libvirt.h @@ -4,7 +4,7 @@ * Description: Provides the interfaces of the libvirt library to handle * virtualized domains * - * Copyright (C) 2005-2006, 2010-2014 Red Hat, Inc. + * Copyright (C) 2005-2006, 2010-2018 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 @@ -36,8 +36,7 @@ extern "C" { # include # include # include -typedef struct _virDomainCheckpoint virDomainCheckpoint; -typedef virDomainCheckpoint *virDomainCheckpointPtr; +# include # include # include # include diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h index eef31eb1f0..ee8a9a3e0e 100644 --- a/src/driver-hypervisor.h +++ b/src/driver-hypervisor.h @@ -1,7 +1,7 @@ /* * driver-hypervisor.h: entry points for hypervisor drivers * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2018 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 @@ -1321,6 +1321,53 @@ 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 +(*virDrvDomainListCheckpoints)(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointListChildren)(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags); + +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointLookupByName)(virDomainPtr domain, + const char *name, + unsigned int flags); + +typedef int +(*virDrvDomainHasCurrentCheckpoint)(virDomainPtr domain, + unsigned int flags); + +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointGetParent)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointCurrent)(virDomainPtr domain, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointIsCurrent)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointHasMetadata)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointDelete)(virDomainCheckpointPtr checkpoint, + unsigned int flags); typedef struct _virHypervisorDriver virHypervisorDriver; typedef virHypervisorDriver *virHypervisorDriverPtr; @@ -1572,6 +1619,17 @@ struct _virHypervisorDriver { virDrvConnectBaselineHypervisorCPU connectBaselineHypervisorCPU; virDrvNodeGetSEVInfo nodeGetSEVInfo; virDrvDomainGetLaunchSecurityInfo domainGetLaunchSecurityInfo; + virDrvDomainCheckpointCreateXML domainCheckpointCreateXML; + virDrvDomainCheckpointGetXMLDesc domainCheckpointGetXMLDesc; + virDrvDomainListCheckpoints domainListCheckpoints; + virDrvDomainCheckpointListChildren domainCheckpointListChildren; + virDrvDomainCheckpointLookupByName domainCheckpointLookupByName; + virDrvDomainHasCurrentCheckpoint domainHasCurrentCheckpoint; + virDrvDomainCheckpointGetParent domainCheckpointGetParent; + virDrvDomainCheckpointCurrent domainCheckpointCurrent; + virDrvDomainCheckpointIsCurrent domainCheckpointIsCurrent; + virDrvDomainCheckpointHasMetadata domainCheckpointHasMetadata; + virDrvDomainCheckpointDelete domainCheckpointDelete; }; diff --git a/docs/Makefile.am b/docs/Makefile.am index bd7bc1a431..88c1e83275 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -25,6 +25,7 @@ apihtml =3D \ apihtml_generated =3D \ html/libvirt-libvirt-common.html \ html/libvirt-libvirt-domain.html \ + html/libvirt-libvirt-domain-checkpoint.html \ html/libvirt-libvirt-domain-snapshot.html \ html/libvirt-libvirt-event.html \ html/libvirt-libvirt-host.html \ @@ -316,6 +317,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 \ @@ -332,6 +334,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 5e218a9ad0..471547cea7 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -26,6 +26,7 @@ debugsym =3D None included_files =3D { "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 definiti= ons", "libvirt-domain-snapshot.h": "header with general libvirt API definition= s", "libvirt-event.h": "header with general libvirt API definitions", "libvirt-host.h": "header with general libvirt API definitions", @@ -39,6 +40,7 @@ included_files =3D { "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 lib= virt 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 4914e7dbed..596bc1613d 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -97,6 +97,7 @@
      Reference manual for the C public API, split in common, domain, + domain c= heckpoint, domain sna= pshot, error, event, diff --git a/libvirt.spec.in b/libvirt.spec.in index 5c30a45f62..887d18990e 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -1894,6 +1894,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 65a48ed960..11237b8ab7 100644 --- a/mingw-libvirt.spec.in +++ b/mingw-libvirt.spec.in @@ -272,6 +272,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-gue= sts.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 @@ -361,6 +362,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-gue= sts.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 be2874487c..d246657188 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 33ff280d78..4ec1b78a46 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -175,6 +175,7 @@ DRIVER_SOURCES +=3D \ $(DATATYPES_SOURCES) \ libvirt.c libvirt_internal.h \ libvirt-domain.c \ + libvirt-domain-checkpoint.c \ libvirt-domain-snapshot.c \ libvirt-host.c \ libvirt-interface.c \ @@ -726,6 +727,7 @@ libvirt_setuid_rpc_client_la_SOURCES =3D \ 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-checkpoin= t.c new file mode 100644 index 0000000000..8a7b5b3c56 --- /dev/null +++ b/src/libvirt-domain-checkpoint.c @@ -0,0 +1,723 @@ +/* + * libvirt-domain-checkpoint.c: entry points for virDomainCheckpointPtr AP= Is + * + * Copyright (C) 2006-2014, 2018 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 + * . + */ + +#include + +#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 deallocat= ed + * as its lifetime will be the same as the checkpoint object. + */ +const char * +virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=3D%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=3D%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=3D%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 on a running @domain. + * Typically, it is more common to create a new checkpoint as part of + * kicking off a backup job with virDomainBackupBegin(); however, it + * is also possible to start a checkpoint without a backup. + * + * See Checkpoint XM= L + * for more details on @xmlDesc. In particular, some hypervisors may requi= re + * 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 + * discarded, rather than creating a new checkpoint. When redefining + * checkpoint metadata, the current checkpoint will not be altered + * unless the VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT flag is also + * present. It is an error to request the + * VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT flag without + * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE. + * + * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA, then + * the domain's disk images are modified according to @xmlDesc, but + * then the just-created checkpoint has its metadata deleted. 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=3D%s, flags=3D0x%x", xmlDesc, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn =3D domain->conn; + + virCheckNonNullArgGoto(xmlDesc, error); + virCheckReadOnlyGoto(conn->flags, error); + + VIR_REQUIRE_FLAG_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT, + VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, + error); + + VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, + VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA, + error); + + if (conn->driver->domainCheckpointCreateXML) { + virDomainCheckpointPtr ret; + ret =3D conn->driver->domainCheckpointCreateXML(domain, xmlDesc, f= lags); + 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 snapshot 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 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 e= rror. + * the caller must free() the returned value. + */ +char * +virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + VIR_DEBUG("checkpoint=3D%p, flags=3D0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + conn =3D 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 =3D conn->driver->domainCheckpointGetXMLDesc(checkpoint, flags= ); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainListCheckpoints: + * @domain: a domain object + * @checkpoints: pointer to variable to store the array containing checkpo= int + * objects, 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 alloca= te + * an array to store those objects. + * + * 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, where each group contains bits that describe mutually exclusive + * attributes of a checkpoint, and where all bits within a group describe + * all possible checkpoints. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a 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 th= at + * have no further children (a leaf checkpoint). + * + * The next group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_METADATA and + * VIR_DOMAIN_CHECKPOINT_LIST_NO_METADATA, for filtering checkpoints based= on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * Returns the number of domain checkpoints found or -1 and sets @checkpoi= nts + * to NULL in case of error. On success, the array stored into @checkpoin= ts + * 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 +virDomainListCheckpoints(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "checkpoints=3D%p, flags=3D0x%x", checkpoints= , flags); + + virResetLastError(); + + if (checkpoints) + *checkpoints =3D NULL; + + virCheckDomainReturn(domain, -1); + conn =3D domain->conn; + + if (conn->driver->domainListCheckpoints) { + int ret =3D conn->driver->domainListCheckpoints(domain, checkpoint= s, + flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointListChildren: + * @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. + * + * By default, this command covers only direct children; it is also possib= le + * to expand things to cover all descendants, when @flags includes + * VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS. Also, some filters are provide= d in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a snapshot, and where all bits within a group describe + * all possible snapshots. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a 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 th= at + * have no further children (a leaf checkpoint). + * + * The next group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_METADATA and + * VIR_DOMAIN_CHECKPOINT_LIST_NO_METADATA, for filtering checkpoints based= on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * 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 inclu= ded + * in the return count, to make iteration easier. The caller is responsib= le + * for calling virDomainCheckpointFree() on each array element, then calli= ng + * free() on @children. + */ +int +virDomainCheckpointListChildren(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=3D%p, children=3D%p, flags=3D0x%x", + checkpoint, children, flags); + + virResetLastError(); + + if (children) + *children =3D NULL; + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn =3D checkpoint->domain->conn; + + if (conn->driver->domainCheckpointListChildren) { + int ret =3D conn->driver->domainCheckpointListChildren(checkpoint, + children, fla= gs); + 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=3D%s, flags=3D0x%x", name, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn =3D domain->conn; + + virCheckNonNullArgGoto(name, error); + + if (conn->driver->domainCheckpointLookupByName) { + virDomainCheckpointPtr dom; + dom =3D conn->driver->domainCheckpointLookupByName(domain, name, f= lags); + if (!dom) + goto error; + return dom; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainHasCurrentCheckpoint: + * @domain: pointer to the domain object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Determine if the domain has a current checkpoint. + * + * Returns 1 if such checkpoint exists, 0 if it doesn't, -1 on error. + */ +int +virDomainHasCurrentCheckpoint(virDomainPtr domain, unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "flags=3D0x%x", flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn =3D domain->conn; + + if (conn->driver->domainHasCurrentCheckpoint) { + int ret =3D conn->driver->domainHasCurrentCheckpoint(domain, flags= ); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointCurrent: + * @domain: a domain object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Get the current checkpoint for a domain, 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 + * current domain checkpoint cannot be found, then the + * VIR_ERR_NO_DOMAIN_CHECKPOINT error is raised. + */ +virDomainCheckpointPtr +virDomainCheckpointCurrent(virDomainPtr domain, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "flags=3D0x%x", flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn =3D domain->conn; + + if (conn->driver->domainCheckpointCurrent) { + virDomainCheckpointPtr snap; + snap =3D conn->driver->domainCheckpointCurrent(domain, flags); + if (!snap) + goto error; + return snap; + } + + 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_CHEC= KPOINT + * error is raised. + */ +virDomainCheckpointPtr +virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=3D%p, flags=3D0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + conn =3D checkpoint->domain->conn; + + if (conn->driver->domainCheckpointGetParent) { + virDomainCheckpointPtr snap; + snap =3D conn->driver->domainCheckpointGetParent(checkpoint, flags= ); + if (!snap) + goto error; + return snap; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * 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 virDomainHasCurrentCheckpoint(). + * + * Returns 1 if current, 0 if not current, or -1 on error. + */ +int +virDomainCheckpointIsCurrent(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=3D%p, flags=3D0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn =3D checkpoint->domain->conn; + + if (conn->driver->domainCheckpointIsCurrent) { + int ret; + ret =3D conn->driver->domainCheckpointIsCurrent(checkpoint, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointHasMetadata: + * @checkpoint: a checkpoint object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Determine if the given checkpoint is associated with libvirt metadata + * that would prevent the deletion of the domain. + * + * Returns 1 if the checkpoint has metadata, 0 if the checkpoint exists wi= thout + * help from libvirt, or -1 on error. + */ +int +virDomainCheckpointHasMetadata(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=3D%p, flags=3D0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn =3D checkpoint->domain->conn; + + if (conn->driver->domainCheckpointHasMetadata) { + int ret; + ret =3D conn->driver->domainCheckpointHasMetadata(checkpoint, flag= s); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointDelete: + * @checkpoint: the checkpoint to remove + * @flags: not used yet, pass 0 + * @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 the current checkpoint, the parent + * checkpoint becomes the new current checkpoint. + * + * 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=3D%p, flags=3D0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn =3D 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 =3D 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=3D%p, refs=3D%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 modifi= ed. + * 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=3D%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + + virObjectUnref(checkpoint); + return 0; +} diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms index d4cdbd8b32..fb58b95344 100644 --- a/src/libvirt_public.syms +++ b/src/libvirt_public.syms @@ -809,4 +809,24 @@ LIBVIRT_4.5.0 { virNWFilterBindingGetFilterName; } LIBVIRT_4.4.0; +LIBVIRT_4.9.0 { + global: + virDomainCheckpointCreateXML; + virDomainCheckpointCurrent; + virDomainCheckpointDelete; + virDomainCheckpointFree; + virDomainCheckpointGetConnect; + virDomainCheckpointGetDomain; + virDomainCheckpointGetName; + virDomainCheckpointGetParent; + virDomainCheckpointGetXMLDesc; + virDomainCheckpointHasMetadata; + virDomainCheckpointIsCurrent; + virDomainCheckpointListChildren; + virDomainCheckpointLookupByName; + virDomainCheckpointRef; + virDomainHasCurrentCheckpoint; + virDomainListCheckpoints; +} LIBVIRT_4.5.0; + # .... define new API here using predicted next version number .... --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1539321050504914.6552327647805; Thu, 11 Oct 2018 22:10:50 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 9700B81107; Fri, 12 Oct 2018 05:10:48 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 57C9C8CCFA; Fri, 12 Oct 2018 05:10:48 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id ECC8D18005B2; Fri, 12 Oct 2018 05:10:47 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5Ajwc007089 for ; Fri, 12 Oct 2018 01:10:45 -0400 Received: by smtp.corp.redhat.com (Postfix) id D62F811A105; Fri, 12 Oct 2018 05:10:45 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9BB1F11A098; Fri, 12 Oct 2018 05:10:44 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:09 -0500 Message-Id: <20181012051011.1398546-8-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 7/9] backup: Introduce virDomainBackup APIs X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.28]); Fri, 12 Oct 2018 05:10:49 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" Introduce a few more new public APIs related to incremental backups. This builds on the previous notion of a checkpoint (without an existing checkpoint, the new API is a full backup, differing only from virDomainCopy in the point of time chosen); and also allows creation of a new checkpoint at the same time as starting the backup (after all, an incremental backup is only useful if it covers the state since the previous backup). It also enhances event reporting for signaling when a push model backup completes (where the hypervisor creates the backup); note that the pull model does not have an event (starting the backup lets a third party access the data, and only the third party knows when it is finished). The full list of new API: virDomainBackupBegin; virDomainBackupEnd; virDomainBackupGetXMLDesc; Signed-off-by: Eric Blake --- include/libvirt/libvirt-domain-checkpoint.h | 21 ++ include/libvirt/libvirt-domain.h | 14 +- src/driver-hypervisor.h | 14 ++ src/libvirt-domain-checkpoint.c | 213 ++++++++++++++++++++ src/libvirt-domain.c | 8 +- src/libvirt_public.syms | 3 + tools/virsh-domain.c | 3 +- 7 files changed, 272 insertions(+), 4 deletions(-) diff --git a/include/libvirt/libvirt-domain-checkpoint.h b/include/libvirt/= libvirt-domain-checkpoint.h index cfca8f4b7f..0631a082b3 100644 --- a/include/libvirt/libvirt-domain-checkpoint.h +++ b/include/libvirt/libvirt-domain-checkpoint.h @@ -153,4 +153,25 @@ int virDomainCheckpointDelete(virDomainCheckpointPtr c= heckpoint, int virDomainCheckpointRef(virDomainCheckpointPtr checkpoint); int virDomainCheckpointFree(virDomainCheckpointPtr checkpoint); +typedef enum { + VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA =3D (1 << 0), /* Make checkpoint w= ithout + remembering it */ + /* TODO: VIR_DOMAIN_BACKUP_BEGIN_QUIESCE */ +} virDomainBackupBeginFlags; + +/* Begin an incremental backup job, possibly creating a checkpoint. */ +int virDomainBackupBegin(virDomainPtr domain, const char *diskXml, + const char *checkpointXml, unsigned int flags); + +/* Learn about an ongoing backup job. */ +char *virDomainBackupGetXMLDesc(virDomainPtr domain, int id, + unsigned int flags); + +typedef enum { + VIR_DOMAIN_BACKUP_END_ABORT =3D (1 << 0), /* Abandon a push model back= up */ +} virDomainBackupEndFlags; + +/* Complete (or abort) an incremental backup job. */ +int virDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags); + #endif /* __VIR_LIBVIRT_DOMAIN_CHECKPOINT_H__ */ diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-dom= ain.h index fdd2d6b8ea..11692e6ae1 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -4,7 +4,7 @@ * Description: Provides APIs for the management of domains * Author: Daniel Veillard * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2018 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 @@ -3168,6 +3168,7 @@ typedef enum { VIR_DOMAIN_JOB_OPERATION_SNAPSHOT =3D 6, VIR_DOMAIN_JOB_OPERATION_SNAPSHOT_REVERT =3D 7, VIR_DOMAIN_JOB_OPERATION_DUMP =3D 8, + VIR_DOMAIN_JOB_OPERATION_BACKUP =3D 9, # ifdef VIR_ENUM_SENTINELS VIR_DOMAIN_JOB_OPERATION_LAST @@ -3183,6 +3184,14 @@ typedef enum { */ # define VIR_DOMAIN_JOB_OPERATION "operation" +/** + * VIR_DOMAIN_JOB_ID: + * + * virDomainGetJobStats field: the id of the job (so far, only for jobs + * started by virDomainBackupBegin()), as VIR_TYPED_PARAM_INT. + */ +# define VIR_DOMAIN_JOB_ID "id" + /** * VIR_DOMAIN_JOB_TIME_ELAPSED: * @@ -3997,7 +4006,8 @@ typedef void (*virConnectDomainEventMigrationIteratio= nCallback)(virConnectPtr co * @nparams: size of the params array * @opaque: application specific data * - * This callback occurs when a job (such as migration) running on the doma= in + * This callback occurs when a job (such as migration or push-model + * virDomainBackupBegin()) running on the domain * is completed. The params array will contain statistics of the just comp= leted * job as virDomainGetJobStats would return. The callback must not free @p= arams * (the array will be freed once the callback finishes). diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h index ee8a9a3e0e..2ae0b381a9 100644 --- a/src/driver-hypervisor.h +++ b/src/driver-hypervisor.h @@ -1369,6 +1369,17 @@ typedef int (*virDrvDomainCheckpointDelete)(virDomainCheckpointPtr checkpoint, unsigned int flags); +typedef int +(*virDrvDomainBackupBegin)(virDomainPtr domain, const char *diskXml, + const char *checkpointXml, unsigned int flags); + +typedef char * +(*virDrvDomainBackupGetXMLDesc)(virDomainPtr domain, int id, + unsigned int flags); + +typedef int +(*virDrvDomainBackupEnd)(virDomainPtr domain, int id, unsigned int flags); + typedef struct _virHypervisorDriver virHypervisorDriver; typedef virHypervisorDriver *virHypervisorDriverPtr; @@ -1630,6 +1641,9 @@ struct _virHypervisorDriver { virDrvDomainCheckpointIsCurrent domainCheckpointIsCurrent; virDrvDomainCheckpointHasMetadata domainCheckpointHasMetadata; virDrvDomainCheckpointDelete domainCheckpointDelete; + virDrvDomainBackupBegin domainBackupBegin; + virDrvDomainBackupGetXMLDesc domainBackupGetXMLDesc; + virDrvDomainBackupEnd domainBackupEnd; }; diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoin= t.c index 8a7b5b3c56..dd1dd82123 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -721,3 +721,216 @@ virDomainCheckpointFree(virDomainCheckpointPtr checkp= oint) virObjectUnref(checkpoint); return 0; } + + +/** + * virDomainBackupBegin: + * @domain: a domain object + * @diskXml: description of storage to utilize and expose during + * the backup, or NULL + * @checkpointXml: description of a checkpoint to create, or NULL + * @flags: bitwise-OR of supported virDomainBackupBeginFlags + * + * Start a point-in-time backup job for the specified disks of a + * running domain. + * + * A backup job is mutually exclusive with domain migration + * (particularly when the job sets up an NBD export, since it is not + * possible to tell any NBD clients about a server migrating between + * hosts). For now, backup jobs are also mutually exclusive with any + * other block job on the same device, although this restriction may + * be lifted in a future release. Progress of the backup job can be + * tracked via virDomainGetJobStats(). The job remains active until a + * subsequent call to virDomainBackupEnd(), even if it no longer has + * anything to copy. + * + * This API differs from virDomainBlockCopy() in that it can grab the + * state of more than one disk in parallel, and the state is captured + * as of the start of the job, rather than the end. + * + * There are two fundamental backup approaches. The first, called a + * push model, instructs the hypervisor to copy the state of the guest + * disk to the designated storage destination (which may be on the + * local file system or a network device); in this mode, the + * hypervisor writes the content of the guest disk to the destination, + * then emits VIR_DOMAIN_EVENT_ID_JOB_COMPLETED when the backup is + * either complete or failed (the backup image is invalid if the job + * is ended prior to the event being emitted). The second, called a + * pull model, instructs the hypervisor to expose the state of the + * guest disk over an NBD export; a third-party client can then + * connect to this export, and read whichever portions of the disk it + * desires. In this mode, there is no event; libvirt has to be + * informed when the third-party NBD client is done and the backup + * resources can be released. + * + * The @diskXml parameter is optional but usually provided, and + * contains details about the backup, including which backup mode to + * use, whether the backup is incremental from a previous checkpoint, + * which disks participate in the backup, the destination for a push + * model backup, and the temporary storage and NBD server details for + * a pull model backup. If omitted, the backup attempts to default to + * a push mode full backup of all disks, where libvirt generates a + * filename for each disk by appending a suffix of a timestamp in + * seconds since the Epoch. virDomainBackupGetXMLDesc() can be called + * to learn actual values selected. For more information, see + * formatcheckpoint.html#BackupAttributes. + * + * The @checkpointXml parameter is optional; if non-NULL, then libvirt + * behaves as if virDomainCheckpointCreateXML() were called with + * @checkpointXml and the flag VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA + * forwarded appropriately, atomically covering the same guest state + * that will be part of the backup. The creation of a new checkpoint + * allows for future incremental backups. Note that some hypervisors + * may require a particular disk format, such as qcow2, in order to + * take advantage of checkpoints, while allowing arbitrary formats + * if checkpoints are not involved. + * + * Returns a non-negative job id on success, or negative on failure. + * This operation returns quickly, such that a user can choose to + * start a backup job between virDomainFSFreeze() and + * virDomainFSThaw() in order to create the backup while guest I/O is + * quiesced. + */ +/* FIXME: Do we need a specific API for listing all current backup + * jobs (which, at the moment, is at most one job), or is it better to + * refactor other existing job APIs in libvirt-domain.c to have job-id + * counterparts along with a generic listing of all jobs (with flags + * for filtering to specific job types)? + */ +int +virDomainBackupBegin(virDomainPtr domain, const char *diskXml, + const char *checkpointXml, unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "diskXml=3D%s, checkpointXml=3D%s, flags=3D0x= %x", + NULLSTR(diskXml), NULLSTR(checkpointXml), flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn =3D domain->conn; + + virCheckReadOnlyGoto(conn->flags, error); + if (flags & VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA) + virCheckNonNullArgGoto(checkpointXml, error); + + if (conn->driver->domainBackupBegin) { + int ret; + ret =3D conn->driver->domainBackupBegin(domain, diskXml, checkpoin= tXml, + flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainBackupGetXMLDesc: + * @domain: a domain object + * @id: the id of an active backup job previously started with + * virDomainBackupBegin() + * @flags: bitwise-OR of subset of virDomainXMLFlags + * + * In some cases, a user can start a backup job without supplying all + * details, and rely on libvirt to fill in the rest (for example, + * selecting the port used for an NBD export). This API can then be + * used to learn what default values were chosen. + * + * No security-sensitive data will be included unless @flags contains + * VIR_DOMAIN_XML_SECURE; this flag is rejected on read-only + * connections. For this API, @flags should not contain either + * VIR_DOMAIN_XML_INACTIVE or VIR_DOMAIN_XML_UPDATE_CPU. + * + * Returns a NUL-terminated UTF-8 encoded XML instance, or NULL in + * case of error. The caller must free() the returned value. + */ +char * +virDomainBackupGetXMLDesc(virDomainPtr domain, int id, unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "id=3D%d, flags=3D0x%x", id, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn =3D 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; + } + virCheckNonNegativeArgGoto(id, error); + + if (conn->driver->domainBackupGetXMLDesc) { + char *ret; + ret =3D conn->driver->domainBackupGetXMLDesc(domain, id, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainBackupEnd: + * @domain: a domain object + * @id: the id of an active backup job previously started with + * virDomainBackupBegin() + * @flags: bitwise-OR of supported virDomainBackupEndFlags + * + * Conclude a point-in-time backup job @id on the given domain. + * + * If the backup job uses the push model, but the event marking that + * all data has been copied has not yet been emitted, then the command + * fails unless @flags includes VIR_DOMAIN_BACKUP_END_ABORT. If the + * event has been issued, or if the backup uses the pull model, the + * flag has no effect. + * + * Returns 1 if the backup job completed successfully (the backup + * destination file in a push model is consistent), 0 if the job was + * aborted successfully (only when VIR_DOMAIN_BACKUP_END_ABORT is + * passed; the destination file is unusable), and -1 on failure. + */ +int +virDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "id=3D%d, flags=3D0x%x", id, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn =3D domain->conn; + + virCheckReadOnlyGoto(conn->flags, error); + virCheckNonNegativeArgGoto(id, error); + + if (conn->driver->domainBackupEnd) { + int ret; + ret =3D conn->driver->domainBackupEnd(domain, id, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 7690339521..002d214880 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -1,7 +1,7 @@ /* * libvirt-domain.c: entry points for virDomainPtr APIs * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2018 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 @@ -10261,6 +10261,12 @@ virDomainBlockRebase(virDomainPtr dom, const char = *disk, * over the destination format, the ability to copy to a destination that * is not a local file, and the possibility of additional tuning parameter= s. * + * The copy created by this API is not finalized until the job ends, + * and does not lend itself to incremental backups (beyond what + * VIR_DOMAIN_BLOCK_COPY_SHALLOW provides) nor to third-party control + * over the data being copied. For those features, use + * virDomainBackupBegin(). + * * Returns 0 if the operation has started, -1 on failure. */ int diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms index fb58b95344..61a5085dcb 100644 --- a/src/libvirt_public.syms +++ b/src/libvirt_public.syms @@ -811,6 +811,9 @@ LIBVIRT_4.5.0 { LIBVIRT_4.9.0 { global: + virDomainBackupBegin; + virDomainBackupEnd; + virDomainBackupGetXMLDesc; virDomainCheckpointCreateXML; virDomainCheckpointCurrent; virDomainCheckpointDelete; diff --git a/tools/virsh-domain.c b/tools/virsh-domain.c index 372bdb95d3..ba4a0f5310 100644 --- a/tools/virsh-domain.c +++ b/tools/virsh-domain.c @@ -6069,7 +6069,8 @@ VIR_ENUM_IMPL(virshDomainJobOperation, N_("Outgoing migration"), N_("Snapshot"), N_("Snapshot revert"), - N_("Dump")) + N_("Dump"), + N_("Backup")) static const char * virshDomainJobOperationToString(int op) --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 153932107124016.52155739361126; Thu, 11 Oct 2018 22:11:11 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 6F02D308213E; Fri, 12 Oct 2018 05:11:09 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D52798CCFA; Fri, 12 Oct 2018 05:11:08 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 2C014180BADC; Fri, 12 Oct 2018 05:11:08 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5AlXp007096 for ; Fri, 12 Oct 2018 01:10:47 -0400 Received: by smtp.corp.redhat.com (Postfix) id 5E3A8B19D4; Fri, 12 Oct 2018 05:10:47 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1F64711A1D3; Fri, 12 Oct 2018 05:10:45 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:10 -0500 Message-Id: <20181012051011.1398546-9-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 8/9] backup: Add new domain:checkpoint access control X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.42]); Fri, 12 Oct 2018 05:11:10 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" 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 --- src/access/viraccessperm.h | 8 +++++++- src/access/viraccessperm.c | 5 +++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/src/access/viraccessperm.h b/src/access/viraccessperm.h index 5ac5ff3377..c6fd31dcc0 100644 --- a/src/access/viraccessperm.h +++ b/src/access/viraccessperm.h @@ -1,7 +1,7 @@ /* * viraccessperm.h: access control permissions * - * Copyright (C) 2012-2014 Red Hat, Inc. + * Copyright (C) 2012-2018 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 @@ -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 d7cbb70b7b..5cb14d4cd8 100644 --- a/src/access/viraccessperm.c +++ b/src/access/viraccessperm.c @@ -1,7 +1,7 @@ /* * viraccessperm.c: access control permissions * - * Copyright (C) 2012-2014 Red Hat, Inc. + * Copyright (C) 2012-2018 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 @@ -38,7 +38,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", --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Mon Apr 29 05:56:55 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1539321078277466.3834124678949; Thu, 11 Oct 2018 22:11:18 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 6CAB5300170A; Fri, 12 Oct 2018 05:11:16 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2C3A1895B6; Fri, 12 Oct 2018 05:11:16 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id B4E564A46A; Fri, 12 Oct 2018 05:11:15 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9C5AnMD007109 for ; Fri, 12 Oct 2018 01:10:49 -0400 Received: by smtp.corp.redhat.com (Postfix) id 00F4911A0EF; Fri, 12 Oct 2018 05:10:49 +0000 (UTC) Received: from red.redhat.com (ovpn-121-240.rdu2.redhat.com [10.10.121.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9B553B19D4; Fri, 12 Oct 2018 05:10:47 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Fri, 12 Oct 2018 00:10:11 -0500 Message-Id: <20181012051011.1398546-10-eblake@redhat.com> In-Reply-To: <20181012051011.1398546-1-eblake@redhat.com> References: <20181012051011.1398546-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v2 9/9] backup: Implement backup APIs for remote driver X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.45]); Fri, 12 Oct 2018 05:11:17 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" The remote code generator had to be taught about the new virDomainCheckpointPtr type, at which point the remote driver code for backups can be generated. Signed-off-by: Eric Blake --- src/remote/remote_daemon_dispatch.c | 15 ++ src/remote/remote_driver.c | 33 +++- src/remote/remote_protocol.x | 240 +++++++++++++++++++++++++++- src/remote_protocol-structs | 129 +++++++++++++++ src/rpc/gendispatch.pl | 32 ++-- 5 files changed, 430 insertions(+), 19 deletions(-) diff --git a/src/remote/remote_daemon_dispatch.c b/src/remote/remote_daemon= _dispatch.c index e62ebfb596..09fda113a8 100644 --- a/src/remote/remote_daemon_dispatch.c +++ b/src/remote/remote_daemon_dispatch.c @@ -91,6 +91,7 @@ static virStorageVolPtr get_nonnull_storage_vol(virConnec= tPtr conn, remote_nonnu static virSecretPtr get_nonnull_secret(virConnectPtr conn, remote_nonnull_= secret secret); static virNWFilterPtr get_nonnull_nwfilter(virConnectPtr conn, remote_nonn= ull_nwfilter nwfilter); static virNWFilterBindingPtr get_nonnull_nwfilter_binding(virConnectPtr co= nn, remote_nonnull_nwfilter_binding binding); +static virDomainCheckpointPtr get_nonnull_domain_checkpoint(virDomainPtr d= om, 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 void make_nonnull_domain(remote_nonnull_domain *dom_dst, virDomainP= tr dom_src); @@ -102,6 +103,7 @@ static void make_nonnull_node_device(remote_nonnull_nod= e_device *dev_dst, virNod static void make_nonnull_secret(remote_nonnull_secret *secret_dst, virSecr= etPtr secret_src); static void make_nonnull_nwfilter(remote_nonnull_nwfilter *net_dst, virNWF= ilterPtr 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_checkpoin= t *checkpoint_dst, virDomainCheckpointPtr checkpoint_src); static void make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *s= napshot_dst, virDomainSnapshotPtr snapshot_src); static int @@ -7093,6 +7095,12 @@ get_nonnull_nwfilter_binding(virConnectPtr conn, rem= ote_nonnull_nwfilter_binding return virGetNWFilterBinding(conn, binding.portdev, binding.filtername= ); } +static virDomainCheckpointPtr +get_nonnull_domain_checkpoint(virDomainPtr dom, remote_nonnull_domain_chec= kpoint checkpoint) +{ + return virGetDomainCheckpoint(dom, checkpoint.name); +} + static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr dom, remote_nonnull_domain_snapsh= ot snapshot) { @@ -7172,6 +7180,13 @@ make_nonnull_nwfilter_binding(remote_nonnull_nwfilte= r_binding *binding_dst, virN ignore_value(VIR_STRDUP_QUIET(binding_dst->filtername, binding_src->fi= ltername)); } +static void +make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint *checkpoin= t_dst, virDomainCheckpointPtr checkpoint_src) +{ + ignore_value(VIR_STRDUP_QUIET(checkpoint_dst->name, checkpoint_src->na= me)); + make_nonnull_domain(&checkpoint_dst->dom, checkpoint_src->domain); +} + static void 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 3b43e219e5..9c3501cba3 100644 --- a/src/remote/remote_driver.c +++ b/src/remote/remote_driver.c @@ -2,7 +2,7 @@ * remote_driver.c: driver to provide access to libvirtd running * on a remote machine * - * Copyright (C) 2007-2015 Red Hat, Inc. + * Copyright (C) 2007-2018 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 @@ -147,6 +147,7 @@ static virStoragePoolPtr get_nonnull_storage_pool(virCo= nnectPtr 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 d= omain, remote_nonnull_domain_checkpoint checkpoint); static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr domai= n, remote_nonnull_domain_snapshot snapshot); static void make_nonnull_domain(remote_nonnull_domain *dom_dst, virDomainP= tr dom_src); static void make_nonnull_network(remote_nonnull_network *net_dst, virNetwo= rkPtr net_src); @@ -158,6 +159,7 @@ make_nonnull_node_device(remote_nonnull_node_device *de= v_dst, virNodeDevicePtr d static void make_nonnull_secret(remote_nonnull_secret *secret_dst, virSecr= etPtr secret_src); static void make_nonnull_nwfilter(remote_nonnull_nwfilter *nwfilter_dst, v= irNWFilterPtr 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_checkpoin= t *checkpoint_dst, virDomainCheckpointPtr checkpoint_src); static void make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *s= napshot_dst, virDomainSnapshotPtr snapshot_src); /*----------------------------------------------------------------------*/ @@ -8214,6 +8216,12 @@ get_nonnull_nwfilter_binding(virConnectPtr conn, rem= ote_nonnull_nwfilter_binding return virGetNWFilterBinding(conn, binding.portdev, binding.filtername= ); } +static virDomainCheckpointPtr +get_nonnull_domain_checkpoint(virDomainPtr domain, remote_nonnull_domain_c= heckpoint checkpoint) +{ + return virGetDomainCheckpoint(domain, checkpoint.name); +} + static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr domain, remote_nonnull_domain_sna= pshot snapshot) { @@ -8288,6 +8296,13 @@ make_nonnull_nwfilter_binding(remote_nonnull_nwfilte= r_binding *binding_dst, virN binding_dst->filtername =3D binding_src->filtername; } +static void +make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint *checkpoin= t_dst, virDomainCheckpointPtr checkpoint_src) +{ + checkpoint_dst->name =3D 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) { @@ -8536,7 +8551,21 @@ static virHypervisorDriver hypervisor_driver =3D { .connectCompareHypervisorCPU =3D remoteConnectCompareHypervisorCPU, /*= 4.4.0 */ .connectBaselineHypervisorCPU =3D remoteConnectBaselineHypervisorCPU, = /* 4.4.0 */ .nodeGetSEVInfo =3D remoteNodeGetSEVInfo, /* 4.5.0 */ - .domainGetLaunchSecurityInfo =3D remoteDomainGetLaunchSecurityInfo /* = 4.5.0 */ + .domainGetLaunchSecurityInfo =3D remoteDomainGetLaunchSecurityInfo, /*= 4.5.0 */ + .domainCheckpointCreateXML =3D remoteDomainCheckpointCreateXML, /* 4.9= .0 */ + .domainCheckpointGetXMLDesc =3D remoteDomainCheckpointGetXMLDesc, /* 4= .9.0 */ + .domainListCheckpoints =3D remoteDomainListCheckpoints, /* 4.9.0 */ + .domainCheckpointListChildren =3D remoteDomainCheckpointListChildren, = /* 4.9.0 */ + .domainCheckpointLookupByName =3D remoteDomainCheckpointLookupByName, = /* 4.9.0 */ + .domainHasCurrentCheckpoint =3D remoteDomainHasCurrentCheckpoint, /* 4= .9.0 */ + .domainCheckpointGetParent =3D remoteDomainCheckpointGetParent, /* 4.9= .0 */ + .domainCheckpointCurrent =3D remoteDomainCheckpointCurrent, /* 4.9.0 */ + .domainCheckpointIsCurrent =3D remoteDomainCheckpointIsCurrent, /* 4.9= .0 */ + .domainCheckpointHasMetadata =3D remoteDomainCheckpointHasMetadata, /*= 4.9.0 */ + .domainCheckpointDelete =3D remoteDomainCheckpointDelete, /* 4.9.0 */ + .domainBackupBegin =3D remoteDomainBackupBegin, /* 4.9.0 */ + .domainBackupGetXMLDesc =3D remoteDomainBackupGetXMLDesc, /* 4.9.0 */ + .domainBackupEnd =3D remoteDomainBackupEnd, /* 4.9.0 */ }; static virNetworkDriver network_driver =3D { diff --git a/src/remote/remote_protocol.x b/src/remote/remote_protocol.x index 28c8febabd..1e9632743a 100644 --- a/src/remote/remote_protocol.x +++ b/src/remote/remote_protocol.x @@ -3,7 +3,7 @@ * remote_internal driver and libvirtd. This protocol is * internal and may change at any time. * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2018 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 @@ -139,6 +139,9 @@ const REMOTE_AUTH_TYPE_LIST_MAX =3D 20; /* Upper limit on list of memory stats */ const REMOTE_DOMAIN_MEMORY_STATS_MAX =3D 1024; +/* Upper limit on lists of domain checkpoints. */ +const REMOTE_DOMAIN_CHECKPOINT_LIST_MAX =3D 16384; + /* Upper limit on lists of domain snapshots. */ const REMOTE_DOMAIN_SNAPSHOT_LIST_MAX =3D 16384; @@ -321,6 +324,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; @@ -3556,6 +3565,137 @@ struct remote_connect_list_all_nwfilter_bindings_re= t { /* insert@1 */ remote_nonnull_nwfilter_binding bindings; unsigned int ret; }; +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_checkpoints_args { + remote_nonnull_domain dom; + int need_results; + unsigned int flags; +}; + +struct remote_domain_list_checkpoints_ret { /* insert@1 */ + remote_nonnull_domain_checkpoint checkpoints; + int ret; +}; + +struct remote_domain_checkpoint_list_children_args { + remote_nonnull_domain_checkpoint checkpoint; + int need_results; + unsigned int flags; +}; + +struct remote_domain_checkpoint_list_children_ret { /* insert@1 */ + remote_nonnull_domain_checkpoint checkpoints; + 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_has_current_checkpoint_args { + remote_nonnull_domain dom; + unsigned int flags; +}; + +struct remote_domain_has_current_checkpoint_ret { + int result; +}; + +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_current_args { + remote_nonnull_domain dom; + unsigned int flags; +}; + +struct remote_domain_checkpoint_current_ret { + remote_nonnull_domain_checkpoint checkpoint; +}; + +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_has_metadata_args { + remote_nonnull_domain_checkpoint checkpoint; + unsigned int flags; +}; + +struct remote_domain_checkpoint_has_metadata_ret { + int metadata; +}; + +struct remote_domain_checkpoint_delete_args { + remote_nonnull_domain_checkpoint checkpoint; + unsigned int flags; +}; + +struct remote_domain_backup_begin_args { + remote_nonnull_domain dom; + remote_string disk_xml; + remote_string checkpoint_xml; + unsigned int flags; +}; + +struct remote_domain_backup_begin_ret { + int result; +}; + +struct remote_domain_backup_get_xml_desc_args { + remote_nonnull_domain dom; + int id; + unsigned int flags; +}; + +struct remote_domain_backup_get_xml_desc_ret { + remote_nonnull_string xml; +}; + +struct remote_domain_backup_end_args { + remote_nonnull_domain dom; + int id; + unsigned int flags; +}; + +struct remote_domain_backup_end_ret { + int retcode; +}; /*----- Protocol. -----*/ @@ -6312,5 +6452,101 @@ enum remote_procedure { * @acl: connect:search_nwfilter_bindings * @aclfilter: nwfilter_binding:getattr */ - REMOTE_PROC_CONNECT_LIST_ALL_NWFILTER_BINDINGS =3D 401 + REMOTE_PROC_CONNECT_LIST_ALL_NWFILTER_BINDINGS =3D 401, + + /** + * @generate: both + * @acl: domain:checkpoint + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_CREATE_XML =3D 402, + + /** + * @generate: both + * @acl: domain:read + * @acl: domain:read_secure:VIR_DOMAIN_CHECKPOINT_XML_SECURE + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_GET_XML_DESC =3D 403, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_LIST_CHECKPOINTS =3D 404, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_LIST_CHILDREN =3D 405, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_LOOKUP_BY_NAME =3D 406, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_HAS_CURRENT_CHECKPOINT =3D 407, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_CURRENT =3D 408, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_GET_PARENT =3D 409, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT =3D 410, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_HAS_METADATA =3D 411, + + /** + * @generate: both + * @acl: domain:checkpoint + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE =3D 412, + + /** + * @generate: both + * @acl: domain:checkpoint + * @acl: domain:block_read + */ + REMOTE_PROC_DOMAIN_BACKUP_BEGIN =3D 413, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + * @acl: domain:read_secure:VIR_DOMAIN_XML_SECURE + */ + REMOTE_PROC_DOMAIN_BACKUP_GET_XML_DESC =3D 414, + + /** + * @generate: both + * @acl: domain:checkpoint + */ + REMOTE_PROC_DOMAIN_BACKUP_END =3D 415 }; diff --git a/src/remote_protocol-structs b/src/remote_protocol-structs index 6343e14638..86c7c34cf5 100644 --- a/src/remote_protocol-structs +++ b/src/remote_protocol-structs @@ -46,6 +46,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; @@ -2966,6 +2970,117 @@ struct remote_connect_list_all_nwfilter_bindings_re= t { } bindings; u_int ret; }; +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_checkpoints_args { + remote_nonnull_domain dom; + int need_results; + u_int flags; +}; +struct remote_domain_list_checkpoints_ret { + struct { + u_int checkpoints_len; + remote_nonnull_domain_checkpoint * checkpoints_val; + } checkpoints; + int ret; +}; +struct remote_domain_checkpoint_list_children_args { + remote_nonnull_domain_checkpoint checkpoint; + int need_results; + u_int flags; +}; +struct remote_domain_checkpoint_list_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_has_current_checkpoint_args { + remote_nonnull_domain dom; + u_int flags; +}; +struct remote_domain_has_current_checkpoint_ret { + int result; +}; +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_current_args { + remote_nonnull_domain dom; + u_int flags; +}; +struct remote_domain_checkpoint_current_ret { + remote_nonnull_domain_checkpoint checkpoint; +}; +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_has_metadata_args { + remote_nonnull_domain_checkpoint checkpoint; + u_int flags; +}; +struct remote_domain_checkpoint_has_metadata_ret { + int metadata; +}; +struct remote_domain_checkpoint_delete_args { + remote_nonnull_domain_checkpoint checkpoint; + u_int flags; +}; +struct remote_domain_backup_begin_args { + remote_nonnull_domain dom; + remote_string disk_xml; + remote_string checkpoint_xml; + u_int flags; +}; +struct remote_domain_backup_begin_ret { + int result; +}; +struct remote_domain_backup_get_xml_desc_args { + remote_nonnull_domain dom; + int id; + u_int flags; +}; +struct remote_domain_backup_get_xml_desc_ret { + remote_nonnull_string xml; +}; +struct remote_domain_backup_end_args { + remote_nonnull_domain dom; + int id; + u_int flags; +}; +struct remote_domain_backup_end_ret { + int retcode; +}; enum remote_procedure { REMOTE_PROC_CONNECT_OPEN =3D 1, REMOTE_PROC_CONNECT_CLOSE =3D 2, @@ -3368,4 +3483,18 @@ enum remote_procedure { REMOTE_PROC_NWFILTER_BINDING_CREATE_XML =3D 399, REMOTE_PROC_NWFILTER_BINDING_DELETE =3D 400, REMOTE_PROC_CONNECT_LIST_ALL_NWFILTER_BINDINGS =3D 401, + REMOTE_PROC_DOMAIN_CHECKPOINT_CREATE_XML =3D 402, + REMOTE_PROC_DOMAIN_CHECKPOINT_GET_XML_DESC =3D 403, + REMOTE_PROC_DOMAIN_LIST_CHECKPOINTS =3D 404, + REMOTE_PROC_DOMAIN_CHECKPOINT_LIST_CHILDREN =3D 405, + REMOTE_PROC_DOMAIN_CHECKPOINT_LOOKUP_BY_NAME =3D 406, + REMOTE_PROC_DOMAIN_HAS_CURRENT_CHECKPOINT =3D 407, + REMOTE_PROC_DOMAIN_CHECKPOINT_CURRENT =3D 408, + REMOTE_PROC_DOMAIN_CHECKPOINT_GET_PARENT =3D 409, + REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT =3D 410, + REMOTE_PROC_DOMAIN_CHECKPOINT_HAS_METADATA =3D 411, + REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE =3D 412, + REMOTE_PROC_DOMAIN_BACKUP_BEGIN =3D 413, + REMOTE_PROC_DOMAIN_BACKUP_GET_XML_DESC =3D 414, + REMOTE_PROC_DOMAIN_BACKUP_END =3D 415, }; diff --git a/src/rpc/gendispatch.pl b/src/rpc/gendispatch.pl index 0c4648c0fb..348039af3d 100755 --- a/src/rpc/gendispatch.pl +++ b/src/rpc/gendispatch.pl @@ -1,6 +1,6 @@ #!/usr/bin/env perl # -# Copyright (C) 2010-2015 Red Hat, Inc. +# Copyright (C) 2010-2018 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 @@ -567,18 +567,20 @@ elsif ($mode eq "server") { push(@args_list, "$2"); push(@free_list, " virObjectUnref($2);"); - } elsif ($args_member =3D~ m/^remote_nonnull_domain_snapsh= ot (\S+);$/) { + } elsif ($args_member =3D~ m/^remote_nonnull_domain_(check= point|snapshot) (\S+);$/) { + my $type_name =3D name_to_TypeName($1); + push(@vars_list, "virDomainPtr dom =3D NULL"); - push(@vars_list, "virDomainSnapshotPtr snapshot =3D NU= LL"); + push(@vars_list, "virDomain${type_name}Ptr ${1} =3D NU= LL"); push(@getters_list, - " if (!(dom =3D get_nonnull_domain($conn, args= ->${1}.dom)))\n" . + " if (!(dom =3D get_nonnull_domain($conn, args= ->${2}.dom)))\n" . " goto cleanup;\n" . "\n" . - " if (!(snapshot =3D get_nonnull_domain_snapsh= ot(dom, args->${1})))\n" . + " if (!($1 =3D get_nonnull_domain_${1}(dom, ar= gs->$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 =3D~ m/^(?:(?:admin|remote)_string|r= emote_uuid) (\S+)<\S+>;/) { push(@args_list, $conn) if !@args_list; @@ -722,7 +724,7 @@ elsif ($mode eq "server") { if (!$modern_ret_as_list) { push(@ret_list, "ret->$3 =3D tmp.$3;"); } - } elsif ($ret_member =3D~ m/(?:admin|remote)_nonnull_(= secret|nwfilter|nwfilter_binding|node_device|interface|network|storage_vol|= storage_pool|domain_snapshot|domain|server|client) (\S+)<(\S+)>;/) { + } elsif ($ret_member =3D~ m/(?:admin|remote)_nonnull_(= secret|nwfilter|nwfilter_binding|node_device|interface|network|storage_vol|= storage_pool|domain_checkpoint|domain_snapshot|domain|server|client) (\S+)<= (\S+)>;/) { $modern_ret_struct_name =3D $1; $single_ret_list_error_msg_type =3D $1; $single_ret_list_name =3D $2; @@ -780,7 +782,7 @@ elsif ($mode eq "server") { $single_ret_var =3D $1; $single_ret_by_ref =3D 0; $single_ret_check =3D " =3D=3D NULL"; - } elsif ($ret_member =3D~ m/^remote_nonnull_(domain|networ= k|storage_pool|storage_vol|interface|node_device|secret|nwfilter|nwfilter_b= inding|domain_snapshot) (\S+);/) { + } elsif ($ret_member =3D~ m/^remote_nonnull_(domain|networ= k|storage_pool|storage_vol|interface|node_device|secret|nwfilter|nwfilter_b= inding|domain_checkpoint|domain_snapshot) (\S+);/) { my $type_name =3D name_to_TypeName($1); if ($call->{ProcName} eq "DomainCreateWithFlags") { @@ -1325,13 +1327,13 @@ elsif ($mode eq "client") { $priv_src =3D "dev->conn"; push(@args_list, "virNodeDevicePtr dev"); push(@setters_list, "args.name =3D dev->name;"); - } elsif ($args_member =3D~ m/^remote_nonnull_(domain|netwo= rk|storage_pool|storage_vol|interface|secret|nwfilter|nwfilter_binding|doma= in_snapshot) (\S+);/) { + } elsif ($args_member =3D~ m/^remote_nonnull_(domain|netwo= rk|storage_pool|storage_vol|interface|secret|nwfilter|nwfilter_binding|doma= in_checkpoint|domain_snapshot) (\S+);/) { my $name =3D $1; my $arg_name =3D $2; my $type_name =3D name_to_TypeName($name); if ($is_first_arg) { - if ($name eq "domain_snapshot") { + if ($name =3D~ m/^domain_.*/) { $priv_src =3D "$arg_name->domain->conn"; } else { $priv_src =3D "$arg_name->conn"; @@ -1518,7 +1520,7 @@ elsif ($mode eq "client") { } push(@ret_list, "memcpy(result->$3, ret.$3, sizeof= (result->$3));"); - } elsif ($ret_member =3D~ m/(?:admin|remote)_nonnull_(= secret|nwfilter|nwfilter_binding|node_device|interface|network|storage_vol|= storage_pool|domain_snapshot|domain|server|client) (\S+)<(\S+)>;/) { + } elsif ($ret_member =3D~ m/(?:admin|remote)_nonnull_(= secret|nwfilter|nwfilter_binding|node_device|interface|network|storage_vol|= storage_pool|domain_checkpoint|domain_snapshot|domain|server|client) (\S+)<= (\S+)>;/) { my $proc_name =3D name_to_TypeName($1); if ($structprefix eq "admin") { @@ -1571,7 +1573,7 @@ elsif ($mode eq "client") { push(@ret_list, "VIR_FREE(ret.$1);"); $single_ret_var =3D "char *rv =3D NULL"; $single_ret_type =3D "char *"; - } elsif ($ret_member =3D~ m/^remote_nonnull_(domain|networ= k|storage_pool|storage_vol|node_device|interface|secret|nwfilter|nwfilter_b= inding|domain_snapshot) (\S+);/) { + } elsif ($ret_member =3D~ m/^remote_nonnull_(domain|networ= k|storage_pool|storage_vol|node_device|interface|secret|nwfilter|nwfilter_b= inding|domain_checkpoint|domain_snapshot) (\S+);/) { my $name =3D $1; my $arg_name =3D $2; my $type_name =3D name_to_TypeName($name); @@ -1585,7 +1587,7 @@ elsif ($mode eq "client") { $single_ret_var =3D "int rv =3D -1"; $single_ret_type =3D "int"; } else { - if ($name eq "domain_snapshot") { + if ($name =3D~ m/^domain_.*/) { my $dom =3D "$priv_src"; $dom =3D~ s/->conn//; push(@ret_list, "rv =3D get_nonnull_$name($dom= , ret.$arg_name);"); @@ -1928,7 +1930,7 @@ elsif ($mode eq "client") { print " }\n"; print "\n"; } elsif ($modern_ret_as_list) { - if ($modern_ret_struct_name =3D~ m/domain_snapshot|client/) { + if ($modern_ret_struct_name =3D~ m/domain_checkpoint|domain_sn= apshot|client/) { $priv_src =3D~ s/->conn//; } print " if (result) {\n"; --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list