[libvirt] [PATCH v9 00/10] work-in-progress: incremental backup
This is the current state of my incremental backup work on top of the v9 checkpoint patches [1]. While everything compiles and my local tests are able to perform an incremental backup, I already know that the code needs a lot of cleanups before it can be accepted upstream; this is more of a preview post to allow further testing against the APIs while my more immediate focus is on getting checkpoints in. There will be a v10 of this portion of the backup work, but now that checkpoints are nearly ready to go, I'm still aiming to get backups in the same 5.6 release window. [1] https://www.redhat.com/archives/libvir-list/2019-July/msg00236.html I've pushed a tag backup-v9 to both my libvirt.git and libvirt-python.git repos to match: https://repo.or.cz/libvirt/ericb.git/shortlog/refs/tags/backup-v9 https://repo.or.cz/libvirt-python/ericb.git/shortlog/refs/tags/backup-v9 Changes since v8: - lots of rebasing - however, reviews from v8 on this part of the series have not been addressed yet... 001/10:[down] 'backup: qemu: Implement VIR_DOMAIN_CHECKPOINT_XML_SIZE flag' 002/10:[0016] [FC] 'backup: Document new XML for backups' 003/10:[0112] [FC] 'backup: Introduce virDomainBackup APIs' 004/10:[0419] [FC] 'backup: Implement backup APIs for remote driver' 005/10:[0023] [FC] 'backup: Parse and output backup XML' 006/10:[0052] [FC] 'backup: Implement virsh support for backup' 007/10:[0006] [FC] 'backup: qemu: Implement framework for backup job APIs' 008/10:[0010] [FC] 'backup: Wire up qemu full pull backup commands over QMP' 009/10:[----] [-C] 'backup: qemu: Wire up qemu full push backup commands over QMP' 010/10:[down] 'backup: Implement qemu incremental pull backup' Eric Blake (10): backup: qemu: Implement VIR_DOMAIN_CHECKPOINT_XML_SIZE flag backup: Document new XML for backups backup: Introduce virDomainBackup APIs backup: Implement backup APIs for remote driver backup: Parse and output backup XML backup: Implement virsh support for backup backup: qemu: Implement framework for backup job APIs backup: Wire up qemu full pull backup commands over QMP backup: qemu: Wire up qemu full push backup commands over QMP backup: Implement qemu incremental pull backup include/libvirt/libvirt-domain.h | 41 +- src/conf/backup_conf.h | 94 +++ src/conf/virconftypes.h | 3 + src/driver-hypervisor.h | 14 + src/qemu/qemu_blockjob.h | 1 + src/qemu/qemu_domain.h | 4 + src/qemu/qemu_monitor.h | 4 + src/qemu/qemu_monitor_json.h | 3 + docs/docs.html.in | 3 +- docs/format.html.in | 1 + docs/formatbackup.html.in | 184 +++++ docs/formatcheckpoint.html.in | 12 +- docs/index.html.in | 3 +- docs/schemas/domainbackup.rng | 219 ++++++ examples/c/misc/event-test.c | 3 + libvirt.spec.in | 1 + mingw-libvirt.spec.in | 2 + src/conf/Makefile.inc.am | 2 + src/conf/backup_conf.c | 546 ++++++++++++++ src/conf/domain_conf.c | 2 +- src/libvirt-domain-checkpoint.c | 7 +- src/libvirt-domain.c | 219 ++++++ src/libvirt_private.syms | 8 +- src/libvirt_public.syms | 3 + src/qemu/qemu_domain.c | 37 +- src/qemu/qemu_driver.c | 706 ++++++++++++++++++- src/qemu/qemu_monitor.c | 11 + src/qemu/qemu_monitor_json.c | 80 +++ src/qemu/qemu_process.c | 9 + src/remote/remote_driver.c | 3 + src/remote/remote_protocol.x | 53 +- src/remote_protocol-structs | 28 + tests/Makefile.am | 2 + 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/virschematest.c | 2 + tools/virsh-domain.c | 253 ++++++- tools/virsh.pod | 49 ++ 42 files changed, 2634 insertions(+), 22 deletions(-) create mode 100644 src/conf/backup_conf.h create mode 100644 docs/formatbackup.html.in create mode 100644 docs/schemas/domainbackup.rng create mode 100644 src/conf/backup_conf.c 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 -- 2.20.1
Once a checkpoint has been created, it is desirable to estimate the size of the disk delta that is represented between the checkpoint and the current operation. To do this, we have to scrape information out of QMP query-block on a request from the user. Signed-off-by: Eric Blake <eblake@redhat.com> --- src/qemu/qemu_monitor.h | 4 ++ src/qemu/qemu_monitor_json.h | 3 ++ src/qemu/qemu_driver.c | 56 +++++++++++++++++++++++++- src/qemu/qemu_monitor.c | 11 ++++++ src/qemu/qemu_monitor_json.c | 76 ++++++++++++++++++++++++++++++++++++ 5 files changed, 149 insertions(+), 1 deletion(-) diff --git a/src/qemu/qemu_monitor.h b/src/qemu/qemu_monitor.h index c41428b048..9667dac284 100644 --- a/src/qemu/qemu_monitor.h +++ b/src/qemu/qemu_monitor.h @@ -24,6 +24,7 @@ #include "internal.h" #include "domain_conf.h" +#include "checkpoint_conf.h" #include "virbitmap.h" #include "virhash.h" #include "virjson.h" @@ -627,6 +628,9 @@ int qemuMonitorBlockStatsUpdateCapacity(qemuMonitorPtr mon, int qemuMonitorBlockStatsUpdateCapacityBlockdev(qemuMonitorPtr mon, virHashTablePtr stats) ATTRIBUTE_NONNULL(2); +int qemuMonitorUpdateCheckpointSize(qemuMonitorPtr mon, + virDomainCheckpointDefPtr chk) + ATTRIBUTE_NONNULL(2); int qemuMonitorBlockResize(qemuMonitorPtr mon, const char *device, diff --git a/src/qemu/qemu_monitor_json.h b/src/qemu/qemu_monitor_json.h index d0b519c88e..609e0f744c 100644 --- a/src/qemu/qemu_monitor_json.h +++ b/src/qemu/qemu_monitor_json.h @@ -97,6 +97,9 @@ int qemuMonitorJSONBlockResize(qemuMonitorPtr mon, const char *nodename, unsigned long long size); +int qemuMonitorJSONUpdateCheckpointSize(qemuMonitorPtr mon, + virDomainCheckpointDefPtr chk); + int qemuMonitorJSONSetPassword(qemuMonitorPtr mon, const char *protocol, const char *password, diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index 4131367245..f9605027be 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -17363,11 +17363,15 @@ qemuDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, virDomainObjPtr vm = NULL; char *xml = NULL; virDomainMomentObjPtr chk = NULL; + qemuDomainObjPrivatePtr priv; + int rc; + size_t i; virDomainCheckpointDefPtr chkdef; unsigned int format_flags; virCheckFlags(VIR_DOMAIN_CHECKPOINT_XML_SECURE | - VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN, NULL); + VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN | + VIR_DOMAIN_CHECKPOINT_XML_SIZE, NULL); if (!(vm = qemuDomObjFromCheckpoint(checkpoint))) return NULL; @@ -17379,12 +17383,62 @@ qemuDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, goto cleanup; chkdef = virDomainCheckpointObjGetDef(chk); + if (flags & VIR_DOMAIN_CHECKPOINT_XML_SIZE) { + /* TODO: for non-current checkpoint, this requires a QMP sequence per + disk, since the stat of one bitmap in isolation is too low, + and merely adding bitmap sizes may be too high: + block-dirty-bitmap-create tmp + for each bitmap from checkpoint to current: + add bitmap to src_list + block-dirty-bitmap-merge dst=tmp src_list + query-block and read tmp size + block-dirty-bitmap-remove tmp + So for now, go with simpler query-blocks only for current. + */ + if (virDomainCheckpointGetCurrent(vm->checkpoints) != chk) { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, + _("cannot compute size for non-current checkpoint '%s'"), + checkpoint->name); + goto cleanup; + } + + if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_QUERY) < 0) + goto cleanup; + + if (virDomainObjCheckActive(vm) < 0) + goto endjob; + + if (qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0) + goto endjob; + + /* TODO: Shouldn't need to recompute node names. */ + for (i = 0; i < chkdef->ndisks; i++) { + virDomainCheckpointDiskDef *disk = &chkdef->disks[i]; + + if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP) + continue; + VIR_FREE(chk->def->dom->disks[disk->idx]->src->nodeformat); + if (VIR_STRDUP(chk->def->dom->disks[disk->idx]->src->nodeformat, + qemuBlockNodeLookup(vm, disk->name)) < 0) + goto endjob; + } + + priv = vm->privateData; + qemuDomainObjEnterMonitor(driver, vm); + rc = qemuMonitorUpdateCheckpointSize(priv->mon, chkdef); + if (qemuDomainObjExitMonitor(driver, vm) < 0) + goto endjob; + if (rc < 0) + goto endjob; + } + format_flags = virDomainCheckpointFormatConvertXMLFlags(flags); if (chk == virDomainCheckpointGetCurrent(vm->checkpoints)) format_flags |= VIR_DOMAIN_CHECKPOINT_FORMAT_CURRENT; xml = virDomainCheckpointDefFormat(chkdef, driver->caps, driver->xmlopt, format_flags); + endjob: if (flags & VIR_DOMAIN_CHECKPOINT_XML_SIZE) qemuDomainObjEndJob(driver, vm); diff --git a/src/qemu/qemu_monitor.c b/src/qemu/qemu_monitor.c index 731be2e5a6..19c769ae41 100644 --- a/src/qemu/qemu_monitor.c +++ b/src/qemu/qemu_monitor.c @@ -2308,6 +2308,17 @@ qemuMonitorBlockStatsUpdateCapacityBlockdev(qemuMonitorPtr mon, return qemuMonitorJSONBlockStatsUpdateCapacityBlockdev(mon, stats); } +/* Updates "chk" to fill in size of the associated bitmap */ +int qemuMonitorUpdateCheckpointSize(qemuMonitorPtr mon, + virDomainCheckpointDefPtr chk) +{ + VIR_DEBUG("chk=%p", chk); + + QEMU_CHECK_MONITOR(mon); + + return qemuMonitorJSONUpdateCheckpointSize(mon, chk); +} + int qemuMonitorBlockResize(qemuMonitorPtr mon, const char *device, diff --git a/src/qemu/qemu_monitor_json.c b/src/qemu/qemu_monitor_json.c index 8723ff49c7..1769fa70cb 100644 --- a/src/qemu/qemu_monitor_json.c +++ b/src/qemu/qemu_monitor_json.c @@ -2876,6 +2876,82 @@ int qemuMonitorJSONBlockResize(qemuMonitorPtr mon, return ret; } +int qemuMonitorJSONUpdateCheckpointSize(qemuMonitorPtr mon, + virDomainCheckpointDefPtr chk) +{ + int ret = -1; + size_t i, j; + virJSONValuePtr devices; + + if (!(devices = qemuMonitorJSONQueryBlock(mon))) + return -1; + + for (i = 0; i < virJSONValueArraySize(devices); i++) { + virJSONValuePtr dev = virJSONValueArrayGet(devices, i); + virJSONValuePtr inserted; + virJSONValuePtr bitmaps = NULL; + const char *node; + virDomainCheckpointDiskDefPtr disk; + + if (!(dev = qemuMonitorJSONGetBlockDev(devices, i))) + goto cleanup; + + if (!(inserted = virJSONValueObjectGetObject(dev, "inserted"))) + continue; + if (!(node = virJSONValueObjectGetString(inserted, "node-name"))) { + virReportError(VIR_ERR_INTERNAL_ERROR, "%s", + _("query-block device entry was not in expected format")); + goto cleanup; + } + + for (j = 0; j < chk->ndisks; j++) { + disk = &chk->disks[j]; + if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP) + continue; + if (STREQ(chk->parent.dom->disks[disk->idx]->src->nodeformat, node)) + break; + } + if (j == chk->ndisks) { + VIR_DEBUG("query-block did not find node %s", node); + continue; + } + if (!(bitmaps = virJSONValueObjectGetArray(dev, "dirty-bitmaps"))) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("disk %s dirty bitmaps missing"), disk->name); + goto cleanup; + } + for (j = 0; j < virJSONValueArraySize(bitmaps); j++) { + virJSONValuePtr map = virJSONValueArrayGet(bitmaps, j); + const char *name; + + if (!(name = virJSONValueObjectGetString(map, "name"))) { + virReportError(VIR_ERR_INTERNAL_ERROR, "%s", + _("dirty bitmaps entry was not in expected format")); + goto cleanup; + } + if (STRNEQ(name, disk->bitmap)) + continue; + if (virJSONValueObjectGetNumberUlong(map, "count", &disk->size) < 0) { + virReportError(VIR_ERR_INTERNAL_ERROR, "%s", + _("invalid bitmap count")); + goto cleanup; + } + break; + } + if (j == virJSONValueArraySize(bitmaps)) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("disk %s dirty bitmap info missing"), disk->name); + goto cleanup; + } + } + + ret = 0; + + cleanup: + virJSONValueFree(devices); + return ret; +} + int qemuMonitorJSONSetPassword(qemuMonitorPtr mon, const char *protocol, -- 2.20.1
Prepare for new backup APIs by describing the XML that will represent a backup. The XML resembles snapshots and checkpoints in being able to select actions for a set of disks, but has other differences. It can support both push model (the hypervisor does the backup directly into the destination file) and pull model (the hypervisor exposes an access port for a third party to grab what is necessary). Add testsuite coverage for some minimal uses of the XML. The <disk> element within <domainbackup> tries to model the same elements as a <disk> under <domain>, but sharing the RNG grammar proved to be hairy. That is in part because while <domain> use <source> to describe a host resource in use by the guest, a backup job is using a host resource that is not visible to the guest: a push backup action is instead describing a <target> (which ultimately could be a remote network resource, but for simplicity the RNG just validates a local file for now), and a pull backup action is instead describing a temporary local file <scratch> (which probably should not be a remote resource). A future refactoring may thus introduce some way to parameterize RNG to accept <disk type='FOO'>...</disk> so that the name of the subelement can be <source> for domain, or <target> or <scratch> as needed for backups. Future patches may improve this area of code. Signed-off-by: Eric Blake <eblake@redhat.com> --- docs/docs.html.in | 3 +- docs/format.html.in | 1 + docs/formatbackup.html.in | 184 ++++++++++++++++ docs/formatcheckpoint.html.in | 12 +- docs/index.html.in | 3 +- docs/schemas/domainbackup.rng | 219 +++++++++++++++++++ libvirt.spec.in | 1 + mingw-libvirt.spec.in | 2 + tests/Makefile.am | 2 + 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/virschematest.c | 2 + 16 files changed, 465 insertions(+), 8 deletions(-) create mode 100644 docs/formatbackup.html.in create mode 100644 docs/schemas/domainbackup.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 diff --git a/docs/docs.html.in b/docs/docs.html.in index a00b131466..1c38668ef6 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -82,7 +82,8 @@ <a href="formatnode.html">node devices</a>, <a href="formatsecret.html">secrets</a>, <a href="formatsnapshot.html">snapshots</a>, - <a href="formatcheckpoint.html">checkpoints</a></dd> + <a href="formatcheckpoint.html">checkpoints</a>, + <a href="formatbackup.html">backup jobs</a></dd> <dt><a href="uri.html">URI format</a></dt> <dd>The URI formats used for connecting to libvirt</dd> diff --git a/docs/format.html.in b/docs/format.html.in index 20f9ef3348..e287b430bc 100644 --- a/docs/format.html.in +++ b/docs/format.html.in @@ -26,6 +26,7 @@ <li><a href="formatsecret.html">Secrets</a></li> <li><a href="formatsnapshot.html">Snapshots</a></li> <li><a href="formatcheckpoint.html">Checkpoints</a></li> + <li><a href="formatbackup.html">Backup jobs</a></li> </ul> <h2>Command line validation</h2> diff --git a/docs/formatbackup.html.in b/docs/formatbackup.html.in new file mode 100644 index 0000000000..4f76013d84 --- /dev/null +++ b/docs/formatbackup.html.in @@ -0,0 +1,184 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html> +<html xmlns="http://www.w3.org/1999/xhtml"> + <body> + <h1>Backup XML format</h1> + + <ul id="toc"></ul> + + <h2><a id="BackupAttributes">Backup XML</a></h2> + + <p> + Creating a backup, whether full or incremental, is done + via <code>virDomainBackupBegin()</code>, which takes an XML + description of the actions to perform, as well as an optional + second XML document <a href="formatcheckpoint.html">describing a + checkpoint</a> to create at the same point in time. See + also <a href="domainstatecapture.html">a comparison</a> between + the various state capture APIs. + </p> + <p> + 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). + </p> + <p> + The instructions for beginning a backup job are provided as + attributes and elements of the + top-level <code>domainbackup</code> element. This element + includes an optional attribute <code>mode</code> which can be + either "push" or "pull" (default + push). <code>virDomainBackupGetXMLDesc()</code> can be used to + see the actual values selected for elements omitted during + creation (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: + </p> + <dl> + <dt><code>id</code></dt> + <dd>Ignored on input, this element is the job id of the backup + operation returned on success + from <code>virDomainBackupBegin()</code>, and is used for + selecting which backup operation to target + during <code>virDomainBackupGetXMLDesc()</code> + and <code>virDomainBackupEnd()</code>. (Note that until + additional APIs are added for supporting parallel jobs, it is + also possible to ignore this element and use the job + id <code>0</code> to refer to the one and only current backup + job.)</dd> + <dt><code>incremental</code></dt> + <dd>An optional element giving the name of 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 named 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 named + checkpoint. If omitted, a full backup is performed. + </dd> + <dt><code>server</code></dt> + <dd>Present only for a pull mode backup. Contains the same + attributes as + the <a href="formatdomain.html#elementsDisks"><code>protocol</code> + element of a disk</a> 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 is started. + </dd> + <dt><code>disks</code></dt> + <dd>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). If the entire element was omitted on + input, then all disks participate in the backup, otherwise, + only the disks explicitly listed which do not also + use <code>backup='no'</code> will participate. On output, this + is the state of each of the domain's disk in relation to the + backup operation. + <dl> + <dt><code>disk</code></dt> + <dd>This sub-element describes the backup properties of a + specific disk, with the following attributes and child + elements: + <dl> + <dt><code>name</code></dt> + <dd>A mandatory attribute which must match either + the <code><target dev='name'/></code> or an + unambiguous <code><source file='name'/></code> + of one of + the <a href="formatdomain.html#elementsDisks">disk + devices</a> specified for the domain at the time of + the checkpoint.</dd> + <dt><code>backup</code></dt> + <dd>An optional attribute to describe the state of the + backup for the given disk. On input, the + value <code>no</code> skips a backup of the disk, and + any other value is ignored; on output, other values + such as <code>begin</code>, <code>inprogress</code>, + or <code>ready</code> track the backup progress that + libvirt has observed for that disk.</dd> + <dt><code>type</code></dt> + <dd>An optional attribute to describe the type of the + disk, except when <code>backup='no'</code> is + used. Valid values include <code>file</code> + or <code>block</code> for both push and pull model + backups; in the future, <code>network</code> may be + added for push model backups. Similar to a disk + declaration for a domain, the choice of type controls + what additional sub-elements are needed to describe + the destination (such as <code>protocol</code> for a + network destination).</dd> + <dt><code>target</code></dt> + <dd>Valid only for push mode backups, this is the + primary sub-element that describes the file name of + the backup destination, similar to + the <code>source</code> sub-element of a domain + disk. An optional sub-element <code>driver</code> can + also be used, with an attribute <code>type</code> to + specify a destination format different from + qcow2. Additionally, if a push backup is not + incremental, <code>target</code> may contain an + optional attribute <code>shallow="on"</code> so that + the destination file copies only the top-most source + file in a backing chain, rather than collapsing the + entire chain into the copy.</dd> + <dt><code>scratch</code></dt> + <dd>Valid only for pull mode backups, this is the + primary sub-element that describes the file name of + the local scratch file to be used in facilitating the + backup, and is similar to the <code>source</code> + sub-element of a domain disk.</dd> + </dl> + </dd> + </dl> + </dd> + </dl> + + <h2><a id="example">Examples</a></h2> + + <p>Use <code>virDomainBackupBegin()</code> to perform a full + backup using push mode. The example lets libvirt pick the + destination and format for 'vda', fully specifies that we want a + raw backup of 'vdb', and omits 'vdc' from the operation. + </p> + <pre> +<domainbackup> + <disks/> + <disk name='vda'/> + <disk name='vdb' type='file'> + <target file='/path/to/vdb.backup'/> + <driver type='raw'/> + </disk> + <disk name='vdc' backup='no'/> + </disks/> +</domainbackup> + </pre> + + <p>If the previous full backup also passed a parameter describing + <a href="formatcheckpoint.html">checkpoint XML</a> that resulted + in a checkpoint named <code>1525889631</code>, we can make + another call to <code>virDomainBackupBegin()</code> to perform + an incremental backup of just the data changed since that + checkpoint, this time using the following XML to start a pull + model export of the 'vda' and 'vdb' disks, where a third-party + NBD client connecting to '/path/to/server' completes the backup + (omitting 'vdc' from the explicit list has the same effect as + the backup='no' from the previous example): + </p> + <pre> +<domainbackup mode="pull"> + <incremental>1525889631</incremental> + <server transport="unix" socket="/path/to/server"/> + <disks/> + <disk name='vda' type='file'> + <scratch file='/path/to/file1.scratch'/> + </disk> + </disks/> +</domainbackup> + </pre> + </body> +</html> diff --git a/docs/formatcheckpoint.html.in b/docs/formatcheckpoint.html.in index 030f0d6af0..9e9ada8191 100644 --- a/docs/formatcheckpoint.html.in +++ b/docs/formatcheckpoint.html.in @@ -28,12 +28,12 @@ first checkpoint and the second backup operation), it is possible to do an offline reconstruction of the state of the disk at the time of the second backup without having to copy as - much data as a second full backup would require. Future API - additions will make it possible to create checkpoints in - conjunction with a backup - via <code>virDomainBackupBegin()</code> or with an external - snapshot via <code>virDomainSnapshotCreateXML2</code>; but for - now, libvirt exposes enough support to create disk checkpoints + much data as a second full backup would require. Most disk + checkpoints are created in conjunction with a backup + via <code>virDomainBackupBegin()</code>, although a future API + addition of <code>virDomainSnapshotCreateXML2()</code> will also + make this possible when creating external snapshots; however, + libvirt also exposes enough support to create disk checkpoints independently from a backup operation via <code>virDomainCheckpointCreateXML()</code>. </p> diff --git a/docs/index.html.in b/docs/index.html.in index 7d0ab650e3..26e8406917 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -59,7 +59,8 @@ <a href="formatnode.html">node devices</a>, <a href="formatsecret.html">secrets</a>, <a href="formatsnapshot.html">snapshots</a>, - <a href="formatcheckpoint.html">checkpoints</a></dd> + <a href="formatcheckpoint.html">checkpoints</a>, + <a href="formatbackup.html">backup jobs</a></dd> <dt><a href="http://wiki.libvirt.org">Wiki</a></dt> <dd>Read further community contributed content</dd> </dl> diff --git a/docs/schemas/domainbackup.rng b/docs/schemas/domainbackup.rng new file mode 100644 index 0000000000..92327e7077 --- /dev/null +++ b/docs/schemas/domainbackup.rng @@ -0,0 +1,219 @@ +<?xml version="1.0"?> +<!-- A Relax NG schema for the libvirt domain backup properties XML format --> +<grammar xmlns="http://relaxng.org/ns/structure/1.0"> + <start> + <ref name='domainbackup'/> + </start> + + <include href='domaincommon.rng'/> + + <define name='domainbackup'> + <element name='domainbackup'> + <optional> + <attribute name='id'> + <ref name="unsignedInt"/> + </attribute> + </optional> + <interleave> + <optional> + <element name='incremental'> + <text/> + </element> + </optional> + <choice> + <group> + <optional> + <attribute name='mode'> + <value>push</value> + </attribute> + </optional> + <ref name='backupDisksPush'/> + </group> + <group> + <attribute name='mode'> + <value>pull</value> + </attribute> + <interleave> + <element name='server'> + <choice> + <group> + <optional> + <attribute name='transport'> + <value>tcp</value> + </attribute> + </optional> + <attribute name='name'> + <choice> + <ref name='dnsName'/> + <ref name='ipAddr'/> + </choice> + </attribute> + <optional> + <attribute name='port'> + <ref name='unsignedInt'/> + </attribute> + </optional> + <!-- add tls? --> + </group> + <group> + <attribute name='transport'> + <value>unix</value> + </attribute> + <attribute name='socket'> + <ref name='absFilePath'/> + </attribute> + </group> + </choice> + </element> + <ref name='backupDisksPull'/> + </interleave> + </group> + </choice> + </interleave> + </element> + </define> + + <define name='backupPushDriver'> + <optional> + <element name='driver'> + <attribute name='type'> + <ref name='storageFormat'/> + </attribute> + </element> + </optional> + </define> + + <define name='backupAttr'> + <!-- valid values of <disk backup='XXX'> other than 'no' --> + <optional> + <attribute name='backup'> + <choice> + <value>begin</value> + <value>inprogress</value> + <value>ready</value> + </choice> + </attribute> + </optional> + </define> + + <define name='backupDisksPush'> + <optional> + <element name='disks'> + <oneOrMore> + <element name='disk'> + <attribute name='name'> + <choice> + <ref name='diskTarget'/> + <ref name='absFilePath'/> + </choice> + </attribute> + <optional> + <attribute name='shallow'> + <value>on</value> + </attribute> + </optional> + <choice> + <group> + <attribute name='backup'> + <value>no</value> + </attribute> + </group> + <!-- FIXME allow push to a network location, perhaps by + refactoring 'diskSource' to take element name by a + per-grammar ref --> + <group> + <ref name='backupAttr'/> + <optional> + <attribute name='type'> + <value>file</value> + </attribute> + </optional> + <interleave> + <optional> + <element name='target'> + <attribute name='file'> + <ref name='absFilePath'/> + </attribute> + </element> + </optional> + <ref name='backupPushDriver'/> + </interleave> + </group> + <group> + <ref name='backupAttr'/> + <attribute name='type'> + <value>block</value> + </attribute> + <interleave> + <optional> + <element name='target'> + <attribute name='dev'> + <ref name='absFilePath'/> + </attribute> + </element> + </optional> + <ref name='backupPushDriver'/> + </interleave> + </group> + <!-- + <group> + <ref name='backupAttr'/> + <attribute name='type'> + <value>network</value> + </attribute> + ... + </group> + --> + </choice> + </element> + </oneOrMore> + </element> + </optional> + </define> + + <define name='backupDisksPull'> + <optional> + <element name='disks'> + <oneOrMore> + <element name='disk'> + <attribute name='name'> + <choice> + <ref name='diskTarget'/> + <ref name='absFilePath'/> + </choice> + </attribute> + <choice> + <group> + <optional> + <attribute name='type'> + <value>file</value> + </attribute> + </optional> + <optional> + <element name='scratch'> + <attribute name='file'> + <ref name='absFilePath'/> + </attribute> + </element> + </optional> + </group> + <group> + <attribute name='type'> + <value>block</value> + </attribute> + <optional> + <element name='scratch'> + <attribute name='dev'> + <ref name='absFilePath'/> + </attribute> + </element> + </optional> + </group> + </choice> + </element> + </oneOrMore> + </element> + </optional> + </define> + +</grammar> diff --git a/libvirt.spec.in b/libvirt.spec.in index ffadaf2d49..358f5fa200 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -1779,6 +1779,7 @@ 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 diff --git a/mingw-libvirt.spec.in b/mingw-libvirt.spec.in index a20c4b7d74..a56fca45fd 100644 --- a/mingw-libvirt.spec.in +++ b/mingw-libvirt.spec.in @@ -231,6 +231,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.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 @@ -322,6 +323,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.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 diff --git a/tests/Makefile.am b/tests/Makefile.am index 0ae1e51e03..ed5e6c6303 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -82,6 +82,8 @@ EXTRA_DIST = \ capabilityschemadata \ commanddata \ cputestdata \ + domainbackupxml2xmlin \ + domainbackupxml2xmlout \ domaincapsschemadata \ domainconfdata \ domainschemadata \ diff --git a/tests/domainbackupxml2xmlin/backup-pull.xml b/tests/domainbackupxml2xmlin/backup-pull.xml new file mode 100644 index 0000000000..2ce5cd6711 --- /dev/null +++ b/tests/domainbackupxml2xmlin/backup-pull.xml @@ -0,0 +1,9 @@ +<domainbackup mode="pull"> + <incremental>1525889631</incremental> + <server transport='tcp' name='localhost' port='10809'/> + <disks> + <disk name='vda' type='file'> + <scratch file='/path/to/file'/> + </disk> + </disks> +</domainbackup> diff --git a/tests/domainbackupxml2xmlin/backup-push.xml b/tests/domainbackupxml2xmlin/backup-push.xml new file mode 100644 index 0000000000..1b7d3061fd --- /dev/null +++ b/tests/domainbackupxml2xmlin/backup-push.xml @@ -0,0 +1,9 @@ +<domainbackup mode="push"> + <incremental>1525889631</incremental> + <disks> + <disk name='vda' type='file'> + <driver type='raw'/> + <target file='/path/to/file'/> + </disk> + </disks> +</domainbackup> diff --git a/tests/domainbackupxml2xmlin/empty.xml b/tests/domainbackupxml2xmlin/empty.xml new file mode 100644 index 0000000000..7ed511f97b --- /dev/null +++ b/tests/domainbackupxml2xmlin/empty.xml @@ -0,0 +1 @@ +<domainbackup/> diff --git a/tests/domainbackupxml2xmlout/backup-pull.xml b/tests/domainbackupxml2xmlout/backup-pull.xml new file mode 100644 index 0000000000..2ce5cd6711 --- /dev/null +++ b/tests/domainbackupxml2xmlout/backup-pull.xml @@ -0,0 +1,9 @@ +<domainbackup mode="pull"> + <incremental>1525889631</incremental> + <server transport='tcp' name='localhost' port='10809'/> + <disks> + <disk name='vda' type='file'> + <scratch file='/path/to/file'/> + </disk> + </disks> +</domainbackup> diff --git a/tests/domainbackupxml2xmlout/backup-push.xml b/tests/domainbackupxml2xmlout/backup-push.xml new file mode 100644 index 0000000000..1b7d3061fd --- /dev/null +++ b/tests/domainbackupxml2xmlout/backup-push.xml @@ -0,0 +1,9 @@ +<domainbackup mode="push"> + <incremental>1525889631</incremental> + <disks> + <disk name='vda' type='file'> + <driver type='raw'/> + <target file='/path/to/file'/> + </disk> + </disks> +</domainbackup> diff --git a/tests/domainbackupxml2xmlout/empty.xml b/tests/domainbackupxml2xmlout/empty.xml new file mode 100644 index 0000000000..13600fbb1c --- /dev/null +++ b/tests/domainbackupxml2xmlout/empty.xml @@ -0,0 +1,7 @@ +<domainbackup mode="push"> + <disks> + <disk name="vda" type="file"> + <target file="/path/to/file1.copy"/> + </disk> + </disks> +</domainbackup> diff --git a/tests/virschematest.c b/tests/virschematest.c index 8f5101df21..29a3b4eebb 100644 --- a/tests/virschematest.c +++ b/tests/virschematest.c @@ -221,6 +221,8 @@ mymain(void) "lxcxml2xmloutdata", "bhyvexml2argvdata", "genericxml2xmlindata", "genericxml2xmloutdata", "xlconfigdata", "libxlxml2domconfigdata", "qemuhotplugtestdomains"); + DO_TEST_DIR("domainbackup.rng", "domainbackupxml2xmlin", + "domainbackupxml2xmlout"); DO_TEST_DIR("domaincaps.rng", "domaincapsschemadata"); DO_TEST_DIR("domaincheckpoint.rng", "qemudomaincheckpointxml2xmlin", "qemudomaincheckpointxml2xmlout"); -- 2.20.1
On Mon, Jul 08, 2019 at 11:55:45 -0500, Eric Blake wrote:
Prepare for new backup APIs by describing the XML that will represent a backup. The XML resembles snapshots and checkpoints in being able to select actions for a set of disks, but has other differences. It can support both push model (the hypervisor does the backup directly into the destination file) and pull model (the hypervisor exposes an access port for a third party to grab what is necessary). Add testsuite coverage for some minimal uses of the XML.
The <disk> element within <domainbackup> tries to model the same elements as a <disk> under <domain>, but sharing the RNG grammar proved to be hairy. That is in part because while <domain> use <source> to describe a host resource in use by the guest, a backup job is using a host resource that is not visible to the guest: a push backup action is instead describing a <target> (which ultimately could be a remote network resource, but for simplicity the RNG just validates a local file for now), and a pull backup action is instead describing a temporary local file <scratch> (which probably should not be a remote resource). A future refactoring may thus introduce some way to parameterize RNG to accept <disk type='FOO'>...</disk> so that the name of the subelement can be <source> for domain, or <target> or <scratch> as needed for backups. Future patches may improve this area of code.
Signed-off-by: Eric Blake <eblake@redhat.com> ---
[...]
diff --git a/docs/formatbackup.html.in b/docs/formatbackup.html.in new file mode 100644 index 0000000000..4f76013d84 --- /dev/null +++ b/docs/formatbackup.html.in @@ -0,0 +1,184 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html> +<html xmlns="http://www.w3.org/1999/xhtml"> + <body> + <h1>Backup XML format</h1> + + <ul id="toc"></ul> + + <h2><a id="BackupAttributes">Backup XML</a></h2> + + <p> + Creating a backup, whether full or incremental, is done + via <code>virDomainBackupBegin()</code>, which takes an XML + description of the actions to perform, as well as an optional + second XML document <a href="formatcheckpoint.html">describing a + checkpoint</a> to create at the same point in time. See + also <a href="domainstatecapture.html">a comparison</a> between + the various state capture APIs. + </p> + <p> + 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). + </p> + <p> + The instructions for beginning a backup job are provided as + attributes and elements of the + top-level <code>domainbackup</code> element. This element + includes an optional attribute <code>mode</code> which can be + either "push" or "pull" (default + push). <code>virDomainBackupGetXMLDesc()</code> can be used to + see the actual values selected for elements omitted during + creation (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: + </p> + <dl> + <dt><code>id</code></dt> + <dd>Ignored on input, this element is the job id of the backup + operation returned on success + from <code>virDomainBackupBegin()</code>, and is used for + selecting which backup operation to target + during <code>virDomainBackupGetXMLDesc()</code>
Rather than adding yet another job-specific API I'm thinking of adding a set of "domain job" APIs which will allow getting XML stats for migration block and other jobs generically. My motivation is that apart from this, we also have a possibility to have a blockjob which does not have a parent disk any more (e.g. because the guest ejected it) and thus the current APIs would not semantically work with such a thing. By having a generic API we can fix all of these problems without more single-use APIs.
+ and <code>virDomainBackupEnd()</code>. (Note that until
The same for this one. Obviously the job identifier will then become a string rather than a number which will also encode the job type e.g.: block-pull-NODENAME or block-backup-3 etc. I'll try to send a example tomorrow or so. (I didn't start yet though)
+ additional APIs are added for supporting parallel jobs, it is + also possible to ignore this element and use the job + id <code>0</code> to refer to the one and only current backup + job.)</dd> + <dt><code>incremental</code></dt> + <dd>An optional element giving the name of 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 named 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 named + checkpoint. If omitted, a full backup is performed. + </dd> + <dt><code>server</code></dt> + <dd>Present only for a pull mode backup. Contains the same + attributes as + the <a href="formatdomain.html#elementsDisks"><code>protocol</code> + element of a disk</a> attached via NBD in the domain (such as
So will it also contain the 'procotol' setting itself? For future proofing we should not mandate NBD only in the XML.
+ 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 is started. + </dd> + <dt><code>disks</code></dt> + <dd>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). If the entire element was omitted on + input, then all disks participate in the backup, otherwise, + only the disks explicitly listed which do not also + use <code>backup='no'</code> will participate. On output, this + is the state of each of the domain's disk in relation to the + backup operation. + <dl> + <dt><code>disk</code></dt> + <dd>This sub-element describes the backup properties of a + specific disk, with the following attributes and child + elements: + <dl> + <dt><code>name</code></dt> + <dd>A mandatory attribute which must match either + the <code><target dev='name'/></code> or an + unambiguous <code><source file='name'/></code> + of one of + the <a href="formatdomain.html#elementsDisks">disk + devices</a> specified for the domain at the time of + the checkpoint.</dd> + <dt><code>backup</code></dt> + <dd>An optional attribute to describe the state of the + backup for the given disk. On input, the + value <code>no</code> skips a backup of the disk, and + any other value is ignored; on output, other values + such as <code>begin</code>, <code>inprogress</code>, + or <code>ready</code> track the backup progress that
Hmmm, I think the input and output XML descriptions should be separated, it's getting quite confusing.
+ libvirt has observed for that disk.</dd> + <dt><code>type</code></dt> + <dd>An optional attribute to describe the type of the + disk, except when <code>backup='no'</code> is + used. Valid values include <code>file</code> + or <code>block</code> for both push and pull model + backups; in the future, <code>network</code> may be + added for push model backups. Similar to a disk + declaration for a domain, the choice of type controls + what additional sub-elements are needed to describe + the destination (such as <code>protocol</code> for a + network destination).</dd> + <dt><code>target</code></dt> + <dd>Valid only for push mode backups, this is the + primary sub-element that describes the file name of + the backup destination, similar to + the <code>source</code> sub-element of a domain + disk. An optional sub-element <code>driver</code> can + also be used, with an attribute <code>type</code> to + specify a destination format different from + qcow2. Additionally, if a push backup is not + incremental, <code>target</code> may contain an + optional attribute <code>shallow="on"</code> so that + the destination file copies only the top-most source + file in a backing chain, rather than collapsing the + entire chain into the copy.</dd> + <dt><code>scratch</code></dt> + <dd>Valid only for pull mode backups, this is the + primary sub-element that describes the file name of + the local scratch file to be used in facilitating the + backup, and is similar to the <code>source</code>
The source subelement does not contain the 'type' attribute. Where do we set it here? <scratch type='block'><source dev='/dev/blah'/> ?
+ sub-element of a domain disk.</dd> + </dl> + </dd> + </dl> + </dd> + </dl> + + <h2><a id="example">Examples</a></h2> + + <p>Use <code>virDomainBackupBegin()</code> to perform a full + backup using push mode. The example lets libvirt pick the + destination and format for 'vda', fully specifies that we want a + raw backup of 'vdb', and omits 'vdc' from the operation. + </p> + <pre> +<domainbackup> + <disks/> + <disk name='vda'/> + <disk name='vdb' type='file'> + <target file='/path/to/vdb.backup'/> + <driver type='raw'/> + </disk> + <disk name='vdc' backup='no'/> + </disks/> +</domainbackup> + </pre> + + <p>If the previous full backup also passed a parameter describing + <a href="formatcheckpoint.html">checkpoint XML</a> that resulted + in a checkpoint named <code>1525889631</code>, we can make + another call to <code>virDomainBackupBegin()</code> to perform + an incremental backup of just the data changed since that + checkpoint, this time using the following XML to start a pull + model export of the 'vda' and 'vdb' disks, where a third-party + NBD client connecting to '/path/to/server' completes the backup + (omitting 'vdc' from the explicit list has the same effect as + the backup='no' from the previous example): + </p> + <pre> +<domainbackup mode="pull"> + <incremental>1525889631</incremental> + <server transport="unix" socket="/path/to/server"/> + <disks/> + <disk name='vda' type='file'> + <scratch file='/path/to/file1.scratch'/>
I think you want to be able to describe the type somehow. I'm expecting RHV folks to want to stash this into an LV any second.
+ </disk> + </disks/> +</domainbackup> + </pre> + </body> +</html>
[...]
diff --git a/docs/schemas/domainbackup.rng b/docs/schemas/domainbackup.rng new file mode 100644 index 0000000000..92327e7077 --- /dev/null +++ b/docs/schemas/domainbackup.rng @@ -0,0 +1,219 @@ +<?xml version="1.0"?> +<!-- A Relax NG schema for the libvirt domain backup properties XML format --> +<grammar xmlns="http://relaxng.org/ns/structure/1.0"> + <start> + <ref name='domainbackup'/> + </start> + + <include href='domaincommon.rng'/> + + <define name='domainbackup'> + <element name='domainbackup'> + <optional> + <attribute name='id'> + <ref name="unsignedInt"/> + </attribute> + </optional> + <interleave> + <optional> + <element name='incremental'> + <text/>
name
+ </element> + </optional> + <choice> + <group> + <optional> + <attribute name='mode'> + <value>push</value> + </attribute> + </optional> + <ref name='backupDisksPush'/> + </group> + <group> + <attribute name='mode'> + <value>pull</value> + </attribute> + <interleave> + <element name='server'> + <choice>
lacking 'protocol' field
+ <group> + <optional> + <attribute name='transport'> + <value>tcp</value> + </attribute> + </optional> + <attribute name='name'> + <choice> + <ref name='dnsName'/> + <ref name='ipAddr'/> + </choice> + </attribute> + <optional> + <attribute name='port'> + <ref name='unsignedInt'/> + </attribute> + </optional> + <!-- add tls? -->
In 2019 the more appropriate question would be whether to allow non-tls mode at all.
+ </group> + <group> + <attribute name='transport'> + <value>unix</value> + </attribute> + <attribute name='socket'> + <ref name='absFilePath'/> + </attribute> + </group> + </choice> + </element> + <ref name='backupDisksPull'/> + </interleave> + </group> + </choice> + </interleave> + </element> + </define> + + <define name='backupPushDriver'> + <optional> + <element name='driver'> + <attribute name='type'> + <ref name='storageFormat'/> + </attribute> + </element> + </optional> + </define> + + <define name='backupAttr'> + <!-- valid values of <disk backup='XXX'> other than 'no' --> + <optional> + <attribute name='backup'> + <choice> + <value>begin</value> + <value>inprogress</value> + <value>ready</value> + </choice> + </attribute> + </optional> + </define> + + <define name='backupDisksPush'> + <optional> + <element name='disks'> + <oneOrMore> + <element name='disk'> + <attribute name='name'> + <choice> + <ref name='diskTarget'/> + <ref name='absFilePath'/> + </choice> + </attribute> + <optional> + <attribute name='shallow'> + <value>on</value> + </attribute> + </optional> + <choice> + <group> + <attribute name='backup'> + <value>no</value> + </attribute> + </group> + <!-- FIXME allow push to a network location, perhaps by + refactoring 'diskSource' to take element name by a + per-grammar ref --> + <group> + <ref name='backupAttr'/> + <optional> + <attribute name='type'> + <value>file</value> + </attribute> + </optional> + <interleave> + <optional> + <element name='target'> + <attribute name='file'> + <ref name='absFilePath'/> + </attribute> + </element> + </optional> + <ref name='backupPushDriver'/> + </interleave> + </group> + <group> + <ref name='backupAttr'/> + <attribute name='type'> + <value>block</value> + </attribute> + <interleave> + <optional> + <element name='target'> + <attribute name='dev'> + <ref name='absFilePath'/> + </attribute> + </element> + </optional> + <ref name='backupPushDriver'/> + </interleave> + </group> + <!-- + <group> + <ref name='backupAttr'/> + <attribute name='type'> + <value>network</value> + </attribute> + ... + </group> + --> + </choice> + </element> + </oneOrMore> + </element> + </optional> + </define> + + <define name='backupDisksPull'> + <optional> + <element name='disks'> + <oneOrMore> + <element name='disk'> + <attribute name='name'> + <choice> + <ref name='diskTarget'/> + <ref name='absFilePath'/> + </choice> + </attribute> + <choice> + <group> + <optional>
Interresting, there is a scratch location 'type'. So this really should not be optional.
+ <attribute name='type'> + <value>file</value> + </attribute> + </optional> + <optional> + <element name='scratch'> + <attribute name='file'> + <ref name='absFilePath'/> + </attribute> + </element> + </optional> + </group> + <group> + <attribute name='type'> + <value>block</value>
also mention this in the example/test?
+ </attribute> + <optional> + <element name='scratch'> + <attribute name='dev'> + <ref name='absFilePath'/> + </attribute> + </element> + </optional> + </group> + </choice> + </element> + </oneOrMore> + </element> + </optional> + </define> + +</grammar>
diff --git a/tests/domainbackupxml2xmlin/backup-pull.xml b/tests/domainbackupxml2xmlin/backup-pull.xml new file mode 100644 index 0000000000..2ce5cd6711 --- /dev/null +++ b/tests/domainbackupxml2xmlin/backup-pull.xml @@ -0,0 +1,9 @@ +<domainbackup mode="pull"> + <incremental>1525889631</incremental> + <server transport='tcp' name='localhost' port='10809'/>
This really needs a 'protocol' element and also potentially multiple host elements.
+ <disks> + <disk name='vda' type='file'> + <scratch file='/path/to/file'/>
and this really needs something else than a file for the scratch
+ </disk> + </disks> +</domainbackup>
[...]
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). Since multiple backup jobs can be run in parallel in the future (well, qemu doesn't support it yet, but we don't want to preclude the idea), virDomainBackupBegin() returns a positive job id, and the id is also visible in the backup XML. But until a future libvirt release adds a bunch of APIs related to parallel job management where job ids will actually matter, the documentation is also clear that job id 0 means the 'currently running backup job' (provided one exists), for use in virDomainBackupGetXMLDesc() and virDomainBackupEnd(). The full list of new APIs: virDomainBackupBegin; virDomainBackupEnd; virDomainBackupGetXMLDesc; Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> --- include/libvirt/libvirt-domain.h | 41 +++++- src/driver-hypervisor.h | 14 ++ src/qemu/qemu_blockjob.h | 1 + examples/c/misc/event-test.c | 3 + src/conf/domain_conf.c | 2 +- src/libvirt-domain-checkpoint.c | 7 +- src/libvirt-domain.c | 219 +++++++++++++++++++++++++++++++ src/libvirt_public.syms | 3 + tools/virsh-domain.c | 8 +- 9 files changed, 291 insertions(+), 7 deletions(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index f160ee88b5..8aae7889f7 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -3,7 +3,7 @@ * Summary: APIs for management of domains * Description: Provides APIs for the management of domains * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2019 Red Hat, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -2446,6 +2446,9 @@ typedef enum { * exists as long as sync is active */ VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT = 4, + /* Backup (virDomainBackupBegin), job exists until virDomainBackupEnd */ + VIR_DOMAIN_BLOCK_JOB_TYPE_BACKUP = 5, + # ifdef VIR_ENUM_SENTINELS VIR_DOMAIN_BLOCK_JOB_TYPE_LAST # endif @@ -3267,6 +3270,7 @@ typedef enum { VIR_DOMAIN_JOB_OPERATION_SNAPSHOT = 6, VIR_DOMAIN_JOB_OPERATION_SNAPSHOT_REVERT = 7, VIR_DOMAIN_JOB_OPERATION_DUMP = 8, + VIR_DOMAIN_JOB_OPERATION_BACKUP = 9, # ifdef VIR_ENUM_SENTINELS VIR_DOMAIN_JOB_OPERATION_LAST @@ -3282,6 +3286,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: * @@ -4106,7 +4118,8 @@ typedef void (*virConnectDomainEventMigrationIterationCallback)(virConnectPtr co * @nparams: size of the params array * @opaque: application specific data * - * This callback occurs when a job (such as migration) running on the domain + * 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 completed * job as virDomainGetJobStats would return. The callback must not free @params * (the array will be freed once the callback finishes). @@ -4902,4 +4915,28 @@ int virDomainGetLaunchSecurityInfo(virDomainPtr domain, int *nparams, unsigned int flags); +typedef enum { + VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA = (1 << 0), /* Make checkpoint without + remembering it */ + VIR_DOMAIN_BACKUP_BEGIN_QUIESCE = (1 << 1), /* use guest agent to + quiesce all mounted + file systems within + the domain */ +} 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 = (1 << 0), /* Abandon a push model backup */ +} virDomainBackupEndFlags; + +/* Complete (or abort) an incremental backup job. */ +int virDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags); + #endif /* LIBVIRT_DOMAIN_H */ diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h index 395b710a26..9b127071c7 100644 --- a/src/driver-hypervisor.h +++ b/src/driver-hypervisor.h @@ -1363,6 +1363,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; @@ -1622,4 +1633,7 @@ struct _virHypervisorDriver { virDrvDomainCheckpointGetParent domainCheckpointGetParent; virDrvDomainCheckpointDelete domainCheckpointDelete; virDrvDomainCheckpointIsCurrent domainCheckpointIsCurrent; + virDrvDomainBackupBegin domainBackupBegin; + virDrvDomainBackupGetXMLDesc domainBackupGetXMLDesc; + virDrvDomainBackupEnd domainBackupEnd; }; diff --git a/src/qemu/qemu_blockjob.h b/src/qemu/qemu_blockjob.h index da529090ad..70438085ec 100644 --- a/src/qemu/qemu_blockjob.h +++ b/src/qemu/qemu_blockjob.h @@ -54,6 +54,7 @@ typedef enum { QEMU_BLOCKJOB_TYPE_COPY = VIR_DOMAIN_BLOCK_JOB_TYPE_COPY, QEMU_BLOCKJOB_TYPE_COMMIT = VIR_DOMAIN_BLOCK_JOB_TYPE_COMMIT, QEMU_BLOCKJOB_TYPE_ACTIVE_COMMIT = VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT, + QEMU_BLOCKJOB_TYPE_BACKUP = VIR_DOMAIN_BLOCK_JOB_TYPE_BACKUP, /* Additional enum values local to qemu */ QEMU_BLOCKJOB_TYPE_INTERNAL, QEMU_BLOCKJOB_TYPE_LAST diff --git a/examples/c/misc/event-test.c b/examples/c/misc/event-test.c index fcf4492470..98337ad185 100644 --- a/examples/c/misc/event-test.c +++ b/examples/c/misc/event-test.c @@ -891,6 +891,9 @@ blockJobTypeToStr(int type) case VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT: return "active layer block commit"; + + case VIR_DOMAIN_BLOCK_JOB_TYPE_BACKUP: + return "backup"; } return "unknown"; diff --git a/src/conf/domain_conf.c b/src/conf/domain_conf.c index 906d799d0a..10695eba41 100644 --- a/src/conf/domain_conf.c +++ b/src/conf/domain_conf.c @@ -1217,7 +1217,7 @@ VIR_ENUM_IMPL(virDomainOsDefFirmware, VIR_ENUM_DECL(virDomainBlockJob); VIR_ENUM_IMPL(virDomainBlockJob, VIR_DOMAIN_BLOCK_JOB_TYPE_LAST, - "", "", "copy", "", "active-commit", + "", "", "copy", "", "active-commit", "", ); VIR_ENUM_IMPL(virDomainMemoryModel, diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index e1fd81ede0..113cddf08b 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -102,8 +102,11 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags * * Create a new checkpoint using @xmlDesc, with a top-level - * <domaincheckpoint> element, on a running @domain. Note that @xmlDesc - * must validate against the <domaincheckpoint> XML schema. + * <domaincheckpoint> element, on a running @domain. Note that + * @xmlDesc must validate against the <domaincheckpoint> 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 <a href=formatcheckpoint.html#CheckpointAttributes">Checkpoint XML</a> * for more details on @xmlDesc. In particular, some hypervisors may require diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 2fe9bb8e91..60a5b6c446 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -10352,6 +10352,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 parameters. * + * 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 @@ -12375,3 +12381,216 @@ int virDomainGetLaunchSecurityInfo(virDomainPtr domain, virDispatchError(domain->conn); return -1; } + + +/** + * 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() because it can grab the + * state of more than one disk in parallel, and because 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 + * fails or virDomainBackupEnd() is used 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 via virDomainBackupEnd() 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 in the top-level element + * <domainbackup> , 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 to create + * a checkpoint atomically covering the same point in time as the + * backup, using @checkpointXml and forwarding flags + * VIR_DOMAIN_BACKUP_BEGIN_QUIESCE and + * VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA. 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 id is then passed to virDomainBackupGetXMLDesc() and + * virDomainBackupEnd(); it can also be obtained from + * virDomainListJobIds(). 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. + */ +int +virDomainBackupBegin(virDomainPtr domain, + const char *diskXml, + const char *checkpointXml, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "diskXml=%s, checkpointXml=%s, flags=0x%x", + NULLSTR(diskXml), NULLSTR(checkpointXml), flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn = domain->conn; + + virCheckReadOnlyGoto(conn->flags, error); + if (flags & VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA) + virCheckNonNullArgGoto(checkpointXml, error); + + if (conn->driver->domainBackupBegin) { + int ret; + ret = conn->driver->domainBackupBegin(domain, diskXml, checkpointXml, + 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 + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * 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. At present, none of + * the information provided is security sensitive. + * + * @id can either be the return value of a previous + * virDomainBackupBegin() or the value 0 to select the current backup + * job (the latter usage is an error if the hypervisor supports + * parallel jobs and has more than one running). + * + * 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=%d, flags=0x%x", id, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + virCheckNonNegativeArgGoto(id, error); + + if (conn->driver->domainBackupGetXMLDesc) { + char *ret; + ret = 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 + * @flags: bitwise-OR of supported virDomainBackupEndFlags + * + * Conclude a point-in-time backup job of the given domain. + * + * @id can either be the return value of a previous + * virDomainBackupBegin() or the value 0 to select the current backup + * job (the latter usage is an error if the hypervisor supports + * parallel jobs and has more than one running). + * + * 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=%d, flags=0x%x", id, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn = domain->conn; + + virCheckReadOnlyGoto(conn->flags, error); + virCheckNonNegativeArgGoto(id, error); + + if (conn->driver->domainBackupEnd) { + int ret; + ret = conn->driver->domainBackupEnd(domain, id, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms index 6401916a81..a1394d3ef5 100644 --- a/src/libvirt_public.syms +++ b/src/libvirt_public.syms @@ -838,6 +838,9 @@ LIBVIRT_5.5.0 { LIBVIRT_5.6.0 { global: + virDomainBackupBegin; + virDomainBackupEnd; + virDomainBackupGetXMLDesc; virDomainCheckpointCreateXML; virDomainCheckpointDelete; virDomainCheckpointFree; diff --git a/tools/virsh-domain.c b/tools/virsh-domain.c index 0b5aca4758..abc9001508 100644 --- a/tools/virsh-domain.c +++ b/tools/virsh-domain.c @@ -2562,7 +2562,9 @@ VIR_ENUM_IMPL(virshDomainBlockJob, N_("Block Pull"), N_("Block Copy"), N_("Block Commit"), - N_("Active Block Commit")); + N_("Active Block Commit"), + N_("Backup"), +); static const char * virshDomainBlockJobToString(int type) @@ -6080,7 +6082,9 @@ VIR_ENUM_IMPL(virshDomainJobOperation, N_("Outgoing migration"), N_("Snapshot"), N_("Snapshot revert"), - N_("Dump")); + N_("Dump"), + N_("Backup"), +); static const char * virshDomainJobOperationToString(int op) -- 2.20.1
On Mon, Jul 08, 2019 at 11:55:46 -0500, Eric Blake wrote:
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).
Since multiple backup jobs can be run in parallel in the future (well, qemu doesn't support it yet, but we don't want to preclude the idea), virDomainBackupBegin() returns a positive job id, and the id is also visible in the backup XML. But until a future libvirt release adds a bunch of APIs related to parallel job management where job ids will actually matter, the documentation is also clear that job id 0 means the 'currently running backup job' (provided one exists), for use in virDomainBackupGetXMLDesc() and virDomainBackupEnd().
The full list of new APIs: virDomainBackupBegin; virDomainBackupEnd; virDomainBackupGetXMLDesc;
Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> ---
[...]
@@ -2446,6 +2446,9 @@ typedef enum { * exists as long as sync is active */ VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT = 4,
+ /* Backup (virDomainBackupBegin), job exists until virDomainBackupEnd */ + VIR_DOMAIN_BLOCK_JOB_TYPE_BACKUP = 5,
As I've pointed out the last time, treating the sub-jobs of this as blockjobs does not really play well unless you treat them as such fully. That includes virDomainBlockJobAbort. That would again bring in unforseen problems e.g. with partially aborting a backup. I think we really need a new set of APIs for handling this job as a single entity.
@@ -3267,6 +3270,7 @@ typedef enum { VIR_DOMAIN_JOB_OPERATION_SNAPSHOT = 6, VIR_DOMAIN_JOB_OPERATION_SNAPSHOT_REVERT = 7, VIR_DOMAIN_JOB_OPERATION_DUMP = 8, + VIR_DOMAIN_JOB_OPERATION_BACKUP = 9,
@@ -4902,4 +4915,28 @@ int virDomainGetLaunchSecurityInfo(virDomainPtr domain, int *nparams, unsigned int flags);
+typedef enum { + VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA = (1 << 0), /* Make checkpoint without + remembering it */
This also should not exist in the first place. You want to start a NBD server and forget about it?!?
+ VIR_DOMAIN_BACKUP_BEGIN_QUIESCE = (1 << 1), /* use guest agent to + quiesce all mounted + file systems within + the domain */
[...]
diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index e1fd81ede0..113cddf08b 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -102,8 +102,11 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags * * Create a new checkpoint using @xmlDesc, with a top-level - * <domaincheckpoint> element, on a running @domain. Note that @xmlDesc - * must validate against the <domaincheckpoint> XML schema. + * <domaincheckpoint> element, on a running @domain. Note that + * @xmlDesc must validate against the <domaincheckpoint> 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 <a href=formatcheckpoint.html#CheckpointAttributes">Checkpoint XML</a> * for more details on @xmlDesc. In particular, some hypervisors may require diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 2fe9bb8e91..60a5b6c446 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -10352,6 +10352,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 parameters. * + * 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().
Drop this paragraph. Block copy has different semantics.
+ * * Returns 0 if the operation has started, -1 on failure. */ int @@ -12375,3 +12381,216 @@ int virDomainGetLaunchSecurityInfo(virDomainPtr domain, virDispatchError(domain->conn); return -1; } + + +/** + * 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
qemuism
+ * 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() because it can grab the + * state of more than one disk in parallel, and because the state is + * captured as of the start of the job, rather than the end.
The semantics are different ...
+ * + * 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 virDomainBackupEnd() is used 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
qemuism
+ * 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 via virDomainBackupEnd() 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 in the top-level element + * <domainbackup> , 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.
I don't think this transfers properly ...
+ * + * 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, using @checkpointXml and forwarding flags + * VIR_DOMAIN_BACKUP_BEGIN_QUIESCE and + * VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA. 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 id is then passed to virDomainBackupGetXMLDesc() and + * virDomainBackupEnd(); it can also be obtained from + * virDomainListJobIds(). 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. + */
[...]
This one is fairly straightforward - the generator already does what we need. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> --- src/remote/remote_driver.c | 3 ++ src/remote/remote_protocol.x | 53 +++++++++++++++++++++++++++++++++++- src/remote_protocol-structs | 28 +++++++++++++++++++ 3 files changed, 83 insertions(+), 1 deletion(-) diff --git a/src/remote/remote_driver.c b/src/remote/remote_driver.c index 9145aa91ff..0c54caf31b 100644 --- a/src/remote/remote_driver.c +++ b/src/remote/remote_driver.c @@ -8597,6 +8597,9 @@ static virHypervisorDriver hypervisor_driver = { .domainCheckpointGetParent = remoteDomainCheckpointGetParent, /* 5.6.0 */ .domainCheckpointDelete = remoteDomainCheckpointDelete, /* 5.6.0 */ .domainCheckpointIsCurrent = remoteDomainCheckpointIsCurrent, /* 5.6.0 */ + .domainBackupBegin = remoteDomainBackupBegin, /* 5.6.0 */ + .domainBackupGetXMLDesc = remoteDomainBackupGetXMLDesc, /* 5.6.0 */ + .domainBackupEnd = remoteDomainBackupEnd, /* 5.6.0 */ }; static virNetworkDriver network_driver = { diff --git a/src/remote/remote_protocol.x b/src/remote/remote_protocol.x index a2bd30360f..06f2b41a63 100644 --- a/src/remote/remote_protocol.x +++ b/src/remote/remote_protocol.x @@ -3732,6 +3732,37 @@ struct remote_domain_checkpoint_delete_args { 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 id; +}; + +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. -----*/ /* Define the program number, protocol version and procedure numbers here. */ @@ -6595,10 +6626,30 @@ enum remote_procedure { */ REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 417, + /** + * @generate: both + * @acl: domain:checkpoint + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT = 418, + + /** + * @generate: both + * @acl: domain:checkpoint + * @acl: domain:block_write + * @acl: domain:fs_freeze:VIR_DOMAIN_BACKUP_BEGIN_QUIESCE + */ + REMOTE_PROC_DOMAIN_BACKUP_BEGIN = 419, + /** * @generate: both * @priority: high * @acl: domain:read */ - REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT = 418 + REMOTE_PROC_DOMAIN_BACKUP_GET_XML_DESC = 420, + + /** + * @generate: both + * @acl: domain:checkpoint + */ + REMOTE_PROC_DOMAIN_BACKUP_END = 421 }; diff --git a/src/remote_protocol-structs b/src/remote_protocol-structs index ba4337b1bd..535ed2c484 100644 --- a/src/remote_protocol-structs +++ b/src/remote_protocol-structs @@ -3112,6 +3112,31 @@ 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 id; +}; +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 = 1, REMOTE_PROC_CONNECT_CLOSE = 2, @@ -3531,4 +3556,7 @@ enum remote_procedure { REMOTE_PROC_DOMAIN_CHECKPOINT_GET_PARENT = 416, REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 417, REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT = 418, + REMOTE_PROC_DOMAIN_BACKUP_BEGIN = 419, + REMOTE_PROC_DOMAIN_BACKUP_GET_XML_DESC = 420, + REMOTE_PROC_DOMAIN_BACKUP_END = 421, }; -- 2.20.1
Accept XML describing a generic block job, and output it again as needed. This may still need a few tweaks to match the documented XML and RNG schema. Signed-off-by: Eric Blake <eblake@redhat.com> --- src/conf/backup_conf.h | 94 +++++++ src/conf/virconftypes.h | 3 + src/conf/Makefile.inc.am | 2 + src/conf/backup_conf.c | 546 +++++++++++++++++++++++++++++++++++++++ src/libvirt_private.syms | 8 +- 5 files changed, 652 insertions(+), 1 deletion(-) create mode 100644 src/conf/backup_conf.h create mode 100644 src/conf/backup_conf.c diff --git a/src/conf/backup_conf.h b/src/conf/backup_conf.h new file mode 100644 index 0000000000..1714315a1f --- /dev/null +++ b/src/conf/backup_conf.h @@ -0,0 +1,94 @@ +/* + * backup_conf.h: domain backup XML processing + * (based on domain_conf.h) + * + * Copyright (C) 2006-2019 Red Hat, Inc. + * Copyright (C) 2006-2008 Daniel P. Berrange + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see + * <http://www.gnu.org/licenses/>. + */ + +#pragma once + +#include "internal.h" +#include "domain_conf.h" +#include "moment_conf.h" +#include "virenum.h" + +/* Items related to incremental backup state */ + +typedef enum { + VIR_DOMAIN_BACKUP_TYPE_DEFAULT = 0, + VIR_DOMAIN_BACKUP_TYPE_PUSH, + VIR_DOMAIN_BACKUP_TYPE_PULL, + + VIR_DOMAIN_BACKUP_TYPE_LAST +} virDomainBackupType; + +typedef enum { + VIR_DOMAIN_BACKUP_DISK_STATE_DEFAULT = 0, /* Initial */ + VIR_DOMAIN_BACKUP_DISK_STATE_CREATED, /* File created */ + VIR_DOMAIN_BACKUP_DISK_STATE_LABEL, /* Security labels applied */ + VIR_DOMAIN_BACKUP_DISK_STATE_READY, /* Handed to guest */ + VIR_DOMAIN_BACKUP_DISK_STATE_BITMAP, /* Associated temp bitmap created */ + VIR_DOMAIN_BACKUP_DISK_STATE_EXPORT, /* NBD export created */ + VIR_DOMAIN_BACKUP_DISK_STATE_COMPLETE, /* Push job finished */ +} virDomainBackupDiskState; + +/* Stores disk-backup information */ +typedef struct _virDomainBackupDiskDef virDomainBackupDiskDef; +typedef virDomainBackupDiskDef *virDomainBackupDiskDefPtr; +struct _virDomainBackupDiskDef { + char *name; /* name matching the <target dev='...' of the domain */ + int idx; /* index within checkpoint->dom->disks that matches name */ + + /* details of target for push-mode, or of the scratch file for pull-mode */ + virStorageSourcePtr store; + int state; /* virDomainBackupDiskState, not stored in XML */ +}; + +/* Stores the complete backup metadata */ +typedef struct _virDomainBackupDef virDomainBackupDef; +typedef virDomainBackupDef *virDomainBackupDefPtr; +struct _virDomainBackupDef { + /* Public XML. */ + int type; /* virDomainBackupType */ + int id; + char *incremental; + virStorageNetHostDefPtr server; /* only when type == PULL */ + + size_t ndisks; /* should not exceed dom->ndisks */ + virDomainBackupDiskDef *disks; +}; + +VIR_ENUM_DECL(virDomainBackup); + +typedef enum { + VIR_DOMAIN_BACKUP_PARSE_INTERNAL = 1 << 0, +} virDomainBackupParseFlags; + +virDomainBackupDefPtr virDomainBackupDefParseString(const char *xmlStr, + virDomainXMLOptionPtr xmlopt, + unsigned int flags); +virDomainBackupDefPtr virDomainBackupDefParseNode(xmlDocPtr xml, + xmlNodePtr root, + virDomainXMLOptionPtr xmlopt, + unsigned int flags); +void virDomainBackupDefFree(virDomainBackupDefPtr def); +int virDomainBackupDefFormat(virBufferPtr buf, + virDomainBackupDefPtr def, + bool internal); +int virDomainBackupAlignDisks(virDomainBackupDefPtr backup, + virDomainDefPtr dom, const char *suffix); diff --git a/src/conf/virconftypes.h b/src/conf/virconftypes.h index e8e9b6c314..d6e5fe5c49 100644 --- a/src/conf/virconftypes.h +++ b/src/conf/virconftypes.h @@ -93,6 +93,9 @@ typedef virDomainABIStability *virDomainABIStabilityPtr; typedef struct _virDomainActualNetDef virDomainActualNetDef; typedef virDomainActualNetDef *virDomainActualNetDefPtr; +typedef struct _virDomainBackupDef virDomainBackupDef; +typedef virDomainBackupDef *virDomainBackupDefPtr; + typedef struct _virDomainBIOSDef virDomainBIOSDef; typedef virDomainBIOSDef *virDomainBIOSDefPtr; diff --git a/src/conf/Makefile.inc.am b/src/conf/Makefile.inc.am index b72ebbbda5..6913a5c5d8 100644 --- a/src/conf/Makefile.inc.am +++ b/src/conf/Makefile.inc.am @@ -12,6 +12,8 @@ NETDEV_CONF_SOURCES = \ $(NULL) DOMAIN_CONF_SOURCES = \ + conf/backup_conf.c \ + conf/backup_conf.h \ conf/capabilities.c \ conf/capabilities.h \ conf/checkpoint_conf.c \ diff --git a/src/conf/backup_conf.c b/src/conf/backup_conf.c new file mode 100644 index 0000000000..2bd94c1d73 --- /dev/null +++ b/src/conf/backup_conf.c @@ -0,0 +1,546 @@ +/* + * backup_conf.c: domain backup XML processing + * + * Copyright (C) 2006-2019 Red Hat, Inc. + * Copyright (C) 2006-2008 Daniel P. Berrange + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see + * <http://www.gnu.org/licenses/>. + */ + +#include <config.h> + +#include "internal.h" +#include "virbitmap.h" +#include "virbuffer.h" +#include "datatypes.h" +#include "domain_conf.h" +#include "virlog.h" +#include "viralloc.h" +#include "backup_conf.h" +#include "virstoragefile.h" +#include "viruuid.h" +#include "virfile.h" +#include "virerror.h" +#include "virxml.h" +#include "virstring.h" + +#define VIR_FROM_THIS VIR_FROM_DOMAIN + +VIR_LOG_INIT("conf.backup_conf"); + +VIR_ENUM_IMPL(virDomainBackup, + VIR_DOMAIN_BACKUP_TYPE_LAST, + "default", "push", "pull"); + +static void +virDomainBackupDiskDefClear(virDomainBackupDiskDefPtr disk) +{ + VIR_FREE(disk->name); + virStorageSourceClear(disk->store); + disk->store = NULL; +} + +void +virDomainBackupDefFree(virDomainBackupDefPtr def) +{ + size_t i; + + if (!def) + return; + + VIR_FREE(def->incremental); + virStorageNetHostDefFree(1, def->server); + for (i = 0; i < def->ndisks; i++) + virDomainBackupDiskDefClear(&def->disks[i]); + VIR_FREE(def->disks); + VIR_FREE(def); +} + +static int +virDomainBackupDiskDefParseXML(xmlNodePtr node, + xmlXPathContextPtr ctxt, + virDomainBackupDiskDefPtr def, + bool push, bool internal, + virDomainXMLOptionPtr xmlopt) +{ + int ret = -1; + // char *backup = NULL; /* backup="yes|no"? */ + char *type = NULL; + char *driver = NULL; + xmlNodePtr cur; + xmlNodePtr saved = ctxt->node; + + ctxt->node = node; + + if (VIR_ALLOC(def->store) < 0) + goto cleanup; + + def->name = virXMLPropString(node, "name"); + if (!def->name) { + virReportError(VIR_ERR_INTERNAL_ERROR, "%s", + _("missing name from disk backup element")); + goto cleanup; + } + + /* Needed? A way for users to list a disk and explicitly mark it + * as not participating, and then output shows all disks rather + * than just active disks */ +#if 0 + backup = virXMLPropString(node, "backup"); + if (backup) { + def->type = virDomainCheckpointTypeFromString(checkpoint); + if (def->type <= 0) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("unknown disk checkpoint setting '%s'"), + checkpoint); + goto cleanup; + } + } +#endif + + if ((type = virXMLPropString(node, "type"))) { + if ((def->store->type = virStorageTypeFromString(type)) <= 0 || + def->store->type == VIR_STORAGE_TYPE_VOLUME || + def->store->type == VIR_STORAGE_TYPE_DIR) { + virReportError(VIR_ERR_XML_ERROR, + _("unknown disk backup type '%s'"), type); + goto cleanup; + } + } else { + def->store->type = VIR_STORAGE_TYPE_FILE; + } + + if ((cur = virXPathNode(push ? "./target" : "./scratch", ctxt)) && + virDomainStorageSourceParse(cur, ctxt, def->store, 0, xmlopt) < 0) + goto cleanup; + + if (internal) { + int detected; + if (virXPathInt("string(./node/@detected)", ctxt, &detected) < 0) + goto cleanup; + def->store->detected = detected; + def->store->nodeformat = virXPathString("string(./node)", ctxt); + } + + if ((driver = virXPathString("string(./driver/@type)", ctxt))) { + def->store->format = virStorageFileFormatTypeFromString(driver); + if (def->store->format <= 0) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("unknown disk backup driver '%s'"), driver); + goto cleanup; + } else if (!push && def->store->format != VIR_STORAGE_FILE_QCOW2) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("pull mode requires qcow2 driver, not '%s'"), + driver); + goto cleanup; + } + } + + /* validate that the passed path is absolute */ + if (virStorageSourceIsRelative(def->store)) { + virReportError(VIR_ERR_XML_ERROR, + _("disk backup image path '%s' must be absolute"), + def->store->path); + goto cleanup; + } + + ret = 0; + cleanup: + ctxt->node = saved; + + VIR_FREE(driver); +// VIR_FREE(backup); + VIR_FREE(type); + if (ret < 0) + virDomainBackupDiskDefClear(def); + return ret; +} + +static virDomainBackupDefPtr +virDomainBackupDefParse(xmlXPathContextPtr ctxt, + virDomainXMLOptionPtr xmlopt, + unsigned int flags) +{ + virDomainBackupDefPtr def = NULL; + virDomainBackupDefPtr ret = NULL; + xmlNodePtr *nodes = NULL; + xmlNodePtr node = NULL; + char *mode = NULL; + bool push; + size_t i; + int n; + + if (VIR_ALLOC(def) < 0) + goto cleanup; + + mode = virXMLPropString(ctxt->node, "mode"); + if (mode) { + def->type = virDomainBackupTypeFromString(mode); + if (def->type <= 0) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("unknown backup mode '%s'"), mode); + goto cleanup; + } + } else { + def->type = VIR_DOMAIN_BACKUP_TYPE_PUSH; + } + push = def->type == VIR_DOMAIN_BACKUP_TYPE_PUSH; + + if (flags & VIR_DOMAIN_BACKUP_PARSE_INTERNAL) { + char *tmp = virXMLPropString(ctxt->node, "id"); + if (tmp && virStrToLong_i(tmp, NULL, 10, &def->id) < 0) { + virReportError(VIR_ERR_XML_ERROR, + _("invalid 'id' value '%s'"), tmp); + VIR_FREE(tmp); + goto cleanup; + } + VIR_FREE(tmp); + } + + def->incremental = virXPathString("string(./incremental)", ctxt); + + node = virXPathNode("./server", ctxt); + if (node) { + if (def->type != VIR_DOMAIN_BACKUP_TYPE_PULL) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("use of <server> requires pull mode backup")); + goto cleanup; + } + if (VIR_ALLOC(def->server) < 0) + goto cleanup; + if (virDomainStorageNetworkParseHost(node, def->server) < 0) + goto cleanup; + if (def->server->transport == VIR_STORAGE_NET_HOST_TRANS_RDMA) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("transport rdma is not supported for <server>")); + goto cleanup; + } + if (def->server->transport == VIR_STORAGE_NET_HOST_TRANS_UNIX && + def->server->socket[0] != '/') { + virReportError(VIR_ERR_XML_ERROR, + _("backup socket path '%s' must be absolute"), + def->server->socket); + goto cleanup; + } + } + + if ((n = virXPathNodeSet("./disks/*", ctxt, &nodes)) < 0) + goto cleanup; + if (n && VIR_ALLOC_N(def->disks, n) < 0) + goto cleanup; + def->ndisks = n; + for (i = 0; i < def->ndisks; i++) { + if (virDomainBackupDiskDefParseXML(nodes[i], ctxt, + &def->disks[i], push, + flags & VIR_DOMAIN_BACKUP_PARSE_INTERNAL, + xmlopt) < 0) + goto cleanup; + } + VIR_FREE(nodes); + + VIR_STEAL_PTR(ret, def); + + cleanup: + VIR_FREE(mode); + VIR_FREE(nodes); + virDomainBackupDefFree(def); + + return ret; +} + +virDomainBackupDefPtr +virDomainBackupDefParseString(const char *xmlStr, + virDomainXMLOptionPtr xmlopt, + unsigned int flags) +{ + virDomainBackupDefPtr ret = NULL; + xmlDocPtr xml; + int keepBlanksDefault = xmlKeepBlanksDefault(0); + + if ((xml = virXMLParse(NULL, xmlStr, _("(domain_backup)")))) { + xmlKeepBlanksDefault(keepBlanksDefault); + ret = virDomainBackupDefParseNode(xml, xmlDocGetRootElement(xml), + xmlopt, flags); + xmlFreeDoc(xml); + } + xmlKeepBlanksDefault(keepBlanksDefault); + + return ret; +} + +virDomainBackupDefPtr +virDomainBackupDefParseNode(xmlDocPtr xml, + xmlNodePtr root, + virDomainXMLOptionPtr xmlopt, + unsigned int flags) +{ + xmlXPathContextPtr ctxt = NULL; + virDomainBackupDefPtr def = NULL; + + if (!virXMLNodeNameEqual(root, "domainbackup")) { + virReportError(VIR_ERR_XML_ERROR, "%s", _("domainbackup")); + goto cleanup; + } + + ctxt = xmlXPathNewContext(xml); + if (ctxt == NULL) { + virReportOOMError(); + goto cleanup; + } + + ctxt->node = root; + def = virDomainBackupDefParse(ctxt, xmlopt, flags); + cleanup: + xmlXPathFreeContext(ctxt); + return def; +} + +static int +virDomainBackupDiskDefFormat(virBufferPtr buf, + virDomainBackupDiskDefPtr disk, + bool push, bool internal) +{ + int type = disk->store->type; + virBuffer attrBuf = VIR_BUFFER_INITIALIZER; + virBuffer childBuf = VIR_BUFFER_INITIALIZER; + int ret = -1; + + if (!disk->name) + return 0; + + virBufferEscapeString(buf, "<disk name='%s'", disk->name); + /* TODO: per-disk backup=off? */ + + virBufferAsprintf(buf, " type='%s'>\n", virStorageTypeToString(type)); + virBufferAdjustIndent(buf, 2); + + if (disk->store->format > 0) + virBufferEscapeString(buf, "<driver type='%s'/>\n", + virStorageFileFormatTypeToString(disk->store->format)); + /* TODO: should node names be part of storage file xml, rather + * than a one-off hack for qemu? */ + if (internal) { + virBufferEscapeString(buf, "<node detected='%s'", + disk->store->detected ? "1" : "0"); + virBufferEscapeString(buf, ">%s</node>\n", disk->store->nodeformat); + } + + if (virDomainDiskSourceFormat(buf, disk->store, push ? "target" : "scratch", + 0, false, 0, NULL) < 0) + goto cleanup; + virBufferAdjustIndent(buf, -2); + virBufferAddLit(buf, "</disk>\n"); + + ret = 0; + + cleanup: + virBufferFreeAndReset(&attrBuf); + virBufferFreeAndReset(&childBuf); + return ret; +} + +int +virDomainBackupDefFormat(virBufferPtr buf, virDomainBackupDefPtr def, + bool internal) +{ + size_t i; + + virBufferAsprintf(buf, "<domainbackup mode='%s'", + virDomainBackupTypeToString(def->type)); + if (def->id) + virBufferAsprintf(buf, " id='%d'", def->id); + virBufferAddLit(buf, ">\n"); + virBufferAdjustIndent(buf, 2); + + virBufferEscapeString(buf, "<incremental>%s</incremental>\n", + def->incremental); + if (def->server) { + virBufferAsprintf(buf, "<server transport='%s'", + virStorageNetHostTransportTypeToString(def->server->transport)); + virBufferEscapeString(buf, " name='%s'", def->server->name); + if (def->server->port) + virBufferAsprintf(buf, " port='%u'", def->server->port); + virBufferEscapeString(buf, " socket='%s'", def->server->socket); + virBufferAddLit(buf, "/>\n"); + } + + if (def->ndisks) { + virBufferAddLit(buf, "<disks>\n"); + virBufferAdjustIndent(buf, 2); + for (i = 0; i < def->ndisks; i++) { + if (!def->disks[i].store) + continue; + if (virDomainBackupDiskDefFormat(buf, &def->disks[i], + def->type == VIR_DOMAIN_BACKUP_TYPE_PUSH, + internal) < 0) + return -1; + } + virBufferAdjustIndent(buf, -2); + virBufferAddLit(buf, "</disks>\n"); + } + + virBufferAdjustIndent(buf, -2); + virBufferAddLit(buf, "</domainbackup>\n"); + + return virBufferCheckError(buf); +} + + +static int +virDomainBackupCompareDiskIndex(const void *a, const void *b) +{ + const virDomainBackupDiskDef *diska = a; + const virDomainBackupDiskDef *diskb = b; + + /* Integer overflow shouldn't be a problem here. */ + return diska->idx - diskb->idx; +} + +static int +virDomainBackupDefAssignStore(virDomainBackupDiskDefPtr disk, + virStorageSourcePtr src, + const char *suffix) +{ + int ret = -1; + + if (virStorageSourceIsEmpty(src)) { + if (disk->store) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("disk '%s' has no media"), disk->name); + goto cleanup; + } + } else if (src->readonly && disk->store) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("backup of readonly disk '%s' makes no sense"), + disk->name); + goto cleanup; + } else if (!disk->store) { + if (virStorageSourceGetActualType(src) == VIR_STORAGE_TYPE_FILE) { + if (VIR_ALLOC(disk->store) < 0) + goto cleanup; + disk->store->type = VIR_STORAGE_TYPE_FILE; + if (virAsprintf(&disk->store->path, "%s.%s", src->path, + suffix) < 0) + goto cleanup; + disk->store->detected = true; + } else { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("refusing to generate file name for disk '%s'"), + disk->name); + goto cleanup; + } + } + ret = 0; + cleanup: + return ret; +} + +/* Align def->disks to domain. Sort the list of def->disks, + * generating storage names using suffix as needed. Convert paths to + * disk targets for uniformity. Issue an error and return -1 if any + * def->disks[n]->name appears more than once or does not map to + * dom->disks. */ +int +virDomainBackupAlignDisks(virDomainBackupDefPtr def, virDomainDefPtr dom, + const char *suffix) +{ + int ret = -1; + virBitmapPtr map = NULL; + size_t i; + int ndisks; + bool alloc_all = false; + + if (def->ndisks > dom->ndisks) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("too many disk backup requests for domain")); + goto cleanup; + } + + /* Unlikely to have a guest without disks but technically possible. */ + if (!dom->ndisks) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("domain must have at least one disk to perform " + "backups")); + goto cleanup; + } + + if (!(map = virBitmapNew(dom->ndisks))) + goto cleanup; + + /* Double check requested disks. */ + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDefPtr disk = &def->disks[i]; + int idx = virDomainDiskIndexByName(dom, disk->name, false); + + if (idx < 0) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("no disk named '%s'"), disk->name); + goto cleanup; + } + + if (virBitmapIsBitSet(map, idx)) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("disk '%s' specified twice"), + disk->name); + goto cleanup; + } + ignore_value(virBitmapSetBit(map, idx)); + disk->idx = idx; + + if (STRNEQ(disk->name, dom->disks[idx]->dst)) { + VIR_FREE(disk->name); + if (VIR_STRDUP(disk->name, dom->disks[idx]->dst) < 0) + goto cleanup; + } + if (disk->store && !disk->store->path) { + virStorageSourceClear(disk->store); + disk->store = NULL; + } + if (virDomainBackupDefAssignStore(disk, dom->disks[idx]->src, + suffix) < 0) + goto cleanup; + } + + /* Provide fillers for all remaining disks, for easier iteration. */ + if (!def->ndisks) + alloc_all = true; + ndisks = def->ndisks; + if (VIR_EXPAND_N(def->disks, def->ndisks, + dom->ndisks - def->ndisks) < 0) + goto cleanup; + + for (i = 0; i < dom->ndisks; i++) { + virDomainBackupDiskDefPtr disk; + + if (virBitmapIsBitSet(map, i)) + continue; + disk = &def->disks[ndisks++]; + if (VIR_STRDUP(disk->name, dom->disks[i]->dst) < 0) + goto cleanup; + disk->idx = i; + if (alloc_all && + virDomainBackupDefAssignStore(disk, dom->disks[i]->src, suffix) < 0) + goto cleanup; + } + + qsort(&def->disks[0], def->ndisks, sizeof(def->disks[0]), + virDomainBackupCompareDiskIndex); + + ret = 0; + + cleanup: + virBitmapFree(map); + return ret; +} diff --git a/src/libvirt_private.syms b/src/libvirt_private.syms index 28f654bbf8..de25aa05ed 100644 --- a/src/libvirt_private.syms +++ b/src/libvirt_private.syms @@ -70,6 +70,13 @@ virCapabilitiesSetNetPrefix; # conf/checkpoint_conf.h +virDomainBackupAlignDisks; +virDomainBackupDefFormat; +virDomainBackupDefFree; +virDomainBackupDefParseNode; +virDomainBackupDefParseString; +virDomainBackupTypeFromString; +virDomainBackupTypeToString; virDomainCheckpointAlignDisks; virDomainCheckpointDefFormat; virDomainCheckpointDefNew; @@ -79,7 +86,6 @@ virDomainCheckpointRedefinePrep; virDomainCheckpointTypeFromString; virDomainCheckpointTypeToString; - # conf/cpu_conf.h virCPUCacheModeTypeFromString; virCPUCacheModeTypeToString; -- 2.20.1
On Mon, Jul 08, 2019 at 11:55:48 -0500, Eric Blake wrote:
Accept XML describing a generic block job, and output it again as needed. This may still need a few tweaks to match the documented XML and RNG schema.
Signed-off-by: Eric Blake <eblake@redhat.com> ---
[...]
diff --git a/src/conf/backup_conf.h b/src/conf/backup_conf.h new file mode 100644 index 0000000000..1714315a1f --- /dev/null +++ b/src/conf/backup_conf.h @@ -0,0 +1,94 @@
[...]
+/* Stores disk-backup information */ +typedef struct _virDomainBackupDiskDef virDomainBackupDiskDef; +typedef virDomainBackupDiskDef *virDomainBackupDiskDefPtr; +struct _virDomainBackupDiskDef { + char *name; /* name matching the <target dev='...' of the domain */ + int idx; /* index within checkpoint->dom->disks that matches name */ + + /* details of target for push-mode, or of the scratch file for pull-mode */ + virStorageSourcePtr store; + int state; /* virDomainBackupDiskState, not stored in XML */ +}; + +/* Stores the complete backup metadata */ +typedef struct _virDomainBackupDef virDomainBackupDef; +typedef virDomainBackupDef *virDomainBackupDefPtr; +struct _virDomainBackupDef { + /* Public XML. */ + int type; /* virDomainBackupType */ + int id; + char *incremental; + virStorageNetHostDefPtr server; /* only when type == PULL */ + + size_t ndisks; /* should not exceed dom->ndisks */ + virDomainBackupDiskDef *disks; +};
[...]
diff --git a/src/conf/backup_conf.c b/src/conf/backup_conf.c new file mode 100644 index 0000000000..2bd94c1d73 --- /dev/null +++ b/src/conf/backup_conf.c @@ -0,0 +1,546 @@
[...]
+static void +virDomainBackupDiskDefClear(virDomainBackupDiskDefPtr disk) +{ + VIR_FREE(disk->name); + virStorageSourceClear(disk->store); + disk->store = NULL;
This leaks disk->store
+}
[...]
+static int +virDomainBackupDiskDefParseXML(xmlNodePtr node, + xmlXPathContextPtr ctxt, + virDomainBackupDiskDefPtr def, + bool push, bool internal, + virDomainXMLOptionPtr xmlopt) +{ + int ret = -1; + // char *backup = NULL; /* backup="yes|no"? */ + char *type = NULL; + char *driver = NULL; + xmlNodePtr cur; + xmlNodePtr saved = ctxt->node; + + ctxt->node = node; + + if (VIR_ALLOC(def->store) < 0)
virStorageSource MUST be allocated using virStorageSourceNew since it's an virObject
+ goto cleanup; + + def->name = virXMLPropString(node, "name"); + if (!def->name) { + virReportError(VIR_ERR_INTERNAL_ERROR, "%s", + _("missing name from disk backup element")); + goto cleanup; + } + + /* Needed? A way for users to list a disk and explicitly mark it + * as not participating, and then output shows all disks rather + * than just active disks */ +#if 0
...
+ backup = virXMLPropString(node, "backup"); + if (backup) { + def->type = virDomainCheckpointTypeFromString(checkpoint); + if (def->type <= 0) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("unknown disk checkpoint setting '%s'"), + checkpoint); + goto cleanup; + } + } +#endif + + if ((type = virXMLPropString(node, "type"))) { + if ((def->store->type = virStorageTypeFromString(type)) <= 0 || + def->store->type == VIR_STORAGE_TYPE_VOLUME || + def->store->type == VIR_STORAGE_TYPE_DIR) { + virReportError(VIR_ERR_XML_ERROR, + _("unknown disk backup type '%s'"), type); + goto cleanup; + } + } else { + def->store->type = VIR_STORAGE_TYPE_FILE; + } + + if ((cur = virXPathNode(push ? "./target" : "./scratch", ctxt)) && + virDomainStorageSourceParse(cur, ctxt, def->store, 0, xmlopt) < 0) + goto cleanup; + + if (internal) { + int detected; + if (virXPathInt("string(./node/@detected)", ctxt, &detected) < 0) + goto cleanup; + def->store->detected = detected; + def->store->nodeformat = virXPathString("string(./node)", ctxt); + } + + if ((driver = virXPathString("string(./driver/@type)", ctxt))) { + def->store->format = virStorageFileFormatTypeFromString(driver); + if (def->store->format <= 0) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("unknown disk backup driver '%s'"), driver); + goto cleanup; + } else if (!push && def->store->format != VIR_STORAGE_FILE_QCOW2) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("pull mode requires qcow2 driver, not '%s'"),
Why is this qemuism validated in the main parser?
+ driver); + goto cleanup; + } + } + + /* validate that the passed path is absolute */ + if (virStorageSourceIsRelative(def->store)) { + virReportError(VIR_ERR_XML_ERROR, + _("disk backup image path '%s' must be absolute"), + def->store->path); + goto cleanup; + } + + ret = 0; + cleanup: + ctxt->node = saved; + + VIR_FREE(driver); +// VIR_FREE(backup);
...
+ VIR_FREE(type); + if (ret < 0) + virDomainBackupDiskDefClear(def); + return ret; +}
[...]
+static int +virDomainBackupDiskDefFormat(virBufferPtr buf, + virDomainBackupDiskDefPtr disk, + bool push, bool internal) +{ + int type = disk->store->type; + virBuffer attrBuf = VIR_BUFFER_INITIALIZER; + virBuffer childBuf = VIR_BUFFER_INITIALIZER; + int ret = -1; + + if (!disk->name) + return 0; + + virBufferEscapeString(buf, "<disk name='%s'", disk->name); + /* TODO: per-disk backup=off? */ + + virBufferAsprintf(buf, " type='%s'>\n", virStorageTypeToString(type)); + virBufferAdjustIndent(buf, 2); + + if (disk->store->format > 0) + virBufferEscapeString(buf, "<driver type='%s'/>\n", + virStorageFileFormatTypeToString(disk->store->format)); + /* TODO: should node names be part of storage file xml, rather + * than a one-off hack for qemu? */ + if (internal) { + virBufferEscapeString(buf, "<node detected='%s'", + disk->store->detected ? "1" : "0"); + virBufferEscapeString(buf, ">%s</node>\n", disk->store->nodeformat);
private data?
+ } + + if (virDomainDiskSourceFormat(buf, disk->store, push ? "target" : "scratch", + 0, false, 0, NULL) < 0) + goto cleanup; + virBufferAdjustIndent(buf, -2); + virBufferAddLit(buf, "</disk>\n"); + + ret = 0; + + cleanup: + virBufferFreeAndReset(&attrBuf); + virBufferFreeAndReset(&childBuf); + return ret; +} +
[...]
+static int +virDomainBackupDefAssignStore(virDomainBackupDiskDefPtr disk, + virStorageSourcePtr src, + const char *suffix) +{ + int ret = -1;
Please note in the comment that disk->store is used to switch behaviour when all_disks is true.
+ + if (virStorageSourceIsEmpty(src)) { + if (disk->store) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("disk '%s' has no media"), disk->name); + goto cleanup; + } + } else if (src->readonly && disk->store) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("backup of readonly disk '%s' makes no sense"), + disk->name); + goto cleanup; + } else if (!disk->store) { + if (virStorageSourceGetActualType(src) == VIR_STORAGE_TYPE_FILE) { + if (VIR_ALLOC(disk->store) < 0)
virStorageSourceNew.
+ goto cleanup; + disk->store->type = VIR_STORAGE_TYPE_FILE; + if (virAsprintf(&disk->store->path, "%s.%s", src->path, + suffix) < 0) + goto cleanup; + disk->store->detected = true;
I already commented once that this should not be abused.
+ } else { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("refusing to generate file name for disk '%s'"), + disk->name); + goto cleanup; + } + } + ret = 0; + cleanup: + return ret; +} + +/* Align def->disks to domain. Sort the list of def->disks, + * generating storage names using suffix as needed. Convert paths to + * disk targets for uniformity. Issue an error and return -1 if any + * def->disks[n]->name appears more than once or does not map to + * dom->disks. */ +int +virDomainBackupAlignDisks(virDomainBackupDefPtr def, virDomainDefPtr dom, + const char *suffix) +{ + int ret = -1; + virBitmapPtr map = NULL; + size_t i; + int ndisks; + bool alloc_all = false; + + if (def->ndisks > dom->ndisks) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("too many disk backup requests for domain")); + goto cleanup; + } + + /* Unlikely to have a guest without disks but technically possible. */ + if (!dom->ndisks) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("domain must have at least one disk to perform " + "backups")); + goto cleanup; + } + + if (!(map = virBitmapNew(dom->ndisks))) + goto cleanup; + + /* Double check requested disks. */ + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDefPtr disk = &def->disks[i]; + int idx = virDomainDiskIndexByName(dom, disk->name, false); + + if (idx < 0) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("no disk named '%s'"), disk->name); + goto cleanup; + } + + if (virBitmapIsBitSet(map, idx)) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("disk '%s' specified twice"), + disk->name); + goto cleanup; + } + ignore_value(virBitmapSetBit(map, idx)); + disk->idx = idx; + + if (STRNEQ(disk->name, dom->disks[idx]->dst)) { + VIR_FREE(disk->name); + if (VIR_STRDUP(disk->name, dom->disks[idx]->dst) < 0) + goto cleanup; + } + if (disk->store && !disk->store->path) { + virStorageSourceClear(disk->store); + disk->store = NULL;
This will leak disk->store.
+ } + if (virDomainBackupDefAssignStore(disk, dom->disks[idx]->src, + suffix) < 0) + goto cleanup; + } + + /* Provide fillers for all remaining disks, for easier iteration. */ + if (!def->ndisks) + alloc_all = true; + ndisks = def->ndisks; + if (VIR_EXPAND_N(def->disks, def->ndisks, + dom->ndisks - def->ndisks) < 0) + goto cleanup; + + for (i = 0; i < dom->ndisks; i++) { + virDomainBackupDiskDefPtr disk; + + if (virBitmapIsBitSet(map, i)) + continue; + disk = &def->disks[ndisks++]; + if (VIR_STRDUP(disk->name, dom->disks[i]->dst) < 0) + goto cleanup;
Introduce a few more new virsh commands for performing backup jobs. At this time, I did not opt for a convenience command 'backup-begin-as' that cobbles together appropriate XML from the user's command line arguments, but that may be a viable future extension. Similarly, since backup is a potentially long-running operation, it might be nice to add some sugar that automatically handles waiting for the job to end, rather than making the user have to poll or figure out virsh event to do the same. Eventually, we will also need a way to create a checkpoint atomically with an external snapshot. Signed-off-by: Eric Blake <eblake@redhat.com> --- tools/virsh-domain.c | 245 +++++++++++++++++++++++++++++++++++++++++++ tools/virsh.pod | 49 +++++++++ 2 files changed, 294 insertions(+) diff --git a/tools/virsh-domain.c b/tools/virsh-domain.c index abc9001508..83c89400eb 100644 --- a/tools/virsh-domain.c +++ b/tools/virsh-domain.c @@ -14041,6 +14041,233 @@ cmdDomFSInfo(vshControl *ctl, const vshCmd *cmd) return ret; } + +/* + * "backup-begin" command + */ +static const vshCmdInfo info_backup_begin[] = { + {.name = "help", + .data = N_("Start a disk backup of a live domain") + }, + {.name = "desc", + .data = N_("Use XML to start a full or incremental disk backup of a live " + "domain, optionally creating a checkpoint") + }, + {.name = NULL} +}; + +static const vshCmdOptDef opts_backup_begin[] = { + VIRSH_COMMON_OPT_DOMAIN_FULL(0), + {.name = "xmlfile", + .type = VSH_OT_STRING, + .help = N_("domain backup XML"), + }, + {.name = "checkpointxml", + .type = VSH_OT_STRING, + .help = N_("domain checkpoint XML"), + }, + {.name = "no-metadata", + .type = VSH_OT_BOOL, + .help = N_("create checkpoint but don't track metadata"), + }, + {.name = "quiesce", + .type = VSH_OT_BOOL, + .help = N_("quiesce guest's file systems"), + }, + /* TODO: --wait/--verbose/--timeout flags for push model backups? */ + {.name = NULL} +}; + +static bool +cmdBackupBegin(vshControl *ctl, + const vshCmd *cmd) +{ + virDomainPtr dom = NULL; + bool ret = false; + const char *backup_from = NULL; + char *backup_buffer = NULL; + const char *check_from = NULL; + char *check_buffer = NULL; + unsigned int flags = 0; + int id; + + if (vshCommandOptBool(cmd, "no-metadata")) + flags |= VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA; + if (vshCommandOptBool(cmd, "quiesce")) + flags |= VIR_DOMAIN_BACKUP_BEGIN_QUIESCE; + + if (!(dom = virshCommandOptDomain(ctl, cmd, NULL))) + goto cleanup; + + if (vshCommandOptStringReq(ctl, cmd, "xmlfile", &backup_from) < 0) + goto cleanup; + if (!backup_from) { + backup_buffer = vshStrdup(ctl, "<domainbackup/>"); + } else { + if (virFileReadAll(backup_from, VSH_MAX_XML_FILE, &backup_buffer) < 0) { + vshSaveLibvirtError(); + goto cleanup; + } + } + + if (vshCommandOptStringReq(ctl, cmd, "checkpointxml", &check_from) < 0) + goto cleanup; + if (check_from) { + if (virFileReadAll(check_from, VSH_MAX_XML_FILE, &check_buffer) < 0) { + vshSaveLibvirtError(); + goto cleanup; + } + } + + id = virDomainBackupBegin(dom, backup_buffer, check_buffer, flags); + + if (id < 0) + goto cleanup; + + vshPrint(ctl, _("Backup id %d started\n"), id); + if (backup_from) + vshPrintExtra(ctl, _("backup used description from '%s'\n"), + backup_from); + if (check_buffer) + vshPrintExtra(ctl, _("checkpoint created from '%s'\n"), check_from); + + ret = true; + + cleanup: + VIR_FREE(backup_buffer); + VIR_FREE(check_buffer); + virshDomainFree(dom); + + return ret; +} + +/* TODO: backup-begin-as? */ + +/* + * "backup-dumpxml" command + */ +static const vshCmdInfo info_backup_dumpxml[] = { + {.name = "help", + .data = N_("Dump XML for an ongoing domain block backup job") + }, + {.name = "desc", + .data = N_("Backup Dump XML") + }, + {.name = NULL} +}; + +static const vshCmdOptDef opts_backup_dumpxml[] = { + VIRSH_COMMON_OPT_DOMAIN_FULL(0), + {.name = "id", + .type = VSH_OT_INT, + .help = N_("backup job id"), + /* TODO: Add API for listing active jobs, then adding a completer? */ + }, + /* TODO - worth adding this flag? + {.name = "checkpoint", + .type = VSH_OT_BOOL, + .help = N_("if the backup created a checkpoint, also dump that XML") + }, + */ + {.name = NULL} +}; + +static bool +cmdBackupDumpXML(vshControl *ctl, + const vshCmd *cmd) +{ + virDomainPtr dom = NULL; + bool ret = false; + char *xml = NULL; + unsigned int flags = 0; + int id = 0; + + if (vshCommandOptBool(cmd, "security-info")) + flags |= VIR_DOMAIN_XML_SECURE; + + if (vshCommandOptInt(ctl, cmd, "id", &id) < 0) + return false; + + if (!(dom = virshCommandOptDomain(ctl, cmd, NULL))) + return false; + + if (!(xml = virDomainBackupGetXMLDesc(dom, id, flags))) + goto cleanup; + + vshPrint(ctl, "%s", xml); + ret = true; + + cleanup: + VIR_FREE(xml); + virshDomainFree(dom); + + return ret; +} + + +/* + * "backup-end" command + */ +static const vshCmdInfo info_backup_end[] = { + {.name = "help", + .data = N_("Conclude a disk backup of a live domain") + }, + {.name = "desc", + .data = N_("End a domain block backup job") + }, + {.name = NULL} +}; + +static const vshCmdOptDef opts_backup_end[] = { + VIRSH_COMMON_OPT_DOMAIN_FULL(0), + {.name = "id", + .type = VSH_OT_INT, + .help = N_("backup job id"), + /* TODO: Add API for listing active jobs, then adding a completer? */ + }, + {.name = "abort", + .type = VSH_OT_BOOL, + .help = N_("abandon a push model backup that has not yet completed") + }, + {.name = NULL} +}; + +static bool +cmdBackupEnd(vshControl *ctl, const vshCmd *cmd) +{ + virDomainPtr dom = NULL; + bool ret = false; + unsigned int flags = 0; + int id = 0; + int rc; + + if (vshCommandOptBool(cmd, "abort")) + flags |= VIR_DOMAIN_BACKUP_END_ABORT; + + if (vshCommandOptInt(ctl, cmd, "id", &id) < 0) + return false; + + if (!(dom = virshCommandOptDomain(ctl, cmd, NULL))) + goto cleanup; + + rc = virDomainBackupEnd(dom, id, flags); + + if (rc < 0) + goto cleanup; + if (rc == 0) + vshPrint(ctl, _("Backup id %d aborted"), id); + else + vshPrint(ctl, _("Backup id %d completed"), id); + + ret = true; + + cleanup: + virshDomainFree(dom); + + return ret; +} + + const vshCmdDef domManagementCmds[] = { {.name = "attach-device", .handler = cmdAttachDevice, @@ -14066,6 +14293,24 @@ const vshCmdDef domManagementCmds[] = { .info = info_autostart, .flags = 0 }, + {.name = "backup-begin", + .handler = cmdBackupBegin, + .opts = opts_backup_begin, + .info = info_backup_begin, + .flags = 0 + }, + {.name = "backup-dumpxml", + .handler = cmdBackupDumpXML, + .opts = opts_backup_dumpxml, + .info = info_backup_dumpxml, + .flags = 0 + }, + {.name = "backup-end", + .handler = cmdBackupEnd, + .opts = opts_backup_end, + .info = info_backup_end, + .flags = 0 + }, {.name = "blkdeviotune", .handler = cmdBlkdeviotune, .opts = opts_blkdeviotune, diff --git a/tools/virsh.pod b/tools/virsh.pod index 8d69d349e9..7ca8869412 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -1352,6 +1352,55 @@ I<bandwidth> specifies copying bandwidth limit in MiB/s. For further information on the I<bandwidth> argument see the corresponding section for the B<blockjob> command. +=item B<backup-begin> I<domain> [I<xmlfile>] +[I<checkpointxml> [I<--no-metadata>]] [I<--quiesce>] + +Begin a new backup job, and output the resulting job id on success. If +I<xmlfile> is omitted, this defaults to a full backup using a push +model to filenames generated by libvirt; supplying XML allows +fine-tuning such as requesting an incremental backup relative to an +earlier checkpoint, controlling which disks participate or which +filenames are involved, or requesting the use of a pull model backup. +The B<backup-dumpxml> command shows any resulting values assigned by +libvirt. For more information on backup XML, see: +L<https://libvirt.org/formatbackup.html>. + +If I<checkpointxml> is specified, a second file with a top-level +element of <domaincheckpoint> is used to create a simultaneous +checkpoint, for doing a later incremental backup relative to the time +the snapshot was created. If I<--no-metadata> is specified, then the +checkpoint is created, but any metadata is immediately discarded. See +B<checkpoint-create> for more details on checkpoints. + +If I<--quiesce> is specified, libvirt will try to use guest agent +to freeze and unfreeze domain's mounted file systems. However, +if domain has no guest agent, the backup job will fail. + +This command returns as soon as possible, and the backup job runs in +the background; the progress of a push model backup can be checked +with B<domjobinfo> or by waiting for an event with B<event> (the +progress of a pull model backup is under the control of whatever third +party connects to the NBD export). The job is ended with B<block-end>. + +=item B<backup-dumpxml> I<domain> [I<id>] + +Output XML describing the backup job I<id>. The default for I<id> is +0, which works as long as there are no parallel jobs; it is also +possible to use the positive id printed by B<backup-begin> on success. + +=item B<backup-end> I<domain> [I<id>] [I<--abort>] + +End the currentbackup job I<id>. The default for I<id> is 0, which +works as long as there are no parallel jobs; it is also possible to +use the positive id printed by B<backup-begin> on success. + +If the backup job is a push job, but the hypervisor is not yet +complete, this command will fail unless I<--abort> is given; if +aborted, the backup file is incomplete. If the backup job is a pull +job, I<--abort> has no effect, because libvirt assumes the third-party +client is done performing the backup. + + =item B<blkdeviotune> I<domain> I<device> [[I<--config>] [I<--live>] | [I<--current>]] [[I<total-bytes-sec>] | [I<read-bytes-sec>] [I<write-bytes-sec>]] -- 2.20.1
Still needs to actually kick off the right QMP commands, but at least allows validation of backup XML, including the fact that a backup job can survive a libvirtd restart. Atomically creating a checkpoint alongside the backup still needs implementing. Signed-off-by: Eric Blake <eblake@redhat.com> --- src/qemu/qemu_domain.h | 4 + src/qemu/qemu_domain.c | 29 ++++++- src/qemu/qemu_driver.c | 185 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 214 insertions(+), 4 deletions(-) diff --git a/src/qemu/qemu_domain.h b/src/qemu/qemu_domain.h index b1ec4af82f..8f8a08f6cb 100644 --- a/src/qemu/qemu_domain.h +++ b/src/qemu/qemu_domain.h @@ -386,6 +386,10 @@ struct _qemuDomainObjPrivate { /* true if global -mem-prealloc appears on cmd line */ bool memPrealloc; + + /* Any currently running backup job. + * FIXME: allow jobs in parallel. For now, at most one job, always id 1. */ + virDomainBackupDefPtr backup; }; #define QEMU_DOMAIN_PRIVATE(vm) \ diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c index 2fca7bd0b8..64c15d8ae6 100644 --- a/src/qemu/qemu_domain.c +++ b/src/qemu/qemu_domain.c @@ -56,6 +56,7 @@ #include "locking/domain_lock.h" #include "virdomainsnapshotobjlist.h" #include "virdomaincheckpointobjlist.h" +#include "backup_conf.h" #ifdef MAJOR_IN_MKDEV # include <sys/mkdev.h> @@ -2310,13 +2311,25 @@ static int qemuDomainObjPrivateXMLFormatBlockjobs(virBufferPtr buf, virDomainObjPtr vm) { + qemuDomainObjPrivatePtr priv = vm->privateData; virBuffer attrBuf = VIR_BUFFER_INITIALIZER; bool bj = qemuDomainHasBlockjob(vm, false); + int ret = -1; virBufferAsprintf(&attrBuf, " active='%s'", virTristateBoolTypeToString(virTristateBoolFromBool(bj))); - return virXMLFormatElement(buf, "blockjobs", &attrBuf, NULL); + if (virXMLFormatElement(buf, "blockjobs", &attrBuf, NULL) < 0) + goto cleanup; + + /* TODO: merge other blockjobs and backups into uniform space? */ + if (priv->backup && virDomainBackupDefFormat(buf, priv->backup, true) < 0) + goto cleanup; + + ret = 0; + cleanup: + virBufferFreeAndReset(&attrBuf); + return ret; } @@ -2657,16 +2670,24 @@ qemuDomainObjPrivateXMLParseAutomaticPlacement(xmlXPathContextPtr ctxt, static int -qemuDomainObjPrivateXMLParseBlockjobs(qemuDomainObjPrivatePtr priv, +qemuDomainObjPrivateXMLParseBlockjobs(virQEMUDriverPtr driver, + qemuDomainObjPrivatePtr priv, xmlXPathContextPtr ctxt) { - VIR_AUTOFREE(char *) active = NULL; + xmlNodePtr node; int tmp; + VIR_AUTOFREE(char *) active = NULL; if ((active = virXPathString("string(./blockjobs/@active)", ctxt)) && (tmp = virTristateBoolTypeFromString(active)) > 0) priv->reconnectBlockjobs = tmp; + if ((node = virXPathNode("./domainbackup", ctxt)) && + !(priv->backup = virDomainBackupDefParseNode(ctxt->doc, node, + driver->xmlopt, + VIR_DOMAIN_BACKUP_PARSE_INTERNAL))) + return -1; + return 0; } @@ -3024,7 +3045,7 @@ qemuDomainObjPrivateXMLParse(xmlXPathContextPtr ctxt, qemuDomainObjPrivateXMLParsePR(ctxt, &priv->prDaemonRunning); - if (qemuDomainObjPrivateXMLParseBlockjobs(priv, ctxt) < 0) + if (qemuDomainObjPrivateXMLParseBlockjobs(driver, priv, ctxt) < 0) goto error; qemuDomainStorageIdReset(priv); diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index f9605027be..ec5f37fe94 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -104,6 +104,7 @@ #include "virdomainsnapshotobjlist.h" #include "virenum.h" #include "virdomaincheckpointobjlist.h" +#include "backup_conf.h" #define VIR_FROM_THIS VIR_FROM_QEMU @@ -17554,6 +17555,187 @@ qemuDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, return ret; } +static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, + const char *checkpointXml, unsigned int flags) +{ + virQEMUDriverPtr driver = domain->conn->privateData; + virDomainObjPtr vm = NULL; + virDomainBackupDefPtr def = NULL; + virQEMUDriverConfigPtr cfg = NULL; + virCapsPtr caps = NULL; + qemuDomainObjPrivatePtr priv; + int ret = -1; + struct timeval tv; + char *suffix = NULL; + + virCheckFlags(VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA, -1); + /* TODO: VIR_DOMAIN_BACKUP_BEGIN_QUIESCE */ + + // FIXME: Support non-null checkpointXML for incremental - what + // code can be shared with CheckpointCreateXML, then add to transaction + // to create new checkpoint at same time as starting blockdev-backup + if (checkpointXml) { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", + _("cannot create incremental backups yet")); + return -1; + } + // if (chk) VIR_STRDUP(suffix, chk->name); + gettimeofday(&tv, NULL); + if (virAsprintf(&suffix, "%lld", (long long)tv.tv_sec) < 0) + goto cleanup; + + if (!(vm = qemuDomObjFromDomain(domain))) + goto cleanup; + + cfg = virQEMUDriverGetConfig(driver); + + if (virDomainBackupBeginEnsureACL(domain->conn, vm->def, flags) < 0) + goto cleanup; + + if (!(caps = virQEMUDriverGetCapabilities(driver, false))) + goto cleanup; + + if (qemuProcessAutoDestroyActive(driver, vm)) { + virReportError(VIR_ERR_OPERATION_INVALID, + "%s", _("domain is marked for auto destroy")); + goto cleanup; + } + + if (!virDomainObjIsActive(vm)) { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", + _("cannot perform disk backup for inactive domain")); + goto cleanup; + } + if (!(def = virDomainBackupDefParseString(diskXml, driver->xmlopt, 0))) + goto cleanup; + + /* We are going to modify the domain below. */ + if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0) + goto cleanup; + + priv = vm->privateData; + if (priv->backup) { + virReportError(VIR_ERR_OPERATION_INVALID, + "%s", _("another backup job is already running")); + goto endjob; + } + + if (virDomainBackupAlignDisks(def, vm->def, suffix) < 0) + goto endjob; + + /* actually start the checkpoint. 2x2 array of push/pull, full/incr, + plus additional tweak if checkpoint requested */ + /* TODO: issue QMP commands: + - pull: nbd-server-start with <server> from user (or autogenerate server) + - push/pull: blockdev-add per <disk> + - incr: bitmap-add of tmp, bitmap-merge per <disk> + - transaction, containing: + - push+full: blockdev-backup sync:full + - push+incr: blockdev-backup sync:incremental bitmap:tmp + - pull+full: blockdev-backup sync:none + - pull+incr: blockdev-backup sync:none, bitmap-disable of tmp + - if checkpoint: bitmap-disable of old, bitmap-add of new + - pull: nbd-server-add per <disk>, including bitmap for incr + */ + + VIR_STEAL_PTR(priv->backup, def); + ret = priv->backup->id = 1; /* Hard-coded job id for now */ + if (virDomainSaveStatus(driver->xmlopt, cfg->stateDir, vm, + driver->caps) < 0) + VIR_WARN("Unable to save status on vm %s after backup job", + vm->def->name); + + endjob: + qemuDomainObjEndJob(driver, vm); + + cleanup: + VIR_FREE(suffix); + virDomainObjEndAPI(&vm); + virDomainBackupDefFree(def); + virObjectUnref(caps); + virObjectUnref(cfg); + return ret; +} + +static char *qemuDomainBackupGetXMLDesc(virDomainPtr domain, int id, + unsigned int flags) +{ + virDomainObjPtr vm = NULL; + char *xml = NULL; + qemuDomainObjPrivatePtr priv; + virBuffer buf = VIR_BUFFER_INITIALIZER; + + virCheckFlags(0, NULL); + + if (!(vm = qemuDomObjFromDomain(domain))) + return NULL; + + if (virDomainBackupGetXMLDescEnsureACL(domain->conn, vm->def) < 0) + goto cleanup; + + /* TODO: Allow more than one hard-coded job id */ + priv = vm->privateData; + if ((id != 0 && id != 1) || !priv->backup) { + virReportError(VIR_ERR_NO_DOMAIN_CHECKPOINT, + _("no domain backup job with id '%d'"), id); + goto cleanup; + } + + if (virDomainBackupDefFormat(&buf, priv->backup, false) < 0) + goto cleanup; + xml = virBufferContentAndReset(&buf); + + cleanup: + virDomainObjEndAPI(&vm); + return xml; +} + +static int qemuDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags) +{ + virQEMUDriverPtr driver = domain->conn->privateData; + virQEMUDriverConfigPtr cfg = NULL; + virDomainObjPtr vm = NULL; + int ret = -1; + virDomainBackupDefPtr backup = NULL; + qemuDomainObjPrivatePtr priv; + bool want_abort = flags & VIR_DOMAIN_BACKUP_END_ABORT; + + virCheckFlags(VIR_DOMAIN_BACKUP_END_ABORT, -1); + + if (!(vm = qemuDomObjFromDomain(domain))) + return -1; + + cfg = virQEMUDriverGetConfig(driver); + if (virDomainBackupEndEnsureACL(domain->conn, vm->def) < 0) + goto cleanup; + + /* TODO: Allow more than one hard-coded job id */ + priv = vm->privateData; + if ((id != 0 && id != 1) || !priv->backup) { + virReportError(VIR_ERR_NO_DOMAIN_CHECKPOINT, + _("no domain backup job with id '%d'"), id); + goto cleanup; + } + + if (priv->backup->type != VIR_DOMAIN_BACKUP_TYPE_PUSH) + want_abort = false; + + /* TODO: QMP commands to actually cancel the pending job, and on + * pull, also tear down the NBD server */ + VIR_STEAL_PTR(backup, priv->backup); + if (virDomainSaveStatus(driver->xmlopt, cfg->stateDir, vm, + driver->caps) < 0) + VIR_WARN("Unable to save status on vm %s after backup job", + vm->def->name); + + ret = want_abort ? 0 : 1; + + cleanup: + virDomainBackupDefFree(backup); + virDomainObjEndAPI(&vm); + return ret; +} + static int qemuDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd, char **result, unsigned int flags) { @@ -23256,6 +23438,9 @@ static virHypervisorDriver qemuHypervisorDriver = { .domainCheckpointGetParent = qemuDomainCheckpointGetParent, /* 5.6.0 */ .domainCheckpointDelete = qemuDomainCheckpointDelete, /* 5.6.0 */ .domainCheckpointIsCurrent = qemuDomainCheckpointIsCurrent, /* 5.6.0 */ + .domainBackupBegin = qemuDomainBackupBegin, /* 5.6.0 */ + .domainBackupGetXMLDesc = qemuDomainBackupGetXMLDesc, /* 5.6.0 */ + .domainBackupEnd = qemuDomainBackupEnd, /* 5.6.0 */ }; -- 2.20.1
On Mon, Jul 08, 2019 at 11:55:50 -0500, Eric Blake wrote:
Still needs to actually kick off the right QMP commands, but at least allows validation of backup XML, including the fact that a backup job can survive a libvirtd restart. Atomically creating a checkpoint alongside the backup still needs implementing.
Signed-off-by: Eric Blake <eblake@redhat.com> --- src/qemu/qemu_domain.h | 4 + src/qemu/qemu_domain.c | 29 ++++++- src/qemu/qemu_driver.c | 185 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 214 insertions(+), 4 deletions(-)
I can only re-iterate the comment of not stuffing irrelevant code into qemuDomainObjPrivateXMLFormatBlockjobs from the last time and also point out that the NO_METADATA flag should not be included.
Time to actually issue the QMP transactions that start and stop backup commands (for now, just pull mode, not push). Starting a job has to kick off several pre-req steps, then a transaction, and additionally spawn an NBD server for pull mode; ending a job as well as failing partway through beginning a job has to unwind the earlier steps. Implementing push mode, as well as incremental pull and checkpoint creation, is deferred to later patches. Signed-off-by: Eric Blake <eblake@redhat.com> --- src/qemu/qemu_domain.c | 18 +- src/qemu/qemu_driver.c | 310 ++++++++++++++++++++++++++++++++++- src/qemu/qemu_monitor_json.c | 4 + src/qemu/qemu_process.c | 9 + 4 files changed, 327 insertions(+), 14 deletions(-) diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c index 64c15d8ae6..70fe250880 100644 --- a/src/qemu/qemu_domain.c +++ b/src/qemu/qemu_domain.c @@ -2676,17 +2676,25 @@ qemuDomainObjPrivateXMLParseBlockjobs(virQEMUDriverPtr driver, { xmlNodePtr node; int tmp; + size_t i; VIR_AUTOFREE(char *) active = NULL; if ((active = virXPathString("string(./blockjobs/@active)", ctxt)) && (tmp = virTristateBoolTypeFromString(active)) > 0) priv->reconnectBlockjobs = tmp; - if ((node = virXPathNode("./domainbackup", ctxt)) && - !(priv->backup = virDomainBackupDefParseNode(ctxt->doc, node, - driver->xmlopt, - VIR_DOMAIN_BACKUP_PARSE_INTERNAL))) - return -1; + if ((node = virXPathNode("./domainbackup", ctxt))) { + if (!(priv->backup = virDomainBackupDefParseNode(ctxt->doc, node, + driver->xmlopt, + VIR_DOMAIN_BACKUP_PARSE_INTERNAL))) + return -1; + /* The backup job is only stored in XML if backupBegin + * succeeded at exporting the disk, so no need to store disk + * state when we can just force-reset it to a known-good + * value. */ + for (i = 0; i < priv->backup->ndisks; i++) + priv->backup->disks[i].state = VIR_DOMAIN_BACKUP_DISK_STATE_EXPORT; + } return 0; } diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index ec5f37fe94..d9abcfa4c8 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -17555,8 +17555,80 @@ qemuDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, return ret; } -static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, - const char *checkpointXml, unsigned int flags) +static int +qemuDomainBackupPrepare(virQEMUDriverPtr driver, virDomainObjPtr vm, + virDomainBackupDefPtr def) +{ + int ret = -1; + size_t i; + + if (qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0) + goto cleanup; + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + virStorageSourcePtr src = vm->def->disks[disk->idx]->src; + + if (!disk->store) + continue; + if (virAsprintf(&disk->store->nodeformat, "tmp-%s", disk->name) < 0) + goto cleanup; + if (!disk->store->format) + disk->store->format = VIR_STORAGE_FILE_QCOW2; + if (def->incremental) { + if (src->format != VIR_STORAGE_FILE_QCOW2) { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, + _("incremental backup of %s requires qcow2"), + disk->name); + goto cleanup; + } + } + } + ret = 0; + cleanup: + return ret; +} + +/* Called while monitor lock is held. Best-effort cleanup. */ +static int +qemuDomainBackupDiskCleanup(virQEMUDriverPtr driver, virDomainObjPtr vm, + virDomainBackupDiskDef *disk, bool incremental) +{ + qemuDomainObjPrivatePtr priv = vm->privateData; + const char *node = vm->def->disks[disk->idx]->src->nodeformat; + int ret = 0; + + if (!disk->store) + return 0; + if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_EXPORT) { + /* No real need to use nbd-server-remove, since we will + * shortly be calling nbd-server-stop. */ + } + if (incremental && disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_BITMAP && + qemuMonitorDeleteBitmap(priv->mon, node, disk->store->nodeformat) < 0) { + VIR_WARN("Unable to remove temp bitmap for disk %s after backup", + disk->name); + ret = -1; + } + if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_READY && + qemuMonitorBlockdevDel(priv->mon, disk->store->nodeformat) < 0) { + VIR_WARN("Unable to remove temp disk %s after backup", + disk->name); + ret = -1; + } + if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_LABEL) + qemuDomainStorageSourceAccessRevoke(driver, vm, disk->store); + if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_CREATED && + disk->store->detected && unlink(disk->store->path) < 0) { + VIR_WARN("Unable to unlink temp disk %s after backup", + disk->store->path); + ret = -1; + } + return ret; +} + +static int +qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, + const char *checkpointXml, unsigned int flags) { virQEMUDriverPtr driver = domain->conn->privateData; virDomainObjPtr vm = NULL; @@ -17565,8 +17637,14 @@ static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, virCapsPtr caps = NULL; qemuDomainObjPrivatePtr priv; int ret = -1; + virJSONValuePtr json = NULL; + bool job_started = false; + bool nbd_running = false; + size_t i; struct timeval tv; char *suffix = NULL; + virCommandPtr cmd = NULL; + const char *qemuImgPath; virCheckFlags(VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA, -1); /* TODO: VIR_DOMAIN_BACKUP_BEGIN_QUIESCE */ @@ -17587,6 +17665,7 @@ static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, if (!(vm = qemuDomObjFromDomain(domain))) goto cleanup; + priv = vm->privateData; cfg = virQEMUDriverGetConfig(driver); if (virDomainBackupBeginEnsureACL(domain->conn, vm->def, flags) < 0) @@ -17609,25 +17688,145 @@ static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, if (!(def = virDomainBackupDefParseString(diskXml, driver->xmlopt, 0))) goto cleanup; + if (def->type == VIR_DOMAIN_BACKUP_TYPE_PULL) { + if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_NBD_BITMAP)) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("qemu binary lacks pull-mode backup support")); + goto cleanup; + } + if (!def->server) { + if (VIR_ALLOC(def->server) < 0) + goto cleanup; + def->server->transport = VIR_STORAGE_NET_HOST_TRANS_TCP; + if (VIR_STRDUP(def->server->name, "localhost") < 0) + goto cleanup; + } + switch ((virStorageNetHostTransport)def->server->transport) { + case VIR_STORAGE_NET_HOST_TRANS_TCP: + /* TODO: Update qemu.conf to provide a port range, + * probably starting at 10809, for obtaining automatic + * port via virPortAllocatorAcquire, as well as store + * somewhere if we need to call virPortAllocatorRelease + * during BackupEnd. Until then, user must provide port */ + if (!def->server->port) { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", + _("<domainbackup> must specify TCP port for now")); + goto cleanup; + } + break; + case VIR_STORAGE_NET_HOST_TRANS_UNIX: + /* TODO: Do we need to mess with selinux? */ + break; + case VIR_STORAGE_NET_HOST_TRANS_RDMA: + case VIR_STORAGE_NET_HOST_TRANS_LAST: + virReportError(VIR_ERR_INTERNAL_ERROR, "%s", + _("unexpected transport in <domainbackup>")); + goto cleanup; + } + } else { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", + _("push mode backups not supported yet")); + goto cleanup; + } + if (def->incremental) { + if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_BITMAP_MERGE)) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("qemu binary lacks persistent bitmaps support")); + goto cleanup; + } + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", + _("cannot create incremental backups yet")); + goto cleanup; + } + + if (!(qemuImgPath = qemuFindQemuImgBinary(driver))) + goto cleanup; + /* We are going to modify the domain below. */ if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0) goto cleanup; - priv = vm->privateData; if (priv->backup) { virReportError(VIR_ERR_OPERATION_INVALID, "%s", _("another backup job is already running")); goto endjob; } - if (virDomainBackupAlignDisks(def, vm->def, suffix) < 0) + if (virDomainBackupAlignDisks(def, vm->def, suffix) < 0 || + qemuDomainBackupPrepare(driver, vm, def) < 0) goto endjob; /* actually start the checkpoint. 2x2 array of push/pull, full/incr, plus additional tweak if checkpoint requested */ - /* TODO: issue QMP commands: - - pull: nbd-server-start with <server> from user (or autogenerate server) - - push/pull: blockdev-add per <disk> + qemuDomainObjEnterMonitor(driver, vm); + /* - push/pull: blockdev-add per <disk> */ + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + virJSONValuePtr file; + virStorageSourcePtr src = vm->def->disks[disk->idx]->src; + const char *node = src->nodeformat; + + if (!disk->store) + continue; + if (qemuDomainStorageFileInit(driver, vm, disk->store, src) < 0) + goto endmon; + if (disk->store->detected) { + if (virStorageFileCreate(disk->store) < 0) { + virReportSystemError(errno, + _("failed to create image file '%s'"), + NULLSTR(disk->store->path)); + goto endmon; + } + disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_CREATED; + } + if (qemuDomainStorageSourceAccessAllow(driver, vm, disk->store, false, + true) < 0) + goto endmon; + disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_LABEL; + if (disk->store->detected) { + virBuffer buf = VIR_BUFFER_INITIALIZER; + + /* Force initialization of scratch/target file to new qcow2 */ + if (!(cmd = virCommandNewArgList(qemuImgPath, + "create", + "-f", + virStorageFileFormatTypeToString(disk->store->format), + "-o", + NULL))) + goto endmon; + virBufferAsprintf(&buf, "backing_fmt=%s,backing_file=", + virStorageFileFormatTypeToString(src->format)); + virQEMUBuildBufferEscapeComma(&buf, src->path); + virCommandAddArgBuffer(cmd, &buf); + + virQEMUBuildBufferEscapeComma(&buf, disk->store->path); + virCommandAddArgBuffer(cmd, &buf); + if (virCommandRun(cmd, NULL) < 0) + goto endmon; + virCommandFree(cmd); + cmd = NULL; + } + + if (virJSONValueObjectCreate(&file, + "s:driver", "file", + "s:filename", disk->store->path, + NULL) < 0) + goto endmon; + if (virJSONValueObjectCreate(&json, + "s:driver", virStorageFileFormatTypeToString(disk->store->format), + "s:node-name", disk->store->nodeformat, + "a:file", &file, + "s:backing", node, NULL) < 0) { + virJSONValueFree(file); + goto endmon; + } + if (qemuMonitorBlockdevAdd(priv->mon, json) < 0) + goto endmon; + json = NULL; + disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_READY; + } + + /* TODO: - incr: bitmap-add of tmp, bitmap-merge per <disk> - transaction, containing: - push+full: blockdev-backup sync:full @@ -17635,8 +17834,76 @@ static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, - pull+full: blockdev-backup sync:none - pull+incr: blockdev-backup sync:none, bitmap-disable of tmp - if checkpoint: bitmap-disable of old, bitmap-add of new + */ + if (!(json = virJSONValueNewArray())) + goto endmon; + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + virStorageSourcePtr src = vm->def->disks[disk->idx]->src; + + if (!disk->store) + continue; + if (qemuMonitorJSONTransactionAdd(json, + "blockdev-backup", + "s:device", src->nodeformat, + "s:target", disk->store->nodeformat, + "s:sync", "none", + "s:job-id", disk->name, + NULL) < 0) + goto endmon; + } + if (qemuMonitorTransaction(priv->mon, &json) < 0) + goto endmon; + job_started = true; + + /* + - pull: nbd-server-start with <server> from user (or autogenerate server) - pull: nbd-server-add per <disk>, including bitmap for incr */ + if (def->type == VIR_DOMAIN_BACKUP_TYPE_PULL) { + if (qemuMonitorNBDServerStart(priv->mon, def->server, NULL) < 0) + goto endmon; + nbd_running = true; + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + + if (!disk->store) + continue; + if (qemuMonitorNBDServerAdd(priv->mon, disk->store->nodeformat, + disk->name, false, + def->incremental ? disk->name : + NULL) < 0) + goto endmon; + disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_EXPORT; + } + } + + ret = 0; + endmon: + /* Best effort cleanup if we fail partway through */ + if (ret < 0) { + virErrorPtr save_err = virSaveLastError(); + + if (nbd_running && + qemuMonitorNBDServerStop(priv->mon) < 0) + VIR_WARN("Unable to stop NBD server on vm %s after backup job", + vm->def->name); + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + + if (job_started && + qemuMonitorBlockJobCancel(priv->mon, disk->name) < 0) + VIR_WARN("Unable to stop backup job %s on vm %s after failure", + disk->store->nodeformat, vm->def->name); + qemuDomainBackupDiskCleanup(driver, vm, disk, !!def->incremental); + } + virSetError(save_err); + virFreeError(save_err); + } + if (qemuDomainObjExitMonitor(driver, vm) < 0) + ret = -1; + if (ret < 0) + goto endjob; VIR_STEAL_PTR(priv->backup, def); ret = priv->backup->id = 1; /* Hard-coded job id for now */ @@ -17649,7 +17916,9 @@ static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, qemuDomainObjEndJob(driver, vm); cleanup: + virCommandFree(cmd); VIR_FREE(suffix); + virJSONValueFree(json); virDomainObjEndAPI(&vm); virDomainBackupDefFree(def); virObjectUnref(caps); @@ -17699,6 +17968,8 @@ static int qemuDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags) virDomainBackupDefPtr backup = NULL; qemuDomainObjPrivatePtr priv; bool want_abort = flags & VIR_DOMAIN_BACKUP_END_ABORT; + virDomainBackupDefPtr def; + size_t i; virCheckFlags(VIR_DOMAIN_BACKUP_END_ABORT, -1); @@ -17719,9 +17990,27 @@ static int qemuDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags) if (priv->backup->type != VIR_DOMAIN_BACKUP_TYPE_PUSH) want_abort = false; + def = priv->backup; + + /* We are going to modify the domain below. */ + if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0) + goto cleanup; + + qemuDomainObjEnterMonitor(driver, vm); + if (def->type == VIR_DOMAIN_BACKUP_TYPE_PULL) + ret = qemuMonitorNBDServerStop(priv->mon); + for (i = 0; i < def->ndisks; i++) { + if (qemuMonitorBlockJobCancel(priv->mon, + def->disks[i].name) < 0 || + qemuDomainBackupDiskCleanup(driver, vm, &def->disks[i], + !!def->incremental) < 0) + ret = -1; + } + if (qemuDomainObjExitMonitor(driver, vm) < 0 || ret < 0) { + ret = -1; + goto endjob; + } - /* TODO: QMP commands to actually cancel the pending job, and on - * pull, also tear down the NBD server */ VIR_STEAL_PTR(backup, priv->backup); if (virDomainSaveStatus(driver->xmlopt, cfg->stateDir, vm, driver->caps) < 0) @@ -17730,6 +18019,9 @@ static int qemuDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags) ret = want_abort ? 0 : 1; + endjob: + qemuDomainObjEndJob(driver, vm); + cleanup: virDomainBackupDefFree(backup); virDomainObjEndAPI(&vm); diff --git a/src/qemu/qemu_monitor_json.c b/src/qemu/qemu_monitor_json.c index 1769fa70cb..233a11fc31 100644 --- a/src/qemu/qemu_monitor_json.c +++ b/src/qemu/qemu_monitor_json.c @@ -1127,6 +1127,8 @@ qemuMonitorJSONHandleBlockJobImpl(qemuMonitorPtr mon, type = VIR_DOMAIN_BLOCK_JOB_TYPE_COMMIT; else if (STREQ(type_str, "mirror")) type = VIR_DOMAIN_BLOCK_JOB_TYPE_COPY; + else if (STREQ(type_str, "backup")) + type = VIR_DOMAIN_BLOCK_JOB_TYPE_BACKUP; switch ((virConnectDomainEventBlockJobStatus) event) { case VIR_DOMAIN_BLOCK_JOB_COMPLETED: @@ -4884,6 +4886,8 @@ qemuMonitorJSONParseBlockJobInfo(virHashTablePtr blockJobs, info->type = VIR_DOMAIN_BLOCK_JOB_TYPE_COMMIT; else if (STREQ(type, "mirror")) info->type = VIR_DOMAIN_BLOCK_JOB_TYPE_COPY; + else if (STREQ(type, "backup")) + info->type = VIR_DOMAIN_BLOCK_JOB_TYPE_BACKUP; else info->type = VIR_DOMAIN_BLOCK_JOB_TYPE_UNKNOWN; diff --git a/src/qemu/qemu_process.c b/src/qemu/qemu_process.c index aa09ef175a..fdab26fb17 100644 --- a/src/qemu/qemu_process.c +++ b/src/qemu/qemu_process.c @@ -89,6 +89,7 @@ #include "virresctrl.h" #include "virvsock.h" #include "viridentity.h" +#include "backup_conf.h" #define VIR_FROM_THIS VIR_FROM_QEMU @@ -933,6 +934,7 @@ qemuProcessHandleBlockJob(qemuMonitorPtr mon ATTRIBUTE_UNUSED, void *opaque) { virQEMUDriverPtr driver = opaque; + qemuDomainObjPrivatePtr priv; struct qemuProcessEvent *processEvent = NULL; virDomainDiskDefPtr disk; qemuBlockJobDataPtr job = NULL; @@ -943,6 +945,13 @@ qemuProcessHandleBlockJob(qemuMonitorPtr mon ATTRIBUTE_UNUSED, VIR_DEBUG("Block job for device %s (domain: %p,%s) type %d status %d", diskAlias, vm, vm->def->name, type, status); + priv = vm->privateData; + if (type == VIR_DOMAIN_BLOCK_JOB_TYPE_BACKUP && + (!priv->backup || priv->backup->type == VIR_DOMAIN_BACKUP_TYPE_PULL)) { + /* Event for canceling a pull-mode backup is side-effect that + * should not be forwarded on to user */ + goto cleanup; + } if (!(disk = qemuProcessFindDomainDiskByAliasOrQOM(vm, diskAlias, NULL))) goto cleanup; -- 2.20.1
On Mon, Jul 08, 2019 at 11:55:51 -0500, Eric Blake wrote:
Time to actually issue the QMP transactions that start and stop backup commands (for now, just pull mode, not push). Starting a job has to kick off several pre-req steps, then a transaction, and additionally spawn an NBD server for pull mode; ending a job as well as failing partway through beginning a job has to unwind the earlier steps. Implementing push mode, as well as incremental pull and checkpoint creation, is deferred to later patches.
Signed-off-by: Eric Blake <eblake@redhat.com> --- src/qemu/qemu_domain.c | 18 +- src/qemu/qemu_driver.c | 310 ++++++++++++++++++++++++++++++++++- src/qemu/qemu_monitor_json.c | 4 + src/qemu/qemu_process.c | 9 + 4 files changed, 327 insertions(+), 14 deletions(-)
diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c index 64c15d8ae6..70fe250880 100644 --- a/src/qemu/qemu_domain.c +++ b/src/qemu/qemu_domain.c @@ -2676,17 +2676,25 @@ qemuDomainObjPrivateXMLParseBlockjobs(virQEMUDriverPtr driver, { xmlNodePtr node; int tmp; + size_t i; VIR_AUTOFREE(char *) active = NULL;
if ((active = virXPathString("string(./blockjobs/@active)", ctxt)) && (tmp = virTristateBoolTypeFromString(active)) > 0) priv->reconnectBlockjobs = tmp;
- if ((node = virXPathNode("./domainbackup", ctxt)) && - !(priv->backup = virDomainBackupDefParseNode(ctxt->doc, node, - driver->xmlopt, - VIR_DOMAIN_BACKUP_PARSE_INTERNAL))) - return -1; + if ((node = virXPathNode("./domainbackup", ctxt))) { + if (!(priv->backup = virDomainBackupDefParseNode(ctxt->doc, node, + driver->xmlopt, + VIR_DOMAIN_BACKUP_PARSE_INTERNAL))) + return -1; + /* The backup job is only stored in XML if backupBegin + * succeeded at exporting the disk, so no need to store disk + * state when we can just force-reset it to a known-good + * value. */ + for (i = 0; i < priv->backup->ndisks; i++) + priv->backup->disks[i].state = VIR_DOMAIN_BACKUP_DISK_STATE_EXPORT;
Even for push mode?
+ }
return 0; } diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index ec5f37fe94..d9abcfa4c8 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -17555,8 +17555,80 @@ qemuDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, return ret; }
-static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, - const char *checkpointXml, unsigned int flags) +static int +qemuDomainBackupPrepare(virQEMUDriverPtr driver, virDomainObjPtr vm, + virDomainBackupDefPtr def) +{ + int ret = -1; + size_t i; + + if (qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0)
See previous reviews.
+ goto cleanup; + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + virStorageSourcePtr src = vm->def->disks[disk->idx]->src; + + if (!disk->store) + continue; + if (virAsprintf(&disk->store->nodeformat, "tmp-%s", disk->name) < 0) + goto cleanup; + if (!disk->store->format) + disk->store->format = VIR_STORAGE_FILE_QCOW2; + if (def->incremental) { + if (src->format != VIR_STORAGE_FILE_QCOW2) { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, + _("incremental backup of %s requires qcow2"), + disk->name); + goto cleanup; + } + } + } + ret = 0; + cleanup: + return ret; +} + +/* Called while monitor lock is held. Best-effort cleanup. */ +static int +qemuDomainBackupDiskCleanup(virQEMUDriverPtr driver, virDomainObjPtr vm, + virDomainBackupDiskDef *disk, bool incremental) +{ + qemuDomainObjPrivatePtr priv = vm->privateData; + const char *node = vm->def->disks[disk->idx]->src->nodeformat; + int ret = 0; + + if (!disk->store) + return 0; + if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_EXPORT) { + /* No real need to use nbd-server-remove, since we will + * shortly be calling nbd-server-stop. */ + } + if (incremental && disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_BITMAP && + qemuMonitorDeleteBitmap(priv->mon, node, disk->store->nodeformat) < 0) { + VIR_WARN("Unable to remove temp bitmap for disk %s after backup", + disk->name); + ret = -1; + } + if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_READY && + qemuMonitorBlockdevDel(priv->mon, disk->store->nodeformat) < 0) { + VIR_WARN("Unable to remove temp disk %s after backup", + disk->name); + ret = -1; + } + if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_LABEL) + qemuDomainStorageSourceAccessRevoke(driver, vm, disk->store);
You must not call this with @vm unlocked.
+ if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_CREATED && + disk->store->detected && unlink(disk->store->path) < 0) { + VIR_WARN("Unable to unlink temp disk %s after backup", + disk->store->path); + ret = -1; + } + return ret; +} + +static int +qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, + const char *checkpointXml, unsigned int flags) { virQEMUDriverPtr driver = domain->conn->privateData; virDomainObjPtr vm = NULL;
[....]
@@ -17609,25 +17688,145 @@ static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml,
[...]
- if (virDomainBackupAlignDisks(def, vm->def, suffix) < 0) + if (virDomainBackupAlignDisks(def, vm->def, suffix) < 0 || + qemuDomainBackupPrepare(driver, vm, def) < 0) goto endjob;
/* actually start the checkpoint. 2x2 array of push/pull, full/incr, plus additional tweak if checkpoint requested */ - /* TODO: issue QMP commands: - - pull: nbd-server-start with <server> from user (or autogenerate server) - - push/pull: blockdev-add per <disk> + qemuDomainObjEnterMonitor(driver, vm); + /* - push/pull: blockdev-add per <disk> */ + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + virJSONValuePtr file; + virStorageSourcePtr src = vm->def->disks[disk->idx]->src; + const char *node = src->nodeformat; + + if (!disk->store) + continue; + if (qemuDomainStorageFileInit(driver, vm, disk->store, src) < 0)
This takes @vm which is unlocked
+ goto endmon; + if (disk->store->detected) { + if (virStorageFileCreate(disk->store) < 0) { + virReportSystemError(errno, + _("failed to create image file '%s'"), + NULLSTR(disk->store->path)); + goto endmon; + } + disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_CREATED; + } + if (qemuDomainStorageSourceAccessAllow(driver, vm, disk->store, false,
Also this requires @vm locked
+ true) < 0) + goto endmon; + disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_LABEL; + if (disk->store->detected) { + virBuffer buf = VIR_BUFFER_INITIALIZER; + + /* Force initialization of scratch/target file to new qcow2 */ + if (!(cmd = virCommandNewArgList(qemuImgPath, + "create", + "-f", + virStorageFileFormatTypeToString(disk->store->format), + "-o", + NULL))) + goto endmon;
AFAIK if we hold the monitor lock too much (and this qualifies as a long-running operation) without calling actual monitor APIs the event loop will get stuck.
+ virBufferAsprintf(&buf, "backing_fmt=%s,backing_file=", + virStorageFileFormatTypeToString(src->format)); + virQEMUBuildBufferEscapeComma(&buf, src->path); + virCommandAddArgBuffer(cmd, &buf); + + virQEMUBuildBufferEscapeComma(&buf, disk->store->path); + virCommandAddArgBuffer(cmd, &buf); + if (virCommandRun(cmd, NULL) < 0) + goto endmon; + virCommandFree(cmd); + cmd = NULL; + } + + if (virJSONValueObjectCreate(&file, + "s:driver", "file", + "s:filename", disk->store->path, + NULL) < 0) + goto endmon; + if (virJSONValueObjectCreate(&json, + "s:driver", virStorageFileFormatTypeToString(disk->store->format), + "s:node-name", disk->store->nodeformat, + "a:file", &file, + "s:backing", node, NULL) < 0) {
Please use the designated blockdev-add JSON props generators. Also libvirt opted to open the 'file' separately with blockdev add so this should not do things differently.
+ virJSONValueFree(file); + goto endmon; + } + if (qemuMonitorBlockdevAdd(priv->mon, json) < 0) + goto endmon; + json = NULL; + disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_READY; + } + + /* TODO: - incr: bitmap-add of tmp, bitmap-merge per <disk> - transaction, containing: - push+full: blockdev-backup sync:full @@ -17635,8 +17834,76 @@ static int qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, - pull+full: blockdev-backup sync:none - pull+incr: blockdev-backup sync:none, bitmap-disable of tmp - if checkpoint: bitmap-disable of old, bitmap-add of new + */ + if (!(json = virJSONValueNewArray())) + goto endmon; + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + virStorageSourcePtr src = vm->def->disks[disk->idx]->src; + + if (!disk->store) + continue; + if (qemuMonitorJSONTransactionAdd(json, + "blockdev-backup", + "s:device", src->nodeformat,
Also since this does not seem to register the blockjob with the disk you don't get the interlocking with other blockjobs
+ "s:target", disk->store->nodeformat, + "s:sync", "none", + "s:job-id", disk->name,
This should be prefixed with job type.
+ NULL) < 0) + goto endmon;
[...]
@@ -17719,9 +17990,27 @@ static int qemuDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags)
if (priv->backup->type != VIR_DOMAIN_BACKUP_TYPE_PUSH) want_abort = false; + def = priv->backup; + + /* We are going to modify the domain below. */ + if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0) + goto cleanup; + + qemuDomainObjEnterMonitor(driver, vm); + if (def->type == VIR_DOMAIN_BACKUP_TYPE_PULL) + ret = qemuMonitorNBDServerStop(priv->mon); + for (i = 0; i < def->ndisks; i++) { + if (qemuMonitorBlockJobCancel(priv->mon,
If not all disks are part of the job def->disk[i].name might point to a disk which is not part of the backup and this would then attempt to cancel a job of that disk.
+ def->disks[i].name) < 0 || + qemuDomainBackupDiskCleanup(driver, vm, &def->disks[i], + !!def->incremental) < 0) + ret = -1; + } + if (qemuDomainObjExitMonitor(driver, vm) < 0 || ret < 0) { + ret = -1; + goto endjob; + }
Update the code to support push backups; for now, the destination file still has to be local, although the XML could be extended into supporting remote destinations (where we will have to use the full power of blockdev-add). This also touches up the event handling to inform the user when the job is complete. (However, there are probably bugs lurking in the event code; pull mode is more tested than push mode at the time I write this). Signed-off-by: Eric Blake <eblake@redhat.com> --- src/qemu/qemu_driver.c | 81 +++++++++++++++++++++++++++++------------- 1 file changed, 56 insertions(+), 25 deletions(-) diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index d9abcfa4c8..a7a9526d1e 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -17591,14 +17591,13 @@ qemuDomainBackupPrepare(virQEMUDriverPtr driver, virDomainObjPtr vm, /* Called while monitor lock is held. Best-effort cleanup. */ static int qemuDomainBackupDiskCleanup(virQEMUDriverPtr driver, virDomainObjPtr vm, - virDomainBackupDiskDef *disk, bool incremental) + virDomainBackupDiskDef *disk, bool push, + bool incremental, bool completed) { qemuDomainObjPrivatePtr priv = vm->privateData; const char *node = vm->def->disks[disk->idx]->src->nodeformat; int ret = 0; - if (!disk->store) - return 0; if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_EXPORT) { /* No real need to use nbd-server-remove, since we will * shortly be calling nbd-server-stop. */ @@ -17611,16 +17610,17 @@ qemuDomainBackupDiskCleanup(virQEMUDriverPtr driver, virDomainObjPtr vm, } if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_READY && qemuMonitorBlockdevDel(priv->mon, disk->store->nodeformat) < 0) { - VIR_WARN("Unable to remove temp disk %s after backup", - disk->name); + VIR_WARN("Unable to remove %s disk %s after backup", + push ? "target" : "scratch", disk->name); ret = -1; } if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_LABEL) qemuDomainStorageSourceAccessRevoke(driver, vm, disk->store); - if (disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_CREATED && + if ((!push || !completed) && + disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_CREATED && disk->store->detected && unlink(disk->store->path) < 0) { - VIR_WARN("Unable to unlink temp disk %s after backup", - disk->store->path); + VIR_WARN("Unable to unlink %s disk %s after backup", + push ? "failed target" : "scratch", disk->store->path); ret = -1; } return ret; @@ -17640,6 +17640,7 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, virJSONValuePtr json = NULL; bool job_started = false; bool nbd_running = false; + bool push; size_t i; struct timeval tv; char *suffix = NULL; @@ -17688,7 +17689,8 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, if (!(def = virDomainBackupDefParseString(diskXml, driver->xmlopt, 0))) goto cleanup; - if (def->type == VIR_DOMAIN_BACKUP_TYPE_PULL) { + push = def->type == VIR_DOMAIN_BACKUP_TYPE_PUSH; + if (!push) { if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_NBD_BITMAP)) { virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", _("qemu binary lacks pull-mode backup support")); @@ -17723,10 +17725,6 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, _("unexpected transport in <domainbackup>")); goto cleanup; } - } else { - virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", - _("push mode backups not supported yet")); - goto cleanup; } if (def->incremental) { if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_BITMAP_MERGE)) { @@ -17807,6 +17805,7 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, cmd = NULL; } + /* FIXME: allow non-local files for push destinations */ if (virJSONValueObjectCreate(&file, "s:driver", "file", "s:filename", disk->store->path, @@ -17847,7 +17846,7 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, "blockdev-backup", "s:device", src->nodeformat, "s:target", disk->store->nodeformat, - "s:sync", "none", + "s:sync", push ? "full" : "none", "s:job-id", disk->name, NULL) < 0) goto endmon; @@ -17860,7 +17859,7 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, - pull: nbd-server-start with <server> from user (or autogenerate server) - pull: nbd-server-add per <disk>, including bitmap for incr */ - if (def->type == VIR_DOMAIN_BACKUP_TYPE_PULL) { + if (!push) { if (qemuMonitorNBDServerStart(priv->mon, def->server, NULL) < 0) goto endmon; nbd_running = true; @@ -17891,11 +17890,14 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, for (i = 0; i < def->ndisks; i++) { virDomainBackupDiskDef *disk = &def->disks[i]; + if (!disk->store) + continue; if (job_started && qemuMonitorBlockJobCancel(priv->mon, disk->name) < 0) VIR_WARN("Unable to stop backup job %s on vm %s after failure", disk->store->nodeformat, vm->def->name); - qemuDomainBackupDiskCleanup(driver, vm, disk, !!def->incremental); + qemuDomainBackupDiskCleanup(driver, vm, disk, push, + !!def->incremental, false); } virSetError(save_err); virFreeError(save_err); @@ -17970,6 +17972,8 @@ static int qemuDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags) bool want_abort = flags & VIR_DOMAIN_BACKUP_END_ABORT; virDomainBackupDefPtr def; size_t i; + bool push = true; + bool completed = true; virCheckFlags(VIR_DOMAIN_BACKUP_END_ABORT, -1); @@ -17988,23 +17992,50 @@ static int qemuDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags) goto cleanup; } - if (priv->backup->type != VIR_DOMAIN_BACKUP_TYPE_PUSH) - want_abort = false; def = priv->backup; + if (def->type != VIR_DOMAIN_BACKUP_TYPE_PUSH) { + want_abort = false; + push = false; + } /* We are going to modify the domain below. */ if (qemuDomainObjBeginJob(driver, vm, QEMU_JOB_MODIFY) < 0) goto cleanup; qemuDomainObjEnterMonitor(driver, vm); - if (def->type == VIR_DOMAIN_BACKUP_TYPE_PULL) + if (push) { + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + + if (!disk->store) + continue; + if (disk->state != VIR_DOMAIN_BACKUP_DISK_STATE_COMPLETE) + completed = false; + } + } else { ret = qemuMonitorNBDServerStop(priv->mon); - for (i = 0; i < def->ndisks; i++) { - if (qemuMonitorBlockJobCancel(priv->mon, - def->disks[i].name) < 0 || - qemuDomainBackupDiskCleanup(driver, vm, &def->disks[i], - !!def->incremental) < 0) - ret = -1; + } + if (!completed && !want_abort) { + virReportError(VIR_ERR_OPERATION_INVALID, + _("backup job id '%d' not complete yet"), id); + } else { + for (i = 0; i < def->ndisks; i++) { + virDomainBackupDiskDef *disk = &def->disks[i]; + + if (!disk->store) + continue; + if (!push || disk->state < VIR_DOMAIN_BACKUP_DISK_STATE_COMPLETE) { + if (qemuMonitorBlockJobCancel(priv->mon, + disk->name) < 0 && + !want_abort) { + ret = -1; + continue; + } + } + if (qemuDomainBackupDiskCleanup(driver, vm, disk, push, + !!def->incremental, completed) < 0) + ret = -1; + } } if (qemuDomainObjExitMonitor(driver, vm) < 0 || ret < 0) { ret = -1; -- 2.20.1
Complete wiring up incremental backup, by adding in support for creating a checkpoint at the same time as a backup (make the transaction have a few more steps) as well as exposing the dirty bitmap for a prior backup over NBD (requires creating a temporary bitmap, merging all appropriate bitmaps in, then exposing that bitmap over NBD). Signed-off-by: Eric Blake <eblake@redhat.com> --- src/qemu/qemu_driver.c | 198 +++++++++++++++++++++++++++++++++++------ 1 file changed, 170 insertions(+), 28 deletions(-) diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index a7a9526d1e..69aa6b99e7 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -16977,6 +16977,24 @@ qemuDomainCheckpointPrepare(virQEMUDriverPtr driver, virCapsPtr caps, if (disk->type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP) continue; + /* We want to name temporary bitmap after disk name during + * incremental backup, which is not possible if that is a + * persistent bitmap name. We can also make life easier by + * enforcing bitmap names match checkpoint name, although this + * is not technically necessary. */ + if (STREQ(disk->name, disk->bitmap)) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("checkpoint for disk %s must have distinct bitmap name"), + disk->name); + goto cleanup; + } + if (STRNEQ(disk->bitmap, def->parent.name)) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("disk %s bitmap should match checkpoint name %s"), + disk->name, def->parent.name); + goto cleanup; + } + if (vm->def->disks[i]->src->format > 0 && vm->def->disks[i]->src->format != VIR_STORAGE_FILE_QCOW2) { virReportError(VIR_ERR_CONFIG_UNSUPPORTED, @@ -17557,19 +17575,44 @@ qemuDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, static int qemuDomainBackupPrepare(virQEMUDriverPtr driver, virDomainObjPtr vm, - virDomainBackupDefPtr def) + virDomainBackupDefPtr def, + virDomainMomentObjPtr chk) { int ret = -1; size_t i; + virDomainCheckpointDefPtr chkdef; + chkdef = chk ? virDomainCheckpointObjGetDef(chk) : NULL; + if (chk && def->ndisks != chkdef->ndisks) { + virReportError(VIR_ERR_INTERNAL_ERROR, "%s", + _("inconsistency between backup and checkpoint disks")); + goto cleanup; + } if (qemuBlockNodeNamesDetect(driver, vm, QEMU_ASYNC_JOB_NONE) < 0) goto cleanup; for (i = 0; i < def->ndisks; i++) { virDomainBackupDiskDef *disk = &def->disks[i]; virStorageSourcePtr src = vm->def->disks[disk->idx]->src; - if (!disk->store) + /* For now, insist that atomic checkpoint affect same disks as + * those being backed up. */ + if (!disk->store) { + if (chk && + chkdef->disks[i].type != VIR_DOMAIN_CHECKPOINT_TYPE_NONE) { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, + _("disk %s requested checkpoint without backup"), + disk->name); + goto cleanup; + } continue; + } + if (chk && + chkdef->disks[i].type != VIR_DOMAIN_CHECKPOINT_TYPE_BITMAP) { + virReportError(VIR_ERR_OPERATION_UNSUPPORTED, + _("disk %s requested backup without checkpoint"), + disk->name); + goto cleanup; + } if (virAsprintf(&disk->store->nodeformat, "tmp-%s", disk->name) < 0) goto cleanup; if (!disk->store->format) @@ -17603,7 +17646,7 @@ qemuDomainBackupDiskCleanup(virQEMUDriverPtr driver, virDomainObjPtr vm, * shortly be calling nbd-server-stop. */ } if (incremental && disk->state >= VIR_DOMAIN_BACKUP_DISK_STATE_BITMAP && - qemuMonitorDeleteBitmap(priv->mon, node, disk->store->nodeformat) < 0) { + qemuMonitorDeleteBitmap(priv->mon, node, disk->name) < 0) { VIR_WARN("Unable to remove temp bitmap for disk %s after backup", disk->name); ret = -1; @@ -17641,28 +17684,22 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, bool job_started = false; bool nbd_running = false; bool push; + const char *mode; size_t i; struct timeval tv; char *suffix = NULL; virCommandPtr cmd = NULL; const char *qemuImgPath; + virDomainMomentObjPtr chk = NULL; + virDomainMomentObjPtr other = NULL; + virDomainMomentObjPtr parent = NULL; + virDomainMomentObjPtr current; + virJSONValuePtr arr = NULL; + VIR_AUTOUNREF(virDomainCheckpointDefPtr) chkdef = NULL; virCheckFlags(VIR_DOMAIN_BACKUP_BEGIN_NO_METADATA, -1); /* TODO: VIR_DOMAIN_BACKUP_BEGIN_QUIESCE */ - // FIXME: Support non-null checkpointXML for incremental - what - // code can be shared with CheckpointCreateXML, then add to transaction - // to create new checkpoint at same time as starting blockdev-backup - if (checkpointXml) { - virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", - _("cannot create incremental backups yet")); - return -1; - } - // if (chk) VIR_STRDUP(suffix, chk->name); - gettimeofday(&tv, NULL); - if (virAsprintf(&suffix, "%lld", (long long)tv.tv_sec) < 0) - goto cleanup; - if (!(vm = qemuDomObjFromDomain(domain))) goto cleanup; @@ -17689,6 +17726,18 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, if (!(def = virDomainBackupDefParseString(diskXml, driver->xmlopt, 0))) goto cleanup; + if (checkpointXml) { + if (!(chkdef = qemuDomainCheckpointDefParseString(driver, caps, + checkpointXml, + NULL, 0)) || + VIR_STRDUP(suffix, chkdef->parent.name) < 0) + goto cleanup; + } else { + gettimeofday(&tv, NULL); + if (virAsprintf(&suffix, "%lld", (long long)tv.tv_sec) < 0) + goto cleanup; + } + push = def->type == VIR_DOMAIN_BACKUP_TYPE_PUSH; if (!push) { if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_NBD_BITMAP)) { @@ -17726,15 +17775,25 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, goto cleanup; } } + current = virDomainCheckpointGetCurrent(vm->checkpoints); if (def->incremental) { if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_BITMAP_MERGE)) { virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", _("qemu binary lacks persistent bitmaps support")); goto cleanup; } - virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", - _("cannot create incremental backups yet")); - goto cleanup; + for (other = current; other; + other = other->def->parent_name ? + virDomainCheckpointFindByName(vm->checkpoints, + other->def->parent_name) : NULL) + if (STREQ(other->def->name, def->incremental)) + break; + if (!other) { + virReportError(VIR_ERR_OPERATION_INVALID, + _("could not locate checkpoint '%s' for incremental backup"), + def->incremental); + goto cleanup; + } } if (!(qemuImgPath = qemuFindQemuImgBinary(driver))) @@ -17750,14 +17809,38 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, goto endjob; } + if (chkdef) { + if (!virQEMUCapsGet(priv->qemuCaps, QEMU_CAPS_BITMAP_MERGE)) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", + _("qemu binary lacks persistent bitmaps support")); + goto endjob; + } + + if (qemuDomainCheckpointPrepare(driver, caps, vm, chkdef) < 0) + goto endjob; + if (!(chk = virDomainCheckpointAssignDef(vm->checkpoints, chkdef))) + goto endjob; + chkdef = NULL; + if (current) { + parent = current; + if (VIR_STRDUP(chk->def->parent_name, parent->def->name) < 0) + goto endjob; + if (qemuDomainCheckpointWriteMetadata(vm, parent, driver->caps, + driver->xmlopt, + cfg->checkpointDir) < 0) + goto endjob; + } + } + if (virDomainBackupAlignDisks(def, vm->def, suffix) < 0 || - qemuDomainBackupPrepare(driver, vm, def) < 0) + qemuDomainBackupPrepare(driver, vm, def, chk) < 0) goto endjob; /* actually start the checkpoint. 2x2 array of push/pull, full/incr, plus additional tweak if checkpoint requested */ qemuDomainObjEnterMonitor(driver, vm); - /* - push/pull: blockdev-add per <disk> */ + /* - push/pull: blockdev-add per <disk> + - incr: bitmap-add of tmp, bitmap-merge per <disk> */ for (i = 0; i < def->ndisks; i++) { virDomainBackupDiskDef *disk = &def->disks[i]; virJSONValuePtr file; @@ -17823,11 +17906,32 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, goto endmon; json = NULL; disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_READY; + + if (def->incremental) { + if (!(arr = virJSONValueNewArray())) + goto endmon; + if (qemuMonitorAddBitmap(priv->mon, node, disk->name, false) < 0) { + virJSONValueFree(arr); + goto endmon; + } + disk->state = VIR_DOMAIN_BACKUP_DISK_STATE_BITMAP; + for (other = parent ? parent : current; other; + other = other->def->parent_name ? + virDomainCheckpointFindByName(vm->checkpoints, + other->def->parent_name) : NULL) { + if (virJSONValueArrayAppendString(arr, other->def->name) < 0) { + virJSONValueFree(arr); + goto endmon; + } + if (STREQ(other->def->name, def->incremental)) + break; + } + if (qemuMonitorMergeBitmaps(priv->mon, node, disk->name, &arr) < 0) + goto endmon; + } } - /* TODO: - - incr: bitmap-add of tmp, bitmap-merge per <disk> - - transaction, containing: + /* - transaction, containing: - push+full: blockdev-backup sync:full - push+incr: blockdev-backup sync:incremental bitmap:tmp - pull+full: blockdev-backup sync:none @@ -17836,24 +17940,61 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, */ if (!(json = virJSONValueNewArray())) goto endmon; + if (push) + mode = def->incremental ? "incremental" : "full"; + else + mode = "none"; for (i = 0; i < def->ndisks; i++) { virDomainBackupDiskDef *disk = &def->disks[i]; - virStorageSourcePtr src = vm->def->disks[disk->idx]->src; + const char *node; + const char *push_bitmap = NULL; if (!disk->store) continue; + node = qemuBlockNodeLookup(vm, disk->name); + if (push && def->incremental) + push_bitmap = disk->name; if (qemuMonitorJSONTransactionAdd(json, "blockdev-backup", - "s:device", src->nodeformat, + "s:device", node, "s:target", disk->store->nodeformat, - "s:sync", push ? "full" : "none", + "s:sync", mode, + "S:bitmap", push_bitmap, "s:job-id", disk->name, NULL) < 0) goto endmon; + if (def->incremental && !push && + qemuMonitorJSONTransactionAdd(json, + "block-dirty-bitmap-disable", + "s:node", node, + "s:name", disk->name, + NULL) < 0) + goto endmon; } + if (chk && qemuDomainCheckpointAddActions(vm, json, parent, + virDomainCheckpointObjGetDef(chk)) < 0) + goto endmon; if (qemuMonitorTransaction(priv->mon, &json) < 0) goto endmon; job_started = true; + if (chk) { + if (qemuDomainCheckpointWriteMetadata(vm, chk, driver->caps, + driver->xmlopt, + cfg->checkpointDir) < 0) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("unable to save metadata for checkpoint %s"), + chk->def->name); + virDomainCheckpointObjListRemove(vm->checkpoints, chk); + goto endmon; + } + virDomainCheckpointSetCurrent(vm->checkpoints, chk); + other = virDomainCheckpointFindByName(vm->checkpoints, + chk->def->parent_name); + chk->parent = other; + other->nchildren++; + chk->sibling = other->first_child; + other->first_child = chk; + } /* - pull: nbd-server-start with <server> from user (or autogenerate server) @@ -17895,7 +18036,7 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, if (job_started && qemuMonitorBlockJobCancel(priv->mon, disk->name) < 0) VIR_WARN("Unable to stop backup job %s on vm %s after failure", - disk->store->nodeformat, vm->def->name); + disk->name, vm->def->name); qemuDomainBackupDiskCleanup(driver, vm, disk, push, !!def->incremental, false); } @@ -17918,6 +18059,7 @@ qemuDomainBackupBegin(virDomainPtr domain, const char *diskXml, qemuDomainObjEndJob(driver, vm); cleanup: + virJSONValueFree(arr); virCommandFree(cmd); VIR_FREE(suffix); virJSONValueFree(json); -- 2.20.1
participants (2)
-
Eric Blake -
Peter Krempa