From nobody Fri Dec 19 19:02:58 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) client-ip=205.139.110.61; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1574804436; cv=none; d=zohomail.com; s=zohoarc; b=fsRBz7N9DDJu2GKYsQM6dMfjY9lclKqhuOksrH5A3I/cZyIYq05ZShQW6wfmRG5M96+wojChSL7h3ovrlUkmo/N8VxzExz+ao6v+gg/h2pNWd94tXlC/a7AX+lVFdh72upRg55LKDNp6ejIRM60ZUbJ/pYtdl1EYotUrPBoYsYs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1574804436; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=vmHK76rdIqQ4aD4JLAm79rN2oKN9v4EhZFhD3fdChbs=; b=dW1moeIGdiKPEAvyDAI3DTDrs5En7L8IpWfOkt2wzPQ+8z8fqLbkLaMdNb/SCjjWFF09oxTlQTnEsf7fF3FzNdm/01Xx/Xwfh2mxTJ/9vc7OVVksO2cYQ4yqteUDn6JzJF1XDSLTlUnu2KidUEpNJ7HU4xHS4sPUzP7A9BVkVf0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [205.139.110.61]) by mx.zohomail.com with SMTPS id 1574804436570923.8390144680245; Tue, 26 Nov 2019 13:40:36 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-100-ISlCGFu2Pn2wNBFK8UpruQ-1; Tue, 26 Nov 2019 16:40:32 -0500 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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id C2F37DBA7; Tue, 26 Nov 2019 21:40:27 +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 9AB4519C69; Tue, 26 Nov 2019 21:40:27 +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 5B1DE4E567; Tue, 26 Nov 2019 21:40:27 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id xAQLeEnb027826 for ; Tue, 26 Nov 2019 16:40:14 -0500 Received: by smtp.corp.redhat.com (Postfix) id 97F1A600CA; Tue, 26 Nov 2019 21:40:14 +0000 (UTC) Received: from angien.redhat.com (unknown [10.43.2.48]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1ECDB600C8 for ; Tue, 26 Nov 2019 21:40:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1574804435; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=vmHK76rdIqQ4aD4JLAm79rN2oKN9v4EhZFhD3fdChbs=; b=U8aTKcrbucmmNjQn8ey3eBagGSRCwdrjZORLIKgIXlhu4uQxYhdSCxMzSNQpe0ptnyl/Mi p7J6vJg5f1gjB1tEMyVl5hFBCbwpjBFI9yn0UXx7DJQZ7Q0PCj4ot7Llj+puvO+1uZfbQo y86Is2GQmHpQsx3b4qKnUOSh6uL1JnU= From: Peter Krempa To: libvir-list@redhat.com Date: Tue, 26 Nov 2019 22:39:50 +0100 Message-Id: <23a5261ea072f413242907bf67ae5b94cd87c8b0.1574803735.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH 04/21] 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: , 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-MC-Unique: ISlCGFu2Pn2wNBFK8UpruQ-1 X-Mimecast-Spam-Score: 0 Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" From: Eric Blake Introduce a few 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 from virDomainBlockCopy in the point of time chosen and in operation on multiple disks at once); 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). A backup job also affects filtering a listing of domains, as well as adding 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 APIs: virDomainBackupBegin; virDomainBackupGetXMLDesc; Signed-off-by: Eric Blake Signed-off-by: Peter Krempa Reviewed-by: Daniel P. Berrang=C3=A9 --- include/libvirt/libvirt-domain.h | 14 +++- src/driver-hypervisor.h | 12 +++ src/libvirt-domain-checkpoint.c | 7 +- src/libvirt-domain.c | 138 +++++++++++++++++++++++++++++++ src/libvirt_public.syms | 6 ++ 5 files changed, 173 insertions(+), 4 deletions(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-dom= ain.h index b52f58aa8f..e2ad4967e4 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -4129,8 +4129,10 @@ typedef void (*virConnectDomainEventMigrationIterati= onCallback)(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 - * is completed. The params array will contain statistics of the just comp= leted + * This callback occurs when a job (such as migration or backup) running on + * the domain is completed. + * + * The params array will contain statistics of the just completed * job as virDomainGetJobStats would return. The callback must not free @p= arams * (the array will be freed once the callback finishes). * @@ -4949,4 +4951,12 @@ int virDomainAgentSetResponseTimeout(virDomainPtr do= main, int timeout, unsigned int flags); +int virDomainBackupBegin(virDomainPtr domain, + const char *backupXML, + const char *checkpointXML, + unsigned int flags); + +char *virDomainBackupGetXMLDesc(virDomainPtr domain, + unsigned int flags); + #endif /* LIBVIRT_DOMAIN_H */ diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h index 4afd8f6ec5..bce023017d 100644 --- a/src/driver-hypervisor.h +++ b/src/driver-hypervisor.h @@ -1377,6 +1377,16 @@ typedef int int timeout, unsigned int flags); +typedef int +(*virDrvDomainBackupBegin)(virDomainPtr domain, + const char *backupXML, + const char *checkpointXML, + unsigned int flags); + +typedef char * +(*virDrvDomainBackupGetXMLDesc)(virDomainPtr domain, + unsigned int flags); + typedef struct _virHypervisorDriver virHypervisorDriver; typedef virHypervisorDriver *virHypervisorDriverPtr; @@ -1638,4 +1648,6 @@ struct _virHypervisorDriver { virDrvDomainCheckpointDelete domainCheckpointDelete; virDrvDomainGetGuestInfo domainGetGuestInfo; virDrvDomainAgentSetResponseTimeout domainAgentSetResponseTimeout; + virDrvDomainBackupBegin domainBackupBegin; + virDrvDomainBackupGetXMLDesc domainBackupGetXMLDesc; }; diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoin= t.c index fa391f8a06..432c2d5a52 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -102,8 +102,11 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr c= heckpoint) * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags * * Create a new checkpoint using @xmlDesc, with a top-level - * element, on a running @domain. Note that @xmlDesc - * must validate against the XML schema. + * element, on a running @domain. Note that + * @xmlDesc must validate against the XML schema. + * 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 X= ML * for more details on @xmlDesc. In particular, some hypervisors may requi= re diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 77169ec4ca..ec402ba5c0 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -12541,3 +12541,141 @@ virDomainAgentSetResponseTimeout(virDomainPtr dom= ain, virDispatchError(conn); return -1; } + + +/** + * virDomainBackupBegin: + * @domain: a domain object + * @backupXML: description of the requested backup + * @checkpointXML: description of a checkpoint to create or NULL + * @flags: unused; callers must pass 0 + * + * Start a point-in-time backup job for the specified disks of a + * running domain. + * + * A backup job is a domain job and thus mutually exclusive with any other + * domain job such as migration. + * + * 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(). Completion of the job is also annou= nced + * asynchronously via VIR_DOMAIN_EVENT_ID_JOB_COMPLETED event. + * + * 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 + * fails or virDomainAbortJob() is used prior to the event being + * emitted). This kind of the job finishes automatically. Users can + * determine success by using virDomainGetJobStats() with + * VIR_DOMAIN_JOB_STATS_COMPLETED flag. + * + * 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 libvir has to be informed via + * virDomainAbortJob() when the third-party NBD client is done and the bac= kup + * resources can be released. + * + * The @backupXML parameter contains details about the backup in the top-l= evel + * element , 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. + * + * 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 to create + * a checkpoint atomically covering the same point in time as 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 arbitr= ary + * formats if checkpoints are not involved. + * + * Returns 0 on success or -1 on failure. + */ +int +virDomainBackupBegin(virDomainPtr domain, + const char *backupXML, + const char *checkpointXML, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "backupXML=3D%s, checkpointXML=3D%s, flags=3D= 0x%x", + NULLSTR(backupXML), NULLSTR(checkpointXML), flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn =3D domain->conn; + + virCheckNonNullArgGoto(backupXML, error); + virCheckReadOnlyGoto(conn->flags, error); + + if (conn->driver->domainBackupBegin) { + int ret; + ret =3D conn->driver->domainBackupBegin(domain, backupXML, checkpo= intXML, + flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainBackupGetXMLDesc: + * @domain: a domain object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Queries the configuration of the active backup job. + * + * 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. + * + * 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, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "flags=3D0x%x", flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn =3D domain->conn; + + if (conn->driver->domainBackupGetXMLDesc) { + char *ret; + ret =3D conn->driver->domainBackupGetXMLDesc(domain, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms index c92f083758..539d2e3943 100644 --- a/src/libvirt_public.syms +++ b/src/libvirt_public.syms @@ -867,4 +867,10 @@ LIBVIRT_5.10.0 { virDomainAgentSetResponseTimeout; } LIBVIRT_5.8.0; +LIBVIRT_6.0.0 { + global: + virDomainBackupBegin; + virDomainBackupGetXMLDesc; +} LIBVIRT_5.10.0; + # .... define new API here using predicted next version number .... --=20 2.23.0 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list