Upcoming patches plan to introduce virDomainCheckpointPtr as a new object for use in incremental backups, along with documentation how incremental backups differ from snapshots. But first, we need to rename any existing mention of a 'system checkpoint' to instead be a 'full system state snapshot', so that we aren't overloading the term checkpoint. Signed-off-by: Eric Blake <eblake(a)redhat.com&gt; --- Bikeshed suggestions on what to name the new object for use in backups is welcome, if we would rather keep the term 'checkpoint' for a disk+memory snapshot. --- docs/formatsnapshot.html.in | 14 +++++++------- include/libvirt/libvirt-domain-snapshot.h | 2 +- src/conf/snapshot_conf.c | 2 +- src/libvirt-domain-snapshot.c | 4 ++-- src/qemu/qemu_driver.c | 12 ++++++------ tools/virsh-snapshot.c | 2 +- tools/virsh.pod | 14 +++++++------- 7 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in index fbbecfd242..f2e51df5ab 100644 --- a/docs/formatsnapshot.html.in +++ b/docs/formatsnapshot.html.in @@ -33,7 +33,7 @@ resume in a consistent state; but if the disks are modified externally in the meantime, this is likely to lead to data corruption.</dd> - <dt>system checkpoint</dt> + <dt>full system state</dt> <dd>A combination of disk snapshots for all disks as well as VM memory state, which can be used to resume the guest from where it left off with symptoms similar to hibernation (that is, TCP @@ -55,7 +55,7 @@ as <code>virDomainSaveImageGetXMLDesc()</code> to work with those files. </p> - <p>System checkpoints are created + <p>Full system state snapshots are created by <code>virDomainSnapshotCreateXML()</code> with no flags, and disk snapshots are created by the same function with the <code>VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY</code> flag; in @@ -128,13 +128,13 @@ what file name is created in an external snapshot. On output, this is fully populated to show the state of each disk in the snapshot, including any properties that were generated by the - hypervisor defaults. For system checkpoints, this field is - ignored on input and omitted on output (a system checkpoint + hypervisor defaults. For full system state snapshots, this field is + ignored on input and omitted on output (a full system state snapshot implies that all disks participate in the snapshot process, and since the current implementation only does internal system - checkpoints, there are no extra details to add); a future + snapshots, there are no extra details to add); a future release may allow the use of <code>disks</code> with a system - checkpoint. This element has a list of <code>disk</code> + snapshot. This element has a list of <code>disk</code> sub-elements, describing anywhere from zero to all of the disks associated with the domain. <span class="since">Since 0.9.5</span> @@ -206,7 +206,7 @@ </dd> <dt><code>state</code></dt> <dd>The state of the domain at the time this snapshot was taken. - If the snapshot was created as a system checkpoint, then this + If the snapshot was created with full system state, then this is the state of the domain at that time; when the domain is reverted to this snapshot, the domain's state will default to whatever is in this field unless additional flags are passed diff --git a/include/libvirt/libvirt-domain-snapshot.h b/include/libvirt/libvirt-domain-snapshot.h index 0f73f24b2b..e5a893a767 100644 --- a/include/libvirt/libvirt-domain-snapshot.h +++ b/include/libvirt/libvirt-domain-snapshot.h @@ -58,7 +58,7 @@ typedef enum { VIR_DOMAIN_SNAPSHOT_CREATE_HALT = (1 << 3), /* Stop running guest after snapshot */ VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY = (1 << 4), /* disk snapshot, not - system checkpoint */ + full system state */ VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT = (1 << 5), /* reuse any existing external files */ VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE = (1 << 6), /* use guest agent to diff --git a/src/conf/snapshot_conf.c b/src/conf/snapshot_conf.c index 787c3d0feb..5efbef7e09 100644 --- a/src/conf/snapshot_conf.c +++ b/src/conf/snapshot_conf.c @@ -1307,7 +1307,7 @@ virDomainSnapshotRedefinePrep(virDomainPtr domain, (def->state == VIR_DOMAIN_DISK_SNAPSHOT)) { virReportError(VIR_ERR_INVALID_ARG, _("cannot change between disk snapshot and " - "system checkpoint in snapshot %s"), + "full system state in snapshot %s"), def->name); goto cleanup; } diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c index 100326a5e7..71881b2db2 100644 --- a/src/libvirt-domain-snapshot.c +++ b/src/libvirt-domain-snapshot.c @@ -105,7 +105,7 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) * contained in xmlDesc. * * If @flags is 0, the domain can be active, in which case the - * snapshot will be a system checkpoint (both disk state and runtime + * snapshot will be a full system state snapshot (both disk state and runtime * VM state such as RAM contents), where reverting to the snapshot is * the same as resuming from hibernation (TCP connections may have * timed out, but everything else picks up where it left off); or @@ -149,7 +149,7 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) * is not paused while creating the snapshot. This increases the size * of the memory dump file, but reduces downtime of the guest while * taking the snapshot. Some hypervisors only support this flag during - * external checkpoints. + * external snapshots. * * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY, then the * snapshot will be limited to the disks described in @xmlDesc, and no diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index 7c79c324e6..978c02fab9 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -2167,7 +2167,7 @@ qemuDomainReset(virDomainPtr dom, unsigned int flags) } -/* Count how many snapshots in a set are external snapshots or checkpoints. */ +/* Count how many snapshots in a set are external snapshots. */ static int qemuDomainSnapshotCountExternal(void *payload, const void *name ATTRIBUTE_UNUSED, @@ -14688,7 +14688,7 @@ qemuDomainSnapshotPrepare(virDomainObjPtr vm, if ((def->memory == VIR_DOMAIN_SNAPSHOT_LOCATION_INTERNAL && !found_internal) || (found_internal && forbid_internal)) { virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", - _("internal snapshots and checkpoints require all " + _("internal and full system state snapshots require all " "disks to be selected for snapshot")); goto cleanup; } @@ -15161,7 +15161,7 @@ qemuDomainSnapshotCreateActiveExternal(virQEMUDriverPtr driver, if (virDomainObjGetState(vm, NULL) == VIR_DOMAIN_PMSUSPENDED) { pmsuspended = true; } else if (virDomainObjGetState(vm, NULL) == VIR_DOMAIN_RUNNING) { - /* For external checkpoints (those with memory), the guest + /* For full system external snapshots (those with memory), the guest * must pause (either by libvirt up front, or by qemu after * _LIVE converges). For disk-only snapshots with multiple * disks, libvirt must pause externally to get all snapshots @@ -15398,7 +15398,7 @@ qemuDomainSnapshotCreateXML(virDomainPtr domain, redefine)) { virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", _("live snapshot creation is supported only " - "with external checkpoints")); + "with external full system state")); goto cleanup; } @@ -15518,12 +15518,12 @@ qemuDomainSnapshotCreateXML(virDomainPtr domain, } else if (virDomainObjIsActive(vm)) { if (flags & VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY || snap->def->memory == VIR_DOMAIN_SNAPSHOT_LOCATION_EXTERNAL) { - /* external checkpoint or disk snapshot */ + /* external full system or disk snapshot */ if (qemuDomainSnapshotCreateActiveExternal(driver, vm, snap, flags) < 0) goto endjob; } else { - /* internal checkpoint */ + /* internal full system */ if (qemuDomainSnapshotCreateActiveInternal(driver, vm, snap, flags) < 0) goto endjob; diff --git a/tools/virsh-snapshot.c b/tools/virsh-snapshot.c index 812fa91333..33e3107045 100644 --- a/tools/virsh-snapshot.c +++ b/tools/virsh-snapshot.c @@ -1432,7 +1432,7 @@ static const vshCmdOptDef opts_snapshot_list[] = { }, {.name = "active", .type = VSH_OT_BOOL, - .help = N_("filter by snapshots taken while active (system checkpoints)") + .help = N_("filter by snapshots taken while active (full system snapshots)") }, {.name = "disk-only", .type = VSH_OT_BOOL, diff --git a/tools/virsh.pod b/tools/virsh.pod index 3f3314a87e..cb0dbfa7dd 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -4468,8 +4468,8 @@ If I<--halt> is specified, the domain will be left in an inactive state after the snapshot is created. If I<--disk-only> is specified, the snapshot will only include disk -state rather than the usual system checkpoint with vm state. Disk -snapshots are faster than full system checkpoints, but reverting to a +state rather than the usual full system state snapshot with vm state. Disk +snapshots are faster than full system snapshots, but reverting to a disk snapshot may require fsck or journal replays, since it is like the disk state at the point when the power cord is abruptly pulled; and mixing I<--halt> and I<--disk-only> loses any data that was not @@ -4508,10 +4508,10 @@ this. If this flag is not specified, then some hypervisors may fail after partially performing the action, and B<dumpxml> must be used to see whether any partial changes occurred. -If I<--live> is specified, libvirt takes the snapshot (checkpoint) while +If I<--live> is specified, libvirt takes the snapshot while the guest is running. Both disk snapshot and domain memory snapshot are taken. This increases the size of the memory image of the external -checkpoint. This is currently supported only for external checkpoints. +snapshot. This is currently supported only for full system external snapshots. Existence of snapshot metadata will prevent attempts to B<undefine> a persistent domain. However, for transient domains, snapshot @@ -4531,7 +4531,7 @@ Otherwise, if I<--halt> is specified, the domain will be left in an inactive state after the snapshot is created, and if I<--disk-only> is specified, the snapshot will not include vm state. -The I<--memspec> option can be used to control whether a checkpoint +The I<--memspec> option can be used to control whether a full system snapshot is internal or external. The I<--memspec> flag is mandatory, followed by a B<memspec> of the form B<[file=]name[,snapshot=type]>, where type can be B<no>, B<internal>, or B<external>. To include a literal @@ -4539,7 +4539,7 @@ comma in B<file=name>, escape it with a second comma. I<--memspec> cannot be used together with I<--disk-only>. The I<--diskspec> option can be used to control how I<--disk-only> and -external checkpoints create external files. This option can occur +external full system snapshots create external files. This option can occur multiple times, according to the number of <disk> elements in the domain xml. Each <diskspec> is in the form B<disk[,snapshot=type][,driver=type][,file=name]>. A I<diskspec> @@ -4579,7 +4579,7 @@ see whether any partial changes occurred. If I<--live> is specified, libvirt takes the snapshot while the guest is running. This increases the size of the memory image of the external -checkpoint. This is currently supported only for external checkpoints. +snapshot. This is currently supported only for external full system snapshots. =item B<snapshot-current> I<domain> {[I<--name>] | [I<--security-info>] | [I<snapshotname>]} -- 2.14.4

On 06/22/2018 04:16 PM, John Ferlan wrote: That's a tough call. My current design has incremental backups completely separate from the existing checkpoint code for several reasons: - the snapshot code is already confusing with lots of flags (internal/external, disk/memory, etc) - snapshots can be reverted to (well, in theory - we STILL can't revert to an external snapshot cleanly, even though the design supports it) - incremental backups are not direct revert points so, rather than bolt something on to the existing design, I went with a new concept. As you found later in the series, I then tried to provide a good summary page describing the different pieces, and what tradeoffs are involved in order to know which approach will work for a given need. A sequence of snapshots are different points in time you can revert to. A sequence of checkpoints are different points in time you can use as the reference point for starting an incremental backup. So if we don't like the term 'checkpoint', maybe virDomainBlockBackupReference would work. But it is longer, and would make for some mouthful API names. Also, you commented elsewhere that 'virDomainBackupBegin' misses out on the fact that under the hood, it is a block operation (only disk state); would 'virDomainBlockBackupBegin' be any better? There are fewer APIs with the term 'Backup' than with 'Checkpoint', if we do want go with that particular rename. Okay, I can live with shortening the replacement to 'full system'. Don't know if it will happen in the v2 series that I hope to post later tonight, or if it would be done on top (my immediate short-term goal is to get a demo of incremental backups working, to show the API is usable; although the demo depends on unreleased qemu code so only the API would actually go in this month's libvirt release, while the underlying src/qemu/* changes can be delayed and polished to be better than the demo for the time when qemu 3.0 releases the needed bitmap/NBD features). Thanks for the careful grammar/legibility review. I'll try to fold in those suggestions (again, might not make it into v2). -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org

On 06/13/2018 12:42 PM, Eric Blake wrote: This got a lot messier than originally intended. As noted in my response for .1 - I haven't really followed the discussions thus far - so take it with that viewpoint - someone from outside the current discussion trying to make sense of what this topic is all about. I would alter the sentence at the comma... IOW: In order to aid ... their needs, this page compares ... by libvirt. Then rather than discussing this below - I think we really need to state right at the top the following: </p> <p> The information here is primarily geared towards capturing the state of the active domain. Capturing state of an inactive domain essentially only requires the contents of the guest disks and then restoring that state is merely a fresh boot with the disks restored to that state. There are aspects of the subsequent functionality that cover the inactive state collection, but it's not the primary focus. to me the commas are unnecessary. s/activity./activity. In this case, state includes domain memory including the current instruction stream and domain storage, whether that is local virtual disks which are not present on a target host or networked storage being updated by the local hypervisor. A clever... [BTW: In rereading my response - I almost want to add - "As it relates to domain checkpoints and backups, state only includes disk state change.". However, I'm not sure if that ties in yet or not. I think it only matters for the two new API's being discussed.] , then there is... s/,/ in order/ [BTW: The following includes something else I pulled up from the list below...] s/had. /had. The astute reader will also realize that state capture at any level requires that the data must be stored and managed by some mechanism. This processing may be to a single file or some set of chained files. This is the inflection point between where Libvirt would (could, should?) integrate with third party tools that are built around managing the volume of data possibly generated by multiple domains with multiple disks. This leaves the task of synchronizing the capture algorithms to Libvirt in order to be able to work seamlessly with the underlying hypervisor. <paragraph break> There are several libvirt APIs associated with ... (different is superfluous) s/, such that the captured state/which s/But since ... given task./The following is a list of trade-offs and differences between the various facets that affect capturing domain state for active domains:/ "Data Completeness" (or Integrity) corresponding s/preparation (the.../preparation. The ... s/started), while .../started. While .../ Feels like a paragraph break... Or even a whole new bullet: <dt>Quiescing of Data</dt> s/around either point in time/at any point in time/ That last sentence: Freezing guest I/O can be problematic depending on what the guest's expectations are and the duration of the freeze. Some software will rightfully panic once it is given the chance to realize it lost some number of seconds. In general though long pauses are unacceptable, so reducing the time spent frozen is a goal of management software. Still the balance for data integrity and completeness does require some amount of time. I pulled part of this to earlier - let's face it, the offline guest is not the focus of this work, so I think it's only worth discussing or noting that an API can handle active or inactive guests. <dt>Memory State only, Disk change only, or Both</dt> I ended up essentially moving this concept prior to the list of facets. I suppose it could go here too, but I'm not sure this ends up being so much of a tradeoff as opposed to an overall design decision made when deciding to implement some sort of backup solution. In the long run, the management software "doesn't care" where or how the data is stored - it's just providing the data. That last sentence could almost be it's own bullet "Impact to Active State". Libvirt already captures active state as part of normal processing by updates to the domain's active XML. So again, this isn't a facet affecting capturing state - it seems to be more of a statement related to the reality of what Libvirt can/should be expected to do vs. being able to allow configurability for external forces to make certain decisions. How about Full vs. Incremental Is there a "downside" to the time needed for ma[r]king the "first checkpoint"? Or do we dictate/assume that someone has some sort of backup already before starting the domain and updates thereafter are all incremental. FWIW: A couple of others that come to mind that are facets: <dt>Local or Remote Storage</dt> Domains that completely use remote storage may only need some mechanism to keep track of the guest memory state while using some external means to manage/track the remote storage. Still even with that, it's possible that the hypervisor has I/O's "in flight" to the network storage that could be "important data" in the big picture. So having the capability to have the management software keeping track of all disk state can be important. <dt>Network Latency</dt> Whether it's domain storage or the saving of the domain data into some remote storage, network latency has an impact on snapshot data. Having dedicated network capacity/bandwidth and/or properly set quality of service certainly helps. Perhaps in some way providing an example of a migration vs. pure save could be helpful - using of course the various facets. Something like: An example of the various facets in action is migration of a running guest. In order for the guest to be able to start on a target from whence it left off on a source, the guest has to get to a point where execution on the source is stopped, the last remaining changes occurring since the migration started are then transferred, and the guest is started on the target. The management software thus must keep track of the starting point and any changes since the starting point. These last changes are often referred to as dirty page tracking or dirty disk block bitmaps. At some point in time during the migration, the management software must freeze the source guest, transfer the dirty data, and then start the guest on the target. This period of time must be minimal. To minimize overall migration time, one is advised to use a dedicated network connection with a high quality of service. Alternatively saving the current state of the running guest can just be a point in time type operation which doesn't require updating the "last vestiges" of state prior to writing out the saved state file. The state file is the point in time of whatever is current and may contain incomplete data which if used to restart the guest could cause confusion or problems because some operation wasn't completed depending upon where in time the operation was commenced. Do you think perhaps it may be a good idea to list the pros and cons of each of the APIs? As in, why someone would want to use one over another? and of course which work together... s/For qemu/Using QEMU/ Some random grumbling from me about the complexity of SnapshotCreateXML interacting with BlockCommit ;-)... Still should perhaps the Block API's be listed first to create a grounding of what they do so that when discussed as part of this Snapshot section? Of course all that without getting in the gnarly details of using Block APIs. The SnapshotCreateXML API is a "complex maze" of flag usage where it's important to understand the nuances between active/inactive, internal/external, memory/disk/both, and reversion to the point in time. s/, and/ and/ realistically the part about tracking guest memory state is probably unnecessary. s/job (to .../job. To .../ s/jobs)./jobs./ s/, with/ with/ s/), or/) or/ s/(// s/)// The next two aren't even introduced yet... But I'd probably also want to know about virDomain{Save|ManagedSave[Image]} which while not snapshot level type API's, they can be used to save domain state information. And since we discussed quiesce and freeze/thaw above, should there should virDomainFS{Freeze|Thaw} be discussed - if only to note their usage? introduced. Still for grounding this was a good introduction. I think the order should be changed since before performing an incremental backup is possible there must be some way to set when time begins. s/, and/ and/ s/, so much as make/, rather it makes/ changed? The "When performing ... current backup" description is a bit confusing to read for me. So do I create Checkpoint before after the Backup or both? Hard to be simultaneous - one comes first. This reliance on one another gets really confusing... Using the term "Guest state" for Checkpoint to mean something different than Snapshot makes for difficult comprehension in the grand scheme of domain management. Of slight concern is that there's nothing in the Checkpoint or Backup API naming scheme that says this is for disk/block only. There's also nothing that would cause me to think they are related without reading their descriptions. > + <h2><a id="examples">Examples</a></h2> > + <p>The following two sequences both capture the disk state of a > + running guest, then complete with the guest running on its > + original disk image; but with a difference that an unexpected > + interruption during the first mode leaves a temporary wrapper > + file that must be accounted for, while interruption of the > + second mode has no impact to the guest.</p> > + <p>1. Backup via temporary snapshot > + <pre> > +virDomainFSFreeze() > +virDomainSnapshotCreateXML(VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY) > +virDomainFSThaw() > +third-party copy the backing file to backup storage # most time spent here > +virDomainBlockCommit(VIR_DOMAIN_BLOCK_COMMIT_ACTIVE) per disk > +wait for commit ready event per disk > +virDomainBlockJobAbort() per disk > + </pre></p> > + > + <p>2. Direct backup > + <pre> > +virDomainFSFreeze() > +virDomainBackupBegin() > +virDomainFSThaw() > +wait for push mode event, or pull data over NBD # most time spent here > +virDomainBackeupEnd() > + </pre></p> > + > + </body> > +</html> The examples certainly need more beef w/r/t description. Personally, I like the fact that we're heavily documenting things before writing the code rather than the opposite direction. John

On 06/13/2018 12:42 PM, Eric Blake wrote: The above hunk is separable (and push-able) as it's own patch, so you can consider it : Reviewed-by: John Ferlan <jferlan(a)redhat.com&gt; Naming scheme aside, the rest had one minor nit: [...] checkpoint John

On 06/26/2018 02:03 PM, Nir Soffer wrote: That's a pre-existing documentation issue (probably worth a separate cleanup patch to a lot of files, if it really does render better to tie the details to the 'Ptr' typedef rather than the opaque typedef). Copied from the existing VIR_ERR_INVALID_DOMAIN_SNAPSHOT. Sadly, there MUST be such a thing - it exists to (try and) catch bugs such as: void *ptr = virAPI1() (which returns virDomainPtr) virDomainCheckpointAPI2(ptr, ...) (which expects virDomainCheckpointPtr) where you are passing in the wrong type, or such as: virConnectPtr conn = virAPI1() virDomainCheckpointPtr chk = virAPI2(conn) virConnectClose(conn) virDomainCheckpointAPI3(chk) where you are passing in the right type but wrong order because the checkpoint depends on a connection that you have closed Such is the life of copy-and-paste. My excuse is that the code I copied from has the same sort of poor comment. Yes, except that libvirt already has the practice of distinguishing error messages according to which type was expected. This is a function for internal use only; it is not exported as a public function, but exists to mirror... ...this existing snapshot function with the exact same amount of zero comments. It was implemented in this patch, in src/datatypes.c. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org

On 06/13/2018 12:42 PM, Eric Blake wrote: Add a link in the format.html.in and index.html.in pages too. IMO: Strange opening line for something describing checkpoints. As I've read further, the fact that checkpoint and backup is only supported for qcow2 domain disks I would think needs to be up at the top here - front an center. No sense reading any further for raw disks. Yet another patch 2 "factor" related to choosing a backup plan. What to do if you have raw devices and how those should be handled. This would seem to preclude LUKS encrypted devices, true? What about disks with various levels of backingStore logic? I can only imagine some of the depth issues causing problems with that logic would be applicable here too with the hierarchical approach. s/, or/ or/ s/time,/time) s/time),/time, s/without,/without/ s/backup,/backup/ s/operation,/operation/ NB: virDomainBackupBegin doesn't exist yet. Still a few patches away. s/; the/. The s/creation,/creation/ s/XML/XML fields/ s/is/are/ "All" of them? Even the readonly ones? First sentence I think should start previous paragraph... What is inside the parenthesis is quite confusing and perhaps "forward thinking" considering not all checkpoint concepts are described yet. So you can create a "current" checkpoint or revert to a checkpoint making it current - so how then does a domain ever have checkpoints without a current checkpoint. Is this a chicken and egg problem? Can one merge two or more checkpoints? Let's say I have A, B, C, D, and E. I could care less about B, C, and D now and I want to merge them to create F which is essentially all 3 sets of changes leaving the time oriented order as A, F, E. I still don't see how a domain doesn't have a current checkpoint even though there are checkpoints. Does the live domain maintain a pointer to the checkpoint? Or are domaincheckpoint xml files only valid with their own context? How would the checkpoint code know if a domain was removed? Following events? s/following/following optional/ > + <dl> > + <dt><code>name</code></dt> > + <dd>The name for this checkpoint. If the name is specified when > + initially creating the checkpoint, then the checkpoint will have > + that particular name. If the name is omitted when initially > + creating the checkpoint, then libvirt will make up a name for > + the checkpoint, based on the time when it was created. Assuming epoch and that seems to be confirmed by the example. What does specific instructions mean in this context? Ah, well now you know why I added the note at the top... This is buried inside this description. I have visions of sugar plum fairies and QE teams using hot (un)plug to make life absolutely miserable in this regard. Setting aside hot [un]plug, this makes it's possible to define a subset of domain qcow2 disks to participate in the checkpoint/backup, fair statement? If not provided, then all qcow2 disks participate. s/the/the qcow2 formatted/ I honestly think you should just pick one the target dev and be done, but I assume there's a reason for both which I don't understand yet. So now I'm confused again. Initially it seemed as though the <disk> sub-elements would be the only ones participating, but now it feels like it's possible to pick and choose to what level something participates. If nothing is provided, can someone change the 'checkpoint' attribute to 'no' (assuming the default is 'bitmap')? This is all rather mind boggling - why can stuff never be simple /-| The whole initial inactive/config XML is loaded here? Or just certain fields. The example XML output has just a UUID, but the data here has a lot more and the RNG shows everything. Did I read something wrong earlier regarding saving domain state? I though the checkpoint/backup code was purely for the domain disks that are of type qcow2. I can see saving the UUID since that cannot change (unlike the name)... But why does the entire "original" config need to be added here? > + </dd> > + </dl> > + > + <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. 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). I think the modes should be described in own bullets rather than part of a long-ish sentence using parentheses to help define what is meant. Perhaps even more verbiage regarding general usage expectations of each model. s/Where/Although ??? s/model,/model/ > + or what file names libvirt generated when none were supplied). > + The following child elements are supported: > + <dl> Since all elements are optional, probably don't have to note it again for each description... s/domain,/domain/ The wording in the parentheses doesn't make complete sense yet. Perhaps it's better to have each as a bullet describing the action of the element for the backup "mode" value. contents ? This hunk above uses <tab>'s not spaces (syntax-check) again, qcow2 formatted disks, right? Is that true for both mode's of backup? network s/,/ and/ sub-element sub-element sub-element Well, suffice to say, I'm lost. I guess I at least am getting an idea why no consensus has been reached yet. > + > + <h2><a id="example">Examples</a></h2> > + > + <p>Using this XML to create a checkpoint of just vda on a qemu > + domain with two disks and a prior checkpoint:</p> > + <pre> > +&lt;domaincheckpoint&gt; > + &lt;description&gt;Completion of updates after OS install&lt;/description&gt; > + &lt;disks&gt; > + &lt;disk name='vda' checkpoint='bitmap'/&gt; > + &lt;disk name='vdb' checkpoint='no'/&gt; > + &lt;/disks&gt; > +&lt;/domaincheckpoint&gt;</pre> > + > + <p>will result in XML similar to this from > + <code>virDomainCheckpointGetXMLDesc()</code>:</p> > + <pre> > +&lt;domaincheckpoint&gt; > + &lt;name&gt;1525889631&lt;/name&gt; > + &lt;description&gt;Completion of updates after OS install&lt;/description&gt; > + &lt;creationTime&gt;1525889631&lt;/creationTime&gt; > + &lt;parent&gt; > + &lt;name&gt;1525111885&lt;/name&gt; > + &lt;/parent&gt; > + &lt;disks&gt; > + &lt;disk name='vda' checkpoint='bitmap' bitmap='1525889631'/&gt; > + &lt;disk name='vdb' checkpoint='no'/&gt; > + &lt;/disks&gt; > + &lt;domain&gt; > + &lt;name&gt;fedora&lt;/name&gt; > + &lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt; > + &lt;memory&gt;1048576&lt;/memory&gt; > + ... > + &lt;devices&gt; > + &lt;disk type='file' device='disk'&gt; > + &lt;driver name='qemu' type='qcow2'/&gt; > + &lt;source file='/path/to/file1'/&gt; > + &lt;target dev='vda' bus='virtio'/&gt; > + &lt;/disk&gt; > + &lt;disk type='file' device='disk' snapshot='external'&gt; > + &lt;driver name='qemu' type='raw'/&gt; > + &lt;source file='/path/to/file2'/&gt; > + &lt;target dev='vdb' bus='virtio'/&gt; > + &lt;/disk&gt; > + ... > + &lt;/devices&gt; > + &lt;/domain&gt; > +&lt;/domaincheckpoint&gt;</pre> > + > + <p>With that checkpoint created, the qcow2 image is now tracking > + all changes that occur in the image since the checkpoint via > + the persistent bitmap named <code>1525889631</code>. Now, we > + can make a subsequent call > + to <code>virDomainBackupBegin()</code> to perform an incremental > + backup of just this data, using the following XML to start a > + pull model NBD export of the vda disk: > + <pre> > +&lt;domainbackup mode="pull"&gt; > + &lt;incremental&gt;1525889631&lt;/incremental&gt; > + &lt;server transport="unix" socket="/path/to/server"/&gt; > + &lt;disks/&gt; > + &lt;disk name='vda' type='file'/&gt; > + &lt;scratch file=/path/to/file1.scratch'/&gt; > + &lt;/disk&gt; > + &lt;/disks/&gt; > +&lt;/domainbackup&gt; > + </pre> > + </body> > +</html> > diff --git a/docs/schemas/domaincheckpoint.rng b/docs/schemas/domaincheckpoint.rng > new file mode 100644 > index 0000000000..1e2c16e035 > --- /dev/null > +++ b/docs/schemas/domaincheckpoint.rng > @@ -0,0 +1,89 @@ > +<?xml version="1.0"?> > +<!-- A Relax NG schema for the libvirt domain checkpoint properties XML format --> > +<grammar xmlns="http://relaxng.org/ns/structure/1.0"> > + <start> > + <ref name='domaincheckpoint'/> > + </start> > + > + <include href='domaincommon.rng'/> > + > + <define name='domaincheckpoint'> > + <element name='domaincheckpoint'> > + <interleave> > + <optional> > + <element name='name'> > + <text/> > + </element> > + </optional> > + <optional> > + <element name='description'> > + <text/> > + </element> > + </optional> > + <optional> > + <element name='creationTime'> > + <text/> > + </element> > + </optional> > + <optional> > + <element name='disks'> > + <zeroOrMore> > + <ref name='diskcheckpoint'/> > + </zeroOrMore> > + </element> > + </optional> > + <optional> > + <choice> > + <element name='domain'> > + <element name='uuid'> > + <ref name="UUID"/> > + </element> > + </element> > + <!-- Nested grammar ensures that any of our overrides of > + storagecommon/domaincommon defines do not conflict > + with any domain.rng overrides. --> > + <grammar> > + <include href='domain.rng'/> > + </grammar> > + </choice> > + </optional> > + <optional> > + <element name='parent'> > + <element name='name'> > + <text/> > + </element> > + </element> > + </optional> > + </interleave> > + </element> > + </define> Since everything is optional, does <optional> have be supplied for each element or can there be one <optional> before the <interleave>? I see no <domainbackup> definition yet either - I assume it's coming. John

On Wed, Jun 13, 2018 at 7:42 PM Eric Blake <eblake(a)redhat.com&gt; wrote: id=CheckpointXML? Not clear. Also not clear. Thanks for the extra context. So the user is responsible for creating checkpoints names? Do we use these the same name in qcow2? This seems too complex. Why do we need arbitrary trees of checkpoints? What is the meaning of reverting a checkpoint? Why not simplify and require the use to provide a name? Why not always specify the disks? Seems too complicated. Why do we need to support a checkpoint referencing a bitmap with a different name? Instead we can have a list of disk that will participate in the checkpoint. Anything not specified will not participate in the snapshot. The name of the checkpoint is always the name of the bitmap. I think we are missing here the size of the underlying data in every disk. This probably means how many dirty bits we have in the bitmaps referenced by the checkpoint for every disk. What do you mean by "inactive domain configuration"? + </p> Just to make it clear: For example we start with: c1 c2 [c3] c3 is the active checkpoint. We create a new checkpoint: c1 c2 c3 [c4] So - using incremental=c2, we will get data referenced by c2? - using incremental=c1, we will get data reference by both c1 and c2? What if we want to backup only data from c1 to c2, not including c3? I don't have a use case for this, but if we can specify tow checkpoints this can be possible. For example: <chekpoints from="c1", to="c2"> Or <checkpoints from="c2"> To get the list of changed blocks, we planned to use something like: qemu-img map nbd+unix:/socket=server.sock Is this possible now? planned? To get the actual data, oVirt needs a device to read from. We don't want to write nbd-client, and we cannot use qemu-img since it does not support streaming data, and we want to stream data using http to the backup application. I guess we will have do this: qemu-nbd -c /dev/nbd0 nbd+unix:/socket=server.sock And serve the data from /dev/nbd0. This should be similar to the way we specify disks for vm, right? Anything that works as vm disk will work for pushing backups? I will continue with the rest of the patch later. Nir + </dd>

Introduce a bunch of new public APIs related to backup checkpoints. Checkpoints are modeled heavily after virDomainSnapshotPtr (both represent a point in time of the guest), although a snapshot exists with the intent of rolling back to that state, while a checkpoint exists to make it possible to create an incremental backup at a later time. Signed-off-by: Eric Blake <eblake(a)redhat.com&gt; --- docs/Makefile.am | 3 + docs/apibuild.py | 2 + docs/docs.html.in | 1 + include/libvirt/libvirt-domain-checkpoint.h | 147 ++++++ include/libvirt/libvirt.h | 5 +- libvirt.spec.in | 1 + mingw-libvirt.spec.in | 2 + po/POTFILES | 1 + src/Makefile.am | 2 + src/driver-hypervisor.h | 60 ++- src/libvirt-domain-checkpoint.c | 708 ++++++++++++++++++++++++++++ src/libvirt_public.syms | 16 + 12 files changed, 944 insertions(+), 4 deletions(-) create mode 100644 include/libvirt/libvirt-domain-checkpoint.h create mode 100644 src/libvirt-domain-checkpoint.c diff --git a/docs/Makefile.am b/docs/Makefile.am index 9620587a77..0df8ebbd64 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -25,6 +25,7 @@ apihtml = \ apihtml_generated = \ html/libvirt-libvirt-common.html \ html/libvirt-libvirt-domain.html \ + html/libvirt-libvirt-domain-checkpoint.html \ html/libvirt-libvirt-domain-snapshot.html \ html/libvirt-libvirt-event.html \ html/libvirt-libvirt-host.html \ @@ -318,6 +319,7 @@ $(python_generated_files): $(APIBUILD_STAMP) $(APIBUILD_STAMP): $(srcdir)/apibuild.py \ $(top_srcdir)/include/libvirt/libvirt.h \ $(top_srcdir)/include/libvirt/libvirt-common.h.in \ + $(top_srcdir)/include/libvirt/libvirt-domain-checkpoint.h \ $(top_srcdir)/include/libvirt/libvirt-domain-snapshot.h \ $(top_srcdir)/include/libvirt/libvirt-domain.h \ $(top_srcdir)/include/libvirt/libvirt-event.h \ @@ -334,6 +336,7 @@ $(APIBUILD_STAMP): $(srcdir)/apibuild.py \ $(top_srcdir)/include/libvirt/libvirt-admin.h \ $(top_srcdir)/include/libvirt/virterror.h \ $(top_srcdir)/src/libvirt.c \ + $(top_srcdir)/src/libvirt-domain-checkpoint.c \ $(top_srcdir)/src/libvirt-domain-snapshot.c \ $(top_srcdir)/src/libvirt-domain.c \ $(top_srcdir)/src/libvirt-host.c \ diff --git a/docs/apibuild.py b/docs/apibuild.py index 5e218a9ad0..471547cea7 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -26,6 +26,7 @@ debugsym = None included_files = { "libvirt-common.h": "header with general libvirt API definitions", "libvirt-domain.h": "header with general libvirt API definitions", + "libvirt-domain-checkpoint.h": "header with general libvirt API definitions", "libvirt-domain-snapshot.h": "header with general libvirt API definitions", "libvirt-event.h": "header with general libvirt API definitions", "libvirt-host.h": "header with general libvirt API definitions", @@ -39,6 +40,7 @@ included_files = { "virterror.h": "header with error specific API definitions", "libvirt.c": "Main interfaces for the libvirt library", "libvirt-domain.c": "Domain interfaces for the libvirt library", + "libvirt-domain-checkpoint.c": "Domain checkpoint interfaces for the libvirt library", "libvirt-domain-snapshot.c": "Domain snapshot interfaces for the libvirt library", "libvirt-host.c": "Host interfaces for the libvirt library", "libvirt-interface.c": "Interface interfaces for the libvirt library", diff --git a/docs/docs.html.in b/docs/docs.html.in index 11dfd27ba6..63dbdf7755 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -97,6 +97,7 @@ <dd>Reference manual for the C public API, split in <a href="html/libvirt-libvirt-common.html">common</a>, <a href="html/libvirt-libvirt-domain.html">domain</a>, + <a href="html/libvirt-libvirt-domain-checkpoint.html">domain checkpoint</a>, <a href="html/libvirt-libvirt-domain-snapshot.html">domain snapshot</a>, <a href="html/libvirt-virterror.html">error</a>, <a href="html/libvirt-libvirt-event.html">event</a>, diff --git a/include/libvirt/libvirt-domain-checkpoint.h b/include/libvirt/libvirt-domain-checkpoint.h new file mode 100644 index 0000000000..4a7dc73089 --- /dev/null +++ b/include/libvirt/libvirt-domain-checkpoint.h @@ -0,0 +1,147 @@ +/* + * libvirt-domain-checkpoint.h + * Summary: APIs for management of domain checkpoints + * Description: Provides APIs for the management of domain checkpoints + * Author: Eric Blake <eblake(a)redhat.com&gt; + * + * Copyright (C) 2006-2018 Red Hat, Inc. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see + * <http://www.gnu.org/licenses/>;. + */ + +#ifndef __VIR_LIBVIRT_DOMAIN_CHECKPOINT_H__ +# define __VIR_LIBVIRT_DOMAIN_CHECKPOINT_H__ + +# ifndef __VIR_LIBVIRT_H_INCLUDES__ +# error "Don't include this file directly, only use libvirt/libvirt.h" +# endif + +/** + * virDomainCheckpoint: + * + * A virDomainCheckpoint is a private structure representing a checkpoint of + * a domain. A checkpoint is useful for tracking which portions of the + * domain disks have been altered since a point in time, but by itself does + * not allow reverting back to that point in time. + */ +typedef struct _virDomainCheckpoint virDomainCheckpoint; + +/** + * virDomainCheckpointPtr: + * + * A virDomainCheckpointPtr is pointer to a virDomainCheckpoint + * private structure, and is the type used to reference a domain + * checkpoint in the API. + */ +typedef virDomainCheckpoint *virDomainCheckpointPtr; + +const char *virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint); +virDomainPtr virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint); +virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint); + +typedef enum { + VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE = (1 << 0), /* Restore or alter + metadata */ + VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT = (1 << 1), /* With redefine, make + checkpoint current */ + VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA = (1 << 2), /* Make checkpoint without + remembering it */ +} virDomainCheckpointCreateFlags; + +/* Create a checkpoint using the current VM state. */ +virDomainCheckpointPtr virDomainCheckpointCreateXML(virDomainPtr domain, + const char *xmlDesc, + unsigned int flags); + +/* Dump the XML of a checkpoint */ +char *virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/** + * virDomainCheckpointListFlags: + * + * Flags valid for virDomainListCheckpoints() and + * virDomainCheckpointListChildren(). Note that the interpretation of + * flag (1<<0) depends on which function it is passed to; but serves + * to toggle the per-call default of whether the listing is shallow or + * recursive. Remaining bits come in groups; if all bits from a group + * are 0, then that group is not used to filter results. */ +typedef enum { + VIR_DOMAIN_CHECKPOINT_LIST_ROOTS = (1 << 0), /* Filter by checkpoints + with no parents, when + listing a domain */ + VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS = (1 << 0), /* List all descendants, + not just children, when + listing a checkpoint */ + + VIR_DOMAIN_CHECKPOINT_LIST_LEAVES = (1 << 1), /* Filter by checkpoints + with no children */ + VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES = (1 << 2), /* Filter by checkpoints + that have children */ + + VIR_DOMAIN_CHECKPOINT_LIST_METADATA = (1 << 3), /* Filter by checkpoints + which have metadata */ + VIR_DOMAIN_CHECKPOINT_LIST_NO_METADATA = (1 << 4), /* Filter by checkpoints + with no metadata */ +} virDomainCheckpointListFlags; + +/* Get all checkpoint objects for this domain */ +int virDomainListCheckpoints(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags); + +/* Get all checkpoint object children for this checkpoint */ +int virDomainCheckpointListChildren(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags); + +/* Get a handle to a named checkpoint */ +virDomainCheckpointPtr virDomainCheckpointLookupByName(virDomainPtr domain, + const char *name, + unsigned int flags); + +/* Check whether a domain has a checkpoint which is currently used */ +int virDomainHasCurrentCheckpoint(virDomainPtr domain, unsigned int flags); + +/* Get a handle to the current checkpoint */ +virDomainCheckpointPtr virDomainCheckpointCurrent(virDomainPtr domain, + unsigned int flags); + +/* Get a handle to the parent checkpoint, if one exists */ +virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/* Determine if a checkpoint is the current checkpoint of its domain. */ +int virDomainCheckpointIsCurrent(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/* Determine if checkpoint has metadata that would prevent domain deletion. */ +int virDomainCheckpointHasMetadata(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/* Delete a checkpoint */ +typedef enum { + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = (1 << 0), /* Also delete children */ + VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata */ + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY = (1 << 2), /* Delete just children */ +} virDomainCheckpointDeleteFlags; + +int virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +int virDomainCheckpointRef(virDomainCheckpointPtr checkpoint); +int virDomainCheckpointFree(virDomainCheckpointPtr checkpoint); + +#endif /* __VIR_LIBVIRT_DOMAIN_CHECKPOINT_H__ */ diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h index 26887a40e7..4e7da0afc4 100644 --- a/include/libvirt/libvirt.h +++ b/include/libvirt/libvirt.h @@ -4,7 +4,7 @@ * Description: Provides the interfaces of the libvirt library to handle * virtualized domains * - * Copyright (C) 2005-2006, 2010-2014 Red Hat, Inc. + * Copyright (C) 2005-2006, 2010-2018 Red Hat, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -36,8 +36,7 @@ extern "C" { # include <libvirt/libvirt-common.h> # include <libvirt/libvirt-host.h> # include <libvirt/libvirt-domain.h> -typedef struct _virDomainCheckpoint virDomainCheckpoint; -typedef virDomainCheckpoint *virDomainCheckpointPtr; +# include <libvirt/libvirt-domain-checkpoint.h> # include <libvirt/libvirt-domain-snapshot.h> # include <libvirt/libvirt-event.h> # include <libvirt/libvirt-interface.h> diff --git a/libvirt.spec.in b/libvirt.spec.in index 50bd79a7d7..a82e97f3db 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -2102,6 +2102,7 @@ exit 0 %{_includedir}/libvirt/libvirt-admin.h %{_includedir}/libvirt/libvirt-common.h %{_includedir}/libvirt/libvirt-domain.h +%{_includedir}/libvirt/libvirt-domain-checkpoint.h %{_includedir}/libvirt/libvirt-domain-snapshot.h %{_includedir}/libvirt/libvirt-event.h %{_includedir}/libvirt/libvirt-host.h diff --git a/mingw-libvirt.spec.in b/mingw-libvirt.spec.in index 6912527cf7..3b41e69661 100644 --- a/mingw-libvirt.spec.in +++ b/mingw-libvirt.spec.in @@ -269,6 +269,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh %{mingw32_includedir}/libvirt/libvirt.h %{mingw32_includedir}/libvirt/libvirt-common.h %{mingw32_includedir}/libvirt/libvirt-domain.h +%{mingw32_includedir}/libvirt/libvirt-domain-checkpoint.h %{mingw32_includedir}/libvirt/libvirt-domain-snapshot.h %{mingw32_includedir}/libvirt/libvirt-event.h %{mingw32_includedir}/libvirt/libvirt-host.h @@ -355,6 +356,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh %{mingw64_includedir}/libvirt/libvirt.h %{mingw64_includedir}/libvirt/libvirt-common.h %{mingw64_includedir}/libvirt/libvirt-domain.h +%{mingw64_includedir}/libvirt/libvirt-domain-checkpoint.h %{mingw64_includedir}/libvirt/libvirt-domain-snapshot.h %{mingw64_includedir}/libvirt/libvirt-event.h %{mingw64_includedir}/libvirt/libvirt-host.h diff --git a/po/POTFILES b/po/POTFILES index be2874487c..d246657188 100644 --- a/po/POTFILES +++ b/po/POTFILES @@ -69,6 +69,7 @@ src/interface/interface_backend_netcf.c src/interface/interface_backend_udev.c src/internal.h src/libvirt-admin.c +src/libvirt-domain-checkpoint.c src/libvirt-domain-snapshot.c src/libvirt-domain.c src/libvirt-host.c diff --git a/src/Makefile.am b/src/Makefile.am index db8c8ebd1a..d20d65574e 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -174,6 +174,7 @@ DRIVER_SOURCES += \ $(DATATYPES_SOURCES) \ libvirt.c libvirt_internal.h \ libvirt-domain.c \ + libvirt-domain-checkpoint.c \ libvirt-domain-snapshot.c \ libvirt-host.c \ libvirt-interface.c \ @@ -728,6 +729,7 @@ libvirt_setuid_rpc_client_la_SOURCES = \ datatypes.c \ libvirt.c \ libvirt-domain.c \ + libvirt-domain-checkpoint.c \ libvirt-domain-snapshot.c \ libvirt-host.c \ libvirt-interface.c \ diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h index eef31eb1f0..ee8a9a3e0e 100644 --- a/src/driver-hypervisor.h +++ b/src/driver-hypervisor.h @@ -1,7 +1,7 @@ /* * driver-hypervisor.h: entry points for hypervisor drivers * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2018 Red Hat, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -1321,6 +1321,53 @@ typedef int int *nparams, unsigned int flags); +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointCreateXML)(virDomainPtr domain, + const char *xmlDesc, + unsigned int flags); + +typedef char * +(*virDrvDomainCheckpointGetXMLDesc)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef int +(*virDrvDomainListCheckpoints)(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointListChildren)(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags); + +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointLookupByName)(virDomainPtr domain, + const char *name, + unsigned int flags); + +typedef int +(*virDrvDomainHasCurrentCheckpoint)(virDomainPtr domain, + unsigned int flags); + +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointGetParent)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointCurrent)(virDomainPtr domain, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointIsCurrent)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointHasMetadata)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointDelete)(virDomainCheckpointPtr checkpoint, + unsigned int flags); typedef struct _virHypervisorDriver virHypervisorDriver; typedef virHypervisorDriver *virHypervisorDriverPtr; @@ -1572,6 +1619,17 @@ struct _virHypervisorDriver { virDrvConnectBaselineHypervisorCPU connectBaselineHypervisorCPU; virDrvNodeGetSEVInfo nodeGetSEVInfo; virDrvDomainGetLaunchSecurityInfo domainGetLaunchSecurityInfo; + virDrvDomainCheckpointCreateXML domainCheckpointCreateXML; + virDrvDomainCheckpointGetXMLDesc domainCheckpointGetXMLDesc; + virDrvDomainListCheckpoints domainListCheckpoints; + virDrvDomainCheckpointListChildren domainCheckpointListChildren; + virDrvDomainCheckpointLookupByName domainCheckpointLookupByName; + virDrvDomainHasCurrentCheckpoint domainHasCurrentCheckpoint; + virDrvDomainCheckpointGetParent domainCheckpointGetParent; + virDrvDomainCheckpointCurrent domainCheckpointCurrent; + virDrvDomainCheckpointIsCurrent domainCheckpointIsCurrent; + virDrvDomainCheckpointHasMetadata domainCheckpointHasMetadata; + virDrvDomainCheckpointDelete domainCheckpointDelete; }; diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c new file mode 100644 index 0000000000..12511a13ee --- /dev/null +++ b/src/libvirt-domain-checkpoint.c @@ -0,0 +1,708 @@ +/* + * libvirt-domain-checkpoint.c: entry points for virDomainCheckpointPtr APIs + * + * Copyright (C) 2006-2014, 2018 Red Hat, Inc. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see + * <http://www.gnu.org/licenses/>;. + */ + +#include <config.h> + +#include "datatypes.h" +#include "virlog.h" + +VIR_LOG_INIT("libvirt.domain-checkpoint"); + +#define VIR_FROM_THIS VIR_FROM_DOMAIN_CHECKPOINT + +/** + * virDomainCheckpointGetName: + * @checkpoint: a checkpoint object + * + * Get the public name for that checkpoint + * + * Returns a pointer to the name or NULL, the string need not be deallocated + * as its lifetime will be the same as the checkpoint object. + */ +const char * +virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + + return checkpoint->name; +} + + +/** + * virDomainCheckpointGetDomain: + * @checkpoint: a checkpoint object + * + * Provides the domain pointer associated with a checkpoint. The + * reference counter on the domain is not increased by this + * call. + * + * Returns the domain or NULL. + */ +virDomainPtr +virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + + return checkpoint->domain; +} + + +/** + * virDomainCheckpointGetConnect: + * @checkpoint: a checkpoint object + * + * Provides the connection pointer associated with a checkpoint. The + * reference counter on the connection is not increased by this + * call. + * + * Returns the connection or NULL. + */ +virConnectPtr +virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + + return checkpoint->domain->conn; +} + + +/** + * virDomainCheckpointCreateXML: + * @domain: a domain object + * @xmlDesc: description of the checkpoint to create + * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags + * + * Create a new checkpoint using @xmlDesc on a running @domain. + * Typically, it is more common to create a new checkpoint as part of + * kicking off a backup job with virDomainBackupBegin(); however, it + * is also possible to start a checkpoint without a backup. + * + * See formatcheckpoint.html#CheckpointAttributes document for more + * details on @xmlDesc. + * + * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, then this + * is a request to reinstate checkpoint metadata that was previously + * discarded, rather than creating a new checkpoint. When redefining + * checkpoint metadata, the current checkpoint will not be altered + * unless the VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT flag is also + * present. It is an error to request the + * VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT flag without + * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE. + * + * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA, then + * the domain's disk images are modified according to @xmlDesc, but + * then the just-created checkpoint has its metadata deleted. This + * flag is incompatible with VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE. + * + * Returns an (opaque) new virDomainCheckpointPtr on success, or NULL + * on failure. + */ +virDomainCheckpointPtr +virDomainCheckpointCreateXML(virDomainPtr domain, + const char *xmlDesc, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=0x%x", xmlDesc, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + virCheckNonNullArgGoto(xmlDesc, error); + virCheckReadOnlyGoto(conn->flags, error); + + VIR_REQUIRE_FLAG_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT, + VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, + error); + + VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, + VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA, + error); + + if (conn->driver->domainCheckpointCreateXML) { + virDomainCheckpointPtr ret; + ret = conn->driver->domainCheckpointCreateXML(domain, xmlDesc, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainCheckpointGetXMLDesc: + * @checkpoint: a domain checkpoint object + * @flags: bitwise-OR of subset of virDomainXMLFlags + * + * Provide an XML description of the domain checkpoint. + * + * No security-sensitive data will be included unless @flags contains + * VIR_DOMAIN_XML_SECURE; this flag is rejected on read-only + * connections. For this API, @flags should not contain either + * VIR_DOMAIN_XML_INACTIVE or VIR_DOMAIN_XML_UPDATE_CPU. + * + * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. + * the caller must free() the returned value. + */ +char * +virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + conn = checkpoint->domain->conn; + + if ((conn->flags & VIR_CONNECT_RO) && (flags & VIR_DOMAIN_XML_SECURE)) { + virReportError(VIR_ERR_OPERATION_DENIED, "%s", + _("virDomainCheckpointGetXMLDesc with secure flag")); + goto error; + } + + if (conn->driver->domainCheckpointGetXMLDesc) { + char *ret; + ret = conn->driver->domainCheckpointGetXMLDesc(checkpoint, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainListCheckpoints: + * @domain: a domain object + * @checkpoints: pointer to variable to store the array containing checkpoint + * objects, or NULL if the list is not required (just returns + * number of checkpoints) + * @flags: bitwise-OR of supported virDomainCheckpoinListFlags + * + * Collect the list of domain checkpoints for the given domain, and allocate + * an array to store those objects. + * + * By default, this command covers all checkpoints; it is also possible to + * limit things to just checkpoints with no parents, when @flags includes + * VIR_DOMAIN_CHECKPOINT_LIST_ROOTS. Additional filters are provided in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a checkpoint, and where all bits within a group describe + * all possible checkpoints. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a hypervisor may return + * either 0 or an error. + * + * The first group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_LEAVES and + * VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES, to filter based on checkpoints that + * have no further children (a leaf checkpoint). + * + * The next group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_METADATA and + * VIR_DOMAIN_CHECKPOINT_LIST_NO_METADATA, for filtering checkpoints based on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * Returns the number of domain checkpoints found or -1 and sets @checkpoints + * to NULL in case of error. On success, the array stored into @checkpoints + * is guaranteed to have an extra allocated element set to NULL but not + * included in the return count, to make iteration easier. The caller is + * responsible for calling virDomainCheckpointFree() on each array element, + * then calling free() on @checkpoints. + */ +int +virDomainListCheckpoints(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "checkpoints=%p, flags=0x%x", checkpoints, flags); + + virResetLastError(); + + if (checkpoints) + *checkpoints = NULL; + + virCheckDomainReturn(domain, -1); + conn = domain->conn; + + if (conn->driver->domainListCheckpoints) { + int ret = conn->driver->domainListCheckpoints(domain, checkpoints, + flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointListChildren: + * @checkpoint: a domain checkpoint object + * @children: pointer to variable to store the array containing checkpoint + * objects, or NULL if the list is not required (just returns + * number of checkpoints) + * @flags: bitwise-OR of supported virDomainCheckpointListFlags + * + * Collect the list of domain checkpoints that are children of the given + * checkpoint, and allocate an array to store those objects. + * + * By default, this command covers only direct children; it is also possible + * to expand things to cover all descendants, when @flags includes + * VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS. Also, some filters are provided in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a snapshot, and where all bits within a group describe + * all possible snapshots. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a hypervisor may return + * either 0 or an error. + * + * The first group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_LEAVES and + * VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES, to filter based on checkpoints that + * have no further children (a leaf checkpoint). + * + * The next group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_METADATA and + * VIR_DOMAIN_CHECKPOINT_LIST_NO_METADATA, for filtering checkpoints based on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * Returns the number of domain checkpoints found or -1 and sets @children to + * NULL in case of error. On success, the array stored into @children is + * guaranteed to have an extra allocated element set to NULL but not included + * in the return count, to make iteration easier. The caller is responsible + * for calling virDomainCheckpointFree() on each array element, then calling + * free() on @children. + */ +int +virDomainCheckpointListChildren(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=%p, children=%p, flags=0x%x", + checkpoint, children, flags); + + virResetLastError(); + + if (children) + *children = NULL; + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn = checkpoint->domain->conn; + + if (conn->driver->domainCheckpointListChildren) { + int ret = conn->driver->domainCheckpointListChildren(checkpoint, + children, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointLookupByName: + * @domain: a domain object + * @name: name for the domain checkpoint + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Try to lookup a domain checkpoint based on its name. + * + * Returns a domain checkpoint object or NULL in case of failure. If the + * domain checkpoint cannot be found, then the VIR_ERR_NO_DOMAIN_CHECKPOINT + * error is raised. + */ +virDomainCheckpointPtr +virDomainCheckpointLookupByName(virDomainPtr domain, + const char *name, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "name=%s, flags=0x%x", name, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + virCheckNonNullArgGoto(name, error); + + if (conn->driver->domainCheckpointLookupByName) { + virDomainCheckpointPtr dom; + dom = conn->driver->domainCheckpointLookupByName(domain, name, flags); + if (!dom) + goto error; + return dom; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainHasCurrentCheckpoint: + * @domain: pointer to the domain object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Determine if the domain has a current checkpoint. + * + * Returns 1 if such checkpoint exists, 0 if it doesn't, -1 on error. + */ +int +virDomainHasCurrentCheckpoint(virDomainPtr domain, unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "flags=0x%x", flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn = domain->conn; + + if (conn->driver->domainHasCurrentCheckpoint) { + int ret = conn->driver->domainHasCurrentCheckpoint(domain, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointCurrent: + * @domain: a domain object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Get the current checkpoint for a domain, if any. + * + * virDomainCheckpointFree should be used to free the resources after the + * checkpoint object is no longer needed. + * + * Returns a domain checkpoint object or NULL in case of failure. If the + * current domain checkpoint cannot be found, then the + * VIR_ERR_NO_DOMAIN_CHECKPOINT error is raised. + */ +virDomainCheckpointPtr +virDomainCheckpointCurrent(virDomainPtr domain, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "flags=0x%x", flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + if (conn->driver->domainCheckpointCurrent) { + virDomainCheckpointPtr snap; + snap = conn->driver->domainCheckpointCurrent(domain, flags); + if (!snap) + goto error; + return snap; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainCheckpointGetParent: + * @checkpoint: a checkpoint object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Get the parent checkpoint for @checkpoint, if any. + * + * virDomainCheckpointFree should be used to free the resources after the + * checkpoint object is no longer needed. + * + * Returns a domain checkpoint object or NULL in case of failure. If the + * given checkpoint is a root (no parent), then the VIR_ERR_NO_DOMAIN_CHECKPOINT + * error is raised. + */ +virDomainCheckpointPtr +virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + conn = checkpoint->domain->conn; + + if (conn->driver->domainCheckpointGetParent) { + virDomainCheckpointPtr snap; + snap = conn->driver->domainCheckpointGetParent(checkpoint, flags); + if (!snap) + goto error; + return snap; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainCheckpointIsCurrent: + * @checkpoint: a checkpoint object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Determine if the given checkpoint is the domain's current checkpoint. See + * also virDomainHasCurrentCheckpoint(). + * + * Returns 1 if current, 0 if not current, or -1 on error. + */ +int +virDomainCheckpointIsCurrent(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn = checkpoint->domain->conn; + + if (conn->driver->domainCheckpointIsCurrent) { + int ret; + ret = conn->driver->domainCheckpointIsCurrent(checkpoint, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointHasMetadata: + * @checkpoint: a checkpoint object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Determine if the given checkpoint is associated with libvirt metadata + * that would prevent the deletion of the domain. + * + * Returns 1 if the checkpoint has metadata, 0 if the checkpoint exists without + * help from libvirt, or -1 on error. + */ +int +virDomainCheckpointHasMetadata(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn = checkpoint->domain->conn; + + if (conn->driver->domainCheckpointHasMetadata) { + int ret; + ret = conn->driver->domainCheckpointHasMetadata(checkpoint, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointDelete: + * @checkpoint: the checkpoint to remove + * @flags: not used yet, pass 0 + * @flags: bitwise-OR of supported virDomainCheckpointDeleteFlags + * + * Removes a checkpoint from the domain. + * + * When removing a checkpoint, the record of which portions of the + * disk were dirtied after the checkpoint will be merged into the + * record tracked by the parent checkpoint, if any. Likewise, if the + * checkpoint being deleted was the current checkpoint, the parent + * checkpoint becomes the new current checkpoint. + * + * If @flags includes VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY, then + * any checkpoint metadata tracked by libvirt is removed while keeping + * the checkpoint contents intact; if a hypervisor does not require + * any libvirt metadata to track checkpoints, then this flag is + * silently ignored. + * + * Returns 0 on success, -1 on error. + */ +int +virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn = checkpoint->domain->conn; + + virCheckReadOnlyGoto(conn->flags, error); + + VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN, + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY, + error); + + if (conn->driver->domainCheckpointDelete) { + int ret = conn->driver->domainCheckpointDelete(checkpoint, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointRef: + * @checkpoint: the checkpoint to hold a reference on + * + * Increment the reference count on the checkpoint. For each + * additional call to this method, there shall be a corresponding + * call to virDomainCheckpointFree to release the reference count, once + * the caller no longer needs the reference to this object. + * + * This method is typically useful for applications where multiple + * threads are using a connection, and it is required that the + * connection and domain remain open until all threads have finished + * using the checkpoint. ie, each new thread using a checkpoint would + * increment the reference count. + * + * Returns 0 in case of success and -1 in case of failure. + */ +int +virDomainCheckpointRef(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p, refs=%d", checkpoint, + checkpoint ? checkpoint->parent.u.s.refs : 0); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + + virObjectRef(checkpoint); + return 0; +} + + +/** + * virDomainCheckpointFree: + * @checkpoint: a domain checkpoint object + * + * Free the domain checkpoint object. The checkpoint itself is not modified. + * The data structure is freed and should not be used thereafter. + * + * Returns 0 in case of success and -1 in case of failure. + */ +int +virDomainCheckpointFree(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + + virObjectUnref(checkpoint); + return 0; +} diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms index 3bf3c3f916..a3e12b9a12 100644 --- a/src/libvirt_public.syms +++ b/src/libvirt_public.syms @@ -794,6 +794,22 @@ LIBVIRT_4.4.0 { LIBVIRT_4.5.0 { global: + virDomainCheckpointCreateXML; + virDomainCheckpointCurrent; + virDomainCheckpointDelete; + virDomainCheckpointFree; + virDomainCheckpointGetConnect; + virDomainCheckpointGetDomain; + virDomainCheckpointGetParent; + virDomainCheckpointGetXMLDesc; + virDomainCheckpointHasMetadata; + virDomainCheckpointIsCurrent; + virDomainCheckpointListChildren; + virDomainCheckpointLookupByName; + virDomainCheckpointRef; + virDomainHasCurrentCheckpoint; + virDomainListCheckpoints; + virDomainCheckpointGetName; virGetLastErrorCode; virGetLastErrorDomain; virNodeGetSEVInfo; -- 2.14.4

On 06/25/2018 06:16 PM, John Ferlan wrote: Yeah, it's been a lot of code on my end, and more still to come. Incomplete sentence? But it definitely explains why I want a working demo of the API in use, even if targeting what is currently experimental qemu commands, to show that the API does what we want. Yes, I was very heavily borrowing the code for snapshots, as both items are sub-objects that are related to a domain at a point in time. Since I copied-and-pasted from snapshots, I like to keep the full range of years from my template code; I could use just 2018 by calling it new code, but I don't see it being much of an issue either way (no one will use this header in isolation, so whether it has the project's full copyright years, or just this file's earliest year of existence, doesn't really matter when git history will paint a full picture). Yeah, I tend to do two spaces after full stop (old-school typewriting convention). I can make it a point to use just one when revising this patch, although I don't think it makes too much difference either way. That's the same way snapshots did it, and yes, two separate names makes the most sense for both consistency and usage. That is, you call either: virDomainListCheckpoints(,0) (list all checkpoints, by recursing) virDomainListCheckpoints(,_LIST_ROOTS) (list only roots, by not recursing) virDomainCheckpointListChildren(,0) (list only direct children, by not recursing) virDomainCheckpointListChildren(,_LIST_DESCENDENTS) (list all generations, by recursing) but it was easier to declare one set of flags than two separate enums for the one difference. There's also the fact that the recurse-or-not bit has a different sense between the two APIs, so having two different names for the bit makes it easier to see which sense you are getting. I'm still not convinced whether we need this flag; we could remove it for initial introduction, and add it later if it proves useful; however, it is modeled after what proved useful for snapshots. The idea here is that if qemu bitmaps learn the ability to track their parent bitmap, then libvirt could reconstruct the checkpoint chain purely by reading the qcow2 metadata, instead of having to track XML itself. Such a tracking will be limited (libvirt wants to store extra metadata such as 'description', 'timestamp', and the full 'domain' layout at the time of the checkpoint, while do not have room in qcow2 to be stored there); but if we allow libvirt to import checkpoints by reading what bitmaps already exist in the qcow2 file, then knowing which checkpoints have no metadata (the ones reconstructed from qcow2) vs. DO have metadata (the ones that libvirt has tracked in secondary XML files) will be useful. Again, modeled after snapshots. The 8 combinations result in: children | metadata_only | children_only 0 0 0 - delete one snapshot (both the bitmap in qcow2 and the libvirt XML) 0 0 1 - invalid (children_only requires children) 0 1 0 - delete the libvirt xml, but leave the bitmap in qcow2 0 1 1 - invalid 1 0 0 - delete a full tree of snapshots (this one and all its children), including libvirt XML 1 0 1 - delete a partial tree of snapshots (all the children, but leave this one intact) 1 1 0 - delete full tree of libvirt xml but leave bitmaps in qcow2 1 1 1 - delete partial tree of libvirt xml but leave bitmaps Hmm - I didn't document _CHILDREN or _CHILDREN_ONLY in the .c file. Maybe I should just delete those flags from here for now (again, we can always add flags later). Also I found a lot of these places by grepping for domain snapshots - if a file mentioned one, it should probably mention the other :) Maybe. And sometimes emacs is funny when it reflows paragraphs. It doesn't affect the generated html docs, though. A valid virDomainCheckpointPtr implies an open connection already. I'm not opposed to trimming the METADATA flag from the first revision, then adding it later if it makes sense. Copy-and-paste from snapshots, but sure, I can clean it up. Oh well, copied from snapshots. Snapshots already had an API that returned a count - it was racy (by the time you queried the count, another thread could have changed the count). We've already learned that the List* functions should return a filterable list of objects, and then provide enough filters to be useful so that a user can narrow the list rather than getting too much data. The other issue is that if I have a sequence of checkpoints: Mon .. Tue .. Wed where Mon is the root, but I want to perform an incremental backup of just the data modified since Wed, then having to do virDomainListCheckpoints(mydom) to get Mon, then virDomainCheckpointListChildren(Mon) to get Tue, then virDomainCheckpointListChildren(Tue) to get Wed, is slower than just doing virDomainListCheckpoints(mydom) to get the set 'Mon, Tue, Wed' up front. Yes, and similar to snapshots. Yep, there's probably a few of these still lurking in my series. This one is copied directly from snapshots; if one should grab a reference to the domain and/or connection, then both should (right now, neither do; the object is valid only as long as your domain object and connection also remain valid). -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org

On Wed, Jun 13, 2018 at 11:42:27AM -0500, Eric Blake wrote: First, thanks for the work! (And for doing the detailed write-ups, as is your wont.) A super minor note: I hope you'll also add the API names in the commit message itself (like you did in the past, for the older APIs); it will be handy when browsing `git log` later. So far I see the new APIs are: - virDomainBackupBegin() - virDomainBackupGetXMLDesc() - virDomainBackupEnd() So, OpenStack Nova currently still uses virDomainBlockRebase(); it hasn't even moved to the newer virDomainBlockCopy(). But as we know, currently both of them have the limitation of having to undefine and then re-define the guest XML. As you suggested elsewhere, probably I could explore (once they are 'frozen') moving to these proposed APIs, which will work without having to do the undefine + re-define dance. [...] -- /kashyap

The remote code generator had to be taught about the new virDomainCheckpointPtr type, at which point the remote driver code for backups can be generated. Signed-off-by: Eric Blake <eblake(a)redhat.com&gt; --- src/remote/remote_daemon_dispatch.c | 15 +++ src/remote/remote_driver.c | 31 ++++- src/remote/remote_protocol.x | 237 +++++++++++++++++++++++++++++++++++- src/remote_protocol-structs | 129 ++++++++++++++++++++ src/rpc/gendispatch.pl | 32 ++--- 5 files changed, 426 insertions(+), 18 deletions(-) diff --git a/src/remote/remote_daemon_dispatch.c b/src/remote/remote_daemon_dispatch.c index f1a5ba2590..b8247c34d9 100644 --- a/src/remote/remote_daemon_dispatch.c +++ b/src/remote/remote_daemon_dispatch.c @@ -90,6 +90,7 @@ static virStoragePoolPtr get_nonnull_storage_pool(virConnectPtr conn, remote_non static virStorageVolPtr get_nonnull_storage_vol(virConnectPtr conn, remote_nonnull_storage_vol vol); static virSecretPtr get_nonnull_secret(virConnectPtr conn, remote_nonnull_secret secret); static virNWFilterPtr get_nonnull_nwfilter(virConnectPtr conn, remote_nonnull_nwfilter nwfilter); +static virDomainCheckpointPtr get_nonnull_domain_checkpoint(virDomainPtr dom, remote_nonnull_domain_checkpoint checkpoint); static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr dom, remote_nonnull_domain_snapshot snapshot); static virNodeDevicePtr get_nonnull_node_device(virConnectPtr conn, remote_nonnull_node_device dev); static void make_nonnull_domain(remote_nonnull_domain *dom_dst, virDomainPtr dom_src); @@ -100,6 +101,7 @@ static void make_nonnull_storage_vol(remote_nonnull_storage_vol *vol_dst, virSto static void make_nonnull_node_device(remote_nonnull_node_device *dev_dst, virNodeDevicePtr dev_src); static void make_nonnull_secret(remote_nonnull_secret *secret_dst, virSecretPtr secret_src); static void make_nonnull_nwfilter(remote_nonnull_nwfilter *net_dst, virNWFilterPtr nwfilter_src); +static void make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint *checkpoint_dst, virDomainCheckpointPtr checkpoint_src); static void make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *snapshot_dst, virDomainSnapshotPtr snapshot_src); static int @@ -7087,6 +7089,12 @@ get_nonnull_nwfilter(virConnectPtr conn, remote_nonnull_nwfilter nwfilter) return virGetNWFilter(conn, nwfilter.name, BAD_CAST nwfilter.uuid); } +static virDomainCheckpointPtr +get_nonnull_domain_checkpoint(virDomainPtr dom, remote_nonnull_domain_checkpoint checkpoint) +{ + return virGetDomainCheckpoint(dom, checkpoint.name); +} + static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr dom, remote_nonnull_domain_snapshot snapshot) { @@ -7159,6 +7167,13 @@ make_nonnull_nwfilter(remote_nonnull_nwfilter *nwfilter_dst, virNWFilterPtr nwfi memcpy(nwfilter_dst->uuid, nwfilter_src->uuid, VIR_UUID_BUFLEN); } +static void +make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint *checkpoint_dst, virDomainCheckpointPtr checkpoint_src) +{ + ignore_value(VIR_STRDUP_QUIET(checkpoint_dst->name, checkpoint_src->name)); + make_nonnull_domain(&checkpoint_dst->dom, checkpoint_src->domain); +} + static void make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *snapshot_dst, virDomainSnapshotPtr snapshot_src) { diff --git a/src/remote/remote_driver.c b/src/remote/remote_driver.c index 1328f910b0..9a4ea68410 100644 --- a/src/remote/remote_driver.c +++ b/src/remote/remote_driver.c @@ -146,6 +146,7 @@ static virStoragePoolPtr get_nonnull_storage_pool(virConnectPtr conn, remote_non static virStorageVolPtr get_nonnull_storage_vol(virConnectPtr conn, remote_nonnull_storage_vol vol); static virNodeDevicePtr get_nonnull_node_device(virConnectPtr conn, remote_nonnull_node_device dev); static virSecretPtr get_nonnull_secret(virConnectPtr conn, remote_nonnull_secret secret); +static virDomainCheckpointPtr get_nonnull_domain_checkpoint(virDomainPtr domain, remote_nonnull_domain_checkpoint checkpoint); static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr domain, remote_nonnull_domain_snapshot snapshot); static void make_nonnull_domain(remote_nonnull_domain *dom_dst, virDomainPtr dom_src); static void make_nonnull_network(remote_nonnull_network *net_dst, virNetworkPtr net_src); @@ -156,6 +157,7 @@ static void make_nonnull_node_device(remote_nonnull_node_device *dev_dst, virNodeDevicePtr dev_src); static void make_nonnull_secret(remote_nonnull_secret *secret_dst, virSecretPtr secret_src); static void make_nonnull_nwfilter(remote_nonnull_nwfilter *nwfilter_dst, virNWFilterPtr nwfilter_src); +static void make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint *checkpoint_dst, virDomainCheckpointPtr checkpoint_src); static void make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *snapshot_dst, virDomainSnapshotPtr snapshot_src); /*----------------------------------------------------------------------*/ @@ -8206,6 +8208,12 @@ get_nonnull_nwfilter(virConnectPtr conn, remote_nonnull_nwfilter nwfilter) return virGetNWFilter(conn, nwfilter.name, BAD_CAST nwfilter.uuid); } +static virDomainCheckpointPtr +get_nonnull_domain_checkpoint(virDomainPtr domain, remote_nonnull_domain_checkpoint checkpoint) +{ + return virGetDomainCheckpoint(domain, checkpoint.name); +} + static virDomainSnapshotPtr get_nonnull_domain_snapshot(virDomainPtr domain, remote_nonnull_domain_snapshot snapshot) { @@ -8273,6 +8281,13 @@ make_nonnull_nwfilter(remote_nonnull_nwfilter *nwfilter_dst, virNWFilterPtr nwfi memcpy(nwfilter_dst->uuid, nwfilter_src->uuid, VIR_UUID_BUFLEN); } +static void +make_nonnull_domain_checkpoint(remote_nonnull_domain_checkpoint *checkpoint_dst, virDomainCheckpointPtr checkpoint_src) +{ + checkpoint_dst->name = checkpoint_src->name; + make_nonnull_domain(&checkpoint_dst->dom, checkpoint_src->domain); +} + static void make_nonnull_domain_snapshot(remote_nonnull_domain_snapshot *snapshot_dst, virDomainSnapshotPtr snapshot_src) { @@ -8521,7 +8536,21 @@ static virHypervisorDriver hypervisor_driver = { .connectCompareHypervisorCPU = remoteConnectCompareHypervisorCPU, /* 4.4.0 */ .connectBaselineHypervisorCPU = remoteConnectBaselineHypervisorCPU, /* 4.4.0 */ .nodeGetSEVInfo = remoteNodeGetSEVInfo, /* 4.5.0 */ - .domainGetLaunchSecurityInfo = remoteDomainGetLaunchSecurityInfo /* 4.5.0 */ + .domainGetLaunchSecurityInfo = remoteDomainGetLaunchSecurityInfo, /* 4.5.0 */ + .domainCheckpointCreateXML = remoteDomainCheckpointCreateXML, /* 4.5.0 */ + .domainCheckpointGetXMLDesc = remoteDomainCheckpointGetXMLDesc, /* 4.5.0 */ + .domainListCheckpoints = remoteDomainListCheckpoints, /* 4.5.0 */ + .domainCheckpointListChildren = remoteDomainCheckpointListChildren, /* 4.5.0 */ + .domainCheckpointLookupByName = remoteDomainCheckpointLookupByName, /* 4.5.0 */ + .domainHasCurrentCheckpoint = remoteDomainHasCurrentCheckpoint, /* 4.5.0 */ + .domainCheckpointGetParent = remoteDomainCheckpointGetParent, /* 4.5.0 */ + .domainCheckpointCurrent = remoteDomainCheckpointCurrent, /* 4.5.0 */ + .domainCheckpointIsCurrent = remoteDomainCheckpointIsCurrent, /* 4.5.0 */ + .domainCheckpointHasMetadata = remoteDomainCheckpointHasMetadata, /* 4.5.0 */ + .domainCheckpointDelete = remoteDomainCheckpointDelete, /* 4.5.0 */ + .domainBackupBegin = remoteDomainBackupBegin, /* 4.5.0 */ + .domainBackupGetXMLDesc = remoteDomainBackupGetXMLDesc, /* 4.5.0 */ + .domainBackupEnd = remoteDomainBackupEnd, /* 4.5.0 */ }; static virNetworkDriver network_driver = { diff --git a/src/remote/remote_protocol.x b/src/remote/remote_protocol.x index 162cf5e61b..a306a46435 100644 --- a/src/remote/remote_protocol.x +++ b/src/remote/remote_protocol.x @@ -3,7 +3,7 @@ * remote_internal driver and libvirtd. This protocol is * internal and may change at any time. * - * Copyright (C) 2006-2015 Red Hat, Inc. + * Copyright (C) 2006-2018 Red Hat, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -136,6 +136,9 @@ const REMOTE_AUTH_TYPE_LIST_MAX = 20; /* Upper limit on list of memory stats */ const REMOTE_DOMAIN_MEMORY_STATS_MAX = 1024; +/* Upper limit on lists of domain checkpoints. */ +const REMOTE_DOMAIN_CHECKPOINT_LIST_MAX = 16384; + /* Upper limit on lists of domain snapshots. */ const REMOTE_DOMAIN_SNAPSHOT_LIST_MAX = 16384; @@ -312,6 +315,12 @@ struct remote_nonnull_secret { remote_nonnull_string usageID; }; +/* A checkpoint which may not be NULL. */ +struct remote_nonnull_domain_checkpoint { + remote_nonnull_string name; + remote_nonnull_domain dom; +}; + /* A snapshot which may not be NULL. */ struct remote_nonnull_domain_snapshot { remote_nonnull_string name; @@ -3505,6 +3514,138 @@ struct remote_domain_get_launch_security_info_ret { remote_typed_param params<REMOTE_DOMAIN_LAUNCH_SECURITY_INFO_PARAMS_MAX>; }; +struct remote_domain_checkpoint_create_xml_args { + remote_nonnull_domain dom; + remote_nonnull_string xml_desc; + unsigned int flags; +}; + +struct remote_domain_checkpoint_create_xml_ret { + remote_nonnull_domain_checkpoint checkpoint; +}; + +struct remote_domain_checkpoint_get_xml_desc_args { + remote_nonnull_domain_checkpoint checkpoint; + unsigned int flags; +}; + +struct remote_domain_checkpoint_get_xml_desc_ret { + remote_nonnull_string xml; +}; + +struct remote_domain_list_checkpoints_args { + remote_nonnull_domain dom; + int need_results; + unsigned int flags; +}; + +struct remote_domain_list_checkpoints_ret { /* insert@1 */ + remote_nonnull_domain_checkpoint checkpoints<REMOTE_DOMAIN_CHECKPOINT_LIST_MAX>; + int ret; +}; + +struct remote_domain_checkpoint_list_children_args { + remote_nonnull_domain_checkpoint checkpoint; + int need_results; + unsigned int flags; +}; + +struct remote_domain_checkpoint_list_children_ret { /* insert@1 */ + remote_nonnull_domain_checkpoint checkpoints<REMOTE_DOMAIN_CHECKPOINT_LIST_MAX>; + int ret; +}; + +struct remote_domain_checkpoint_lookup_by_name_args { + remote_nonnull_domain dom; + remote_nonnull_string name; + unsigned int flags; +}; + +struct remote_domain_checkpoint_lookup_by_name_ret { + remote_nonnull_domain_checkpoint checkpoint; +}; + +struct remote_domain_has_current_checkpoint_args { + remote_nonnull_domain dom; + unsigned int flags; +}; + +struct remote_domain_has_current_checkpoint_ret { + int result; +}; + +struct remote_domain_checkpoint_get_parent_args { + remote_nonnull_domain_checkpoint checkpoint; + unsigned int flags; +}; + +struct remote_domain_checkpoint_get_parent_ret { + remote_nonnull_domain_checkpoint parent; +}; + +struct remote_domain_checkpoint_current_args { + remote_nonnull_domain dom; + unsigned int flags; +}; + +struct remote_domain_checkpoint_current_ret { + remote_nonnull_domain_checkpoint checkpoint; +}; + +struct remote_domain_checkpoint_is_current_args { + remote_nonnull_domain_checkpoint checkpoint; + unsigned int flags; +}; + +struct remote_domain_checkpoint_is_current_ret { + int current; +}; + +struct remote_domain_checkpoint_has_metadata_args { + remote_nonnull_domain_checkpoint checkpoint; + unsigned int flags; +}; + +struct remote_domain_checkpoint_has_metadata_ret { + int metadata; +}; + +struct remote_domain_checkpoint_delete_args { + remote_nonnull_domain_checkpoint checkpoint; + unsigned int flags; +}; + +struct remote_domain_backup_begin_args { + remote_nonnull_domain dom; + remote_string disk_xml; + remote_string checkpoint_xml; + unsigned int flags; +}; + +struct remote_domain_backup_begin_ret { + int result; +}; + +struct remote_domain_backup_get_xml_desc_args { + remote_nonnull_domain dom; + int id; + unsigned int flags; +}; + +struct remote_domain_backup_get_xml_desc_ret { + remote_nonnull_string xml; +}; + +struct remote_domain_backup_end_args { + remote_nonnull_domain dom; + int id; + unsigned int flags; +}; + +struct remote_domain_backup_end_ret { + int retcode; +}; + /*----- Protocol. -----*/ /* Define the program number, protocol version and procedure numbers here. */ @@ -6224,5 +6365,97 @@ enum remote_procedure { * @generate: none * @acl: domain:read */ - REMOTE_PROC_DOMAIN_GET_LAUNCH_SECURITY_INFO = 396 + REMOTE_PROC_DOMAIN_GET_LAUNCH_SECURITY_INFO = 396, + + /** + * @generate: both + * @acl: domain:checkpoint + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_CREATE_XML = 397, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + * @acl: domain:read_secure:VIR_DOMAIN_XML_SECURE + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_GET_XML_DESC = 398, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_LIST_CHECKPOINTS = 399, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_LIST_CHILDREN = 400, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_LOOKUP_BY_NAME = 401, + + /** + * @generate: both + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_HAS_CURRENT_CHECKPOINT = 402, + + /** + * @generate: both + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_CURRENT = 403, + + /** + * @generate: both + * @priority: high + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_GET_PARENT = 404, + + /** + * @generate: both + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT = 405, + + /** + * @generate: both + * @acl: domain:read + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_HAS_METADATA = 406, + + /** + * @generate: both + * @acl: domain:checkpoint + */ + REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 407, + + /** + * @generate: both + * @acl: domain:checkpoint + * @acl: domain:block_read + */ + REMOTE_PROC_DOMAIN_BACKUP_BEGIN = 408, + + /** + * @generate: both + * @acl: domain:read + * @acl: domain:read_secure:VIR_DOMAIN_XML_SECURE + */ + REMOTE_PROC_DOMAIN_BACKUP_GET_XML_DESC = 409, + + /** + * @generate: both + * @acl: domain:checkpoint + */ + REMOTE_PROC_DOMAIN_BACKUP_END = 410 }; diff --git a/src/remote_protocol-structs b/src/remote_protocol-structs index 0c75ad2305..9c7b116151 100644 --- a/src/remote_protocol-structs +++ b/src/remote_protocol-structs @@ -42,6 +42,10 @@ struct remote_nonnull_secret { int usageType; remote_nonnull_string usageID; }; +struct remote_nonnull_domain_checkpoint { + remote_nonnull_string name; + remote_nonnull_domain dom; +}; struct remote_nonnull_domain_snapshot { remote_nonnull_string name; remote_nonnull_domain dom; @@ -2928,6 +2932,117 @@ struct remote_domain_get_launch_security_info_ret { remote_typed_param * params_val; } params; }; +struct remote_domain_checkpoint_create_xml_args { + remote_nonnull_domain dom; + remote_nonnull_string xml_desc; + u_int flags; +}; +struct remote_domain_checkpoint_create_xml_ret { + remote_nonnull_domain_checkpoint checkpoint; +}; +struct remote_domain_checkpoint_get_xml_desc_args { + remote_nonnull_domain_checkpoint checkpoint; + u_int flags; +}; +struct remote_domain_checkpoint_get_xml_desc_ret { + remote_nonnull_string xml; +}; +struct remote_domain_list_checkpoints_args { + remote_nonnull_domain dom; + int need_results; + u_int flags; +}; +struct remote_domain_list_checkpoints_ret { + struct { + u_int checkpoints_len; + remote_nonnull_domain_checkpoint * checkpoints_val; + } checkpoints; + int ret; +}; +struct remote_domain_checkpoint_list_children_args { + remote_nonnull_domain_checkpoint checkpoint; + int need_results; + u_int flags; +}; +struct remote_domain_checkpoint_list_children_ret { + struct { + u_int checkpoints_len; + remote_nonnull_domain_checkpoint * checkpoints_val; + } checkpoints; + int ret; +}; +struct remote_domain_checkpoint_lookup_by_name_args { + remote_nonnull_domain dom; + remote_nonnull_string name; + u_int flags; +}; +struct remote_domain_checkpoint_lookup_by_name_ret { + remote_nonnull_domain_checkpoint checkpoint; +}; +struct remote_domain_has_current_checkpoint_args { + remote_nonnull_domain dom; + u_int flags; +}; +struct remote_domain_has_current_checkpoint_ret { + int result; +}; +struct remote_domain_checkpoint_get_parent_args { + remote_nonnull_domain_checkpoint checkpoint; + u_int flags; +}; +struct remote_domain_checkpoint_get_parent_ret { + remote_nonnull_domain_checkpoint parent; +}; +struct remote_domain_checkpoint_current_args { + remote_nonnull_domain dom; + u_int flags; +}; +struct remote_domain_checkpoint_current_ret { + remote_nonnull_domain_checkpoint checkpoint; +}; +struct remote_domain_checkpoint_is_current_args { + remote_nonnull_domain_checkpoint checkpoint; + u_int flags; +}; +struct remote_domain_checkpoint_is_current_ret { + int current; +}; +struct remote_domain_checkpoint_has_metadata_args { + remote_nonnull_domain_checkpoint checkpoint; + u_int flags; +}; +struct remote_domain_checkpoint_has_metadata_ret { + int metadata; +}; +struct remote_domain_checkpoint_delete_args { + remote_nonnull_domain_checkpoint checkpoint; + u_int flags; +}; +struct remote_domain_backup_begin_args { + remote_nonnull_domain dom; + remote_string disk_xml; + remote_string checkpoint_xml; + u_int flags; +}; +struct remote_domain_backup_begin_ret { + int result; +}; +struct remote_domain_backup_get_xml_desc_args { + remote_nonnull_domain dom; + int id; + u_int flags; +}; +struct remote_domain_backup_get_xml_desc_ret { + remote_nonnull_string xml; +}; +struct remote_domain_backup_end_args { + remote_nonnull_domain dom; + int id; + u_int flags; +}; +struct remote_domain_backup_end_ret { + int retcode; +}; enum remote_procedure { REMOTE_PROC_CONNECT_OPEN = 1, REMOTE_PROC_CONNECT_CLOSE = 2, @@ -3325,4 +3440,18 @@ enum remote_procedure { REMOTE_PROC_CONNECT_BASELINE_HYPERVISOR_CPU = 394, REMOTE_PROC_NODE_GET_SEV_INFO = 395, REMOTE_PROC_DOMAIN_GET_LAUNCH_SECURITY_INFO = 396, + REMOTE_PROC_DOMAIN_CHECKPOINT_CREATE_XML = 397, + REMOTE_PROC_DOMAIN_CHECKPOINT_GET_XML_DESC = 398, + REMOTE_PROC_DOMAIN_LIST_CHECKPOINTS = 399, + REMOTE_PROC_DOMAIN_CHECKPOINT_LIST_CHILDREN = 400, + REMOTE_PROC_DOMAIN_CHECKPOINT_LOOKUP_BY_NAME = 401, + REMOTE_PROC_DOMAIN_HAS_CURRENT_CHECKPOINT = 402, + REMOTE_PROC_DOMAIN_CHECKPOINT_CURRENT = 403, + REMOTE_PROC_DOMAIN_CHECKPOINT_GET_PARENT = 404, + REMOTE_PROC_DOMAIN_CHECKPOINT_IS_CURRENT = 405, + REMOTE_PROC_DOMAIN_CHECKPOINT_HAS_METADATA = 406, + REMOTE_PROC_DOMAIN_CHECKPOINT_DELETE = 407, + REMOTE_PROC_DOMAIN_BACKUP_BEGIN = 408, + REMOTE_PROC_DOMAIN_BACKUP_GET_XML_DESC = 409, + REMOTE_PROC_DOMAIN_BACKUP_END = 410, }; diff --git a/src/rpc/gendispatch.pl b/src/rpc/gendispatch.pl index b8b83b6b40..b40efd91d0 100755 --- a/src/rpc/gendispatch.pl +++ b/src/rpc/gendispatch.pl @@ -1,6 +1,6 @@ #!/usr/bin/env perl # -# Copyright (C) 2010-2015 Red Hat, Inc. +# Copyright (C) 2010-2018 Red Hat, Inc. # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Lesser General Public @@ -567,18 +567,20 @@ elsif ($mode eq "server") { push(@args_list, "$2"); push(@free_list, " virObjectUnref($2);"); - } elsif ($args_member =~ m/^remote_nonnull_domain_snapshot (\S+);$/) { + } elsif ($args_member =~ m/^remote_nonnull_domain_(checkpoint|snapshot) (\S+);$/) { + my $type_name = name_to_TypeName($1); + push(@vars_list, "virDomainPtr dom = NULL"); - push(@vars_list, "virDomainSnapshotPtr snapshot = NULL"); + push(@vars_list, "virDomain${type_name}Ptr ${1} = NULL"); push(@getters_list, - " if (!(dom = get_nonnull_domain($conn, args->${1}.dom)))\n" . + " if (!(dom = get_nonnull_domain($conn, args->${2}.dom)))\n" . " goto cleanup;\n" . "\n" . - " if (!(snapshot = get_nonnull_domain_snapshot(dom, args->${1})))\n" . + " if (!($1 = get_nonnull_domain_${1}(dom, args->$2)))\n" . " goto cleanup;\n"); - push(@args_list, "snapshot"); + push(@args_list, "$1"); push(@free_list, - " virObjectUnref(snapshot);\n" . + " virObjectUnref($1);\n" . " virObjectUnref(dom);"); } elsif ($args_member =~ m/^(?:(?:admin|remote)_string|remote_uuid) (\S+)<\S+>;/) { push(@args_list, $conn) if !@args_list; @@ -722,7 +724,7 @@ elsif ($mode eq "server") { if (!$modern_ret_as_list) { push(@ret_list, "ret->$3 = tmp.$3;"); } - } elsif ($ret_member =~ m/(?:admin|remote)_nonnull_(secret|nwfilter|node_device|interface|network|storage_vol|storage_pool|domain_snapshot|domain|server|client) (\S+)<(\S+)>;/) { + } elsif ($ret_member =~ m/(?:admin|remote)_nonnull_(secret|nwfilter|node_device|interface|network|storage_vol|storage_pool|domain_checkpoint|domain_snapshot|domain|server|client) (\S+)<(\S+)>;/) { $modern_ret_struct_name = $1; $single_ret_list_error_msg_type = $1; $single_ret_list_name = $2; @@ -780,7 +782,7 @@ elsif ($mode eq "server") { $single_ret_var = $1; $single_ret_by_ref = 0; $single_ret_check = " == NULL"; - } elsif ($ret_member =~ m/^remote_nonnull_(domain|network|storage_pool|storage_vol|interface|node_device|secret|nwfilter|domain_snapshot) (\S+);/) { + } elsif ($ret_member =~ m/^remote_nonnull_(domain|network|storage_pool|storage_vol|interface|node_device|secret|nwfilter|domain_checkpoint|domain_snapshot) (\S+);/) { my $type_name = name_to_TypeName($1); if ($call->{ProcName} eq "DomainCreateWithFlags") { @@ -1325,13 +1327,13 @@ elsif ($mode eq "client") { $priv_src = "dev->conn"; push(@args_list, "virNodeDevicePtr dev"); push(@setters_list, "args.name = dev->name;"); - } elsif ($args_member =~ m/^remote_nonnull_(domain|network|storage_pool|storage_vol|interface|secret|nwfilter|domain_snapshot) (\S+);/) { + } elsif ($args_member =~ m/^remote_nonnull_(domain|network|storage_pool|storage_vol|interface|secret|nwfilter|domain_checkpoint|domain_snapshot) (\S+);/) { my $name = $1; my $arg_name = $2; my $type_name = name_to_TypeName($name); if ($is_first_arg) { - if ($name eq "domain_snapshot") { + if ($name =~ m/^domain_.*/) { $priv_src = "$arg_name->domain->conn"; } else { $priv_src = "$arg_name->conn"; @@ -1518,7 +1520,7 @@ elsif ($mode eq "client") { } push(@ret_list, "memcpy(result->$3, ret.$3, sizeof(result->$3));"); - } elsif ($ret_member =~ m/(?:admin|remote)_nonnull_(secret|nwfilter|node_device|interface|network|storage_vol|storage_pool|domain_snapshot|domain|server|client) (\S+)<(\S+)>;/) { + } elsif ($ret_member =~ m/(?:admin|remote)_nonnull_(secret|nwfilter|node_device|interface|network|storage_vol|storage_pool|domain_checkpoint|domain_snapshot|domain|server|client) (\S+)<(\S+)>;/) { my $proc_name = name_to_TypeName($1); if ($structprefix eq "admin") { @@ -1571,7 +1573,7 @@ elsif ($mode eq "client") { push(@ret_list, "VIR_FREE(ret.$1);"); $single_ret_var = "char *rv = NULL"; $single_ret_type = "char *"; - } elsif ($ret_member =~ m/^remote_nonnull_(domain|network|storage_pool|storage_vol|node_device|interface|secret|nwfilter|domain_snapshot) (\S+);/) { + } elsif ($ret_member =~ m/^remote_nonnull_(domain|network|storage_pool|storage_vol|node_device|interface|secret|nwfilter|domain_checkpoint|domain_snapshot) (\S+);/) { my $name = $1; my $arg_name = $2; my $type_name = name_to_TypeName($name); @@ -1585,7 +1587,7 @@ elsif ($mode eq "client") { $single_ret_var = "int rv = -1"; $single_ret_type = "int"; } else { - if ($name eq "domain_snapshot") { + if ($name =~ m/^domain_.*/) { my $dom = "$priv_src"; $dom =~ s/->conn//; push(@ret_list, "rv = get_nonnull_$name($dom, ret.$arg_name);"); @@ -1928,7 +1930,7 @@ elsif ($mode eq "client") { print " }\n"; print "\n"; } elsif ($modern_ret_as_list) { - if ($modern_ret_struct_name =~ m/domain_snapshot|client/) { + if ($modern_ret_struct_name =~ m/domain_checkpoint|domain_snapshot|client/) { $priv_src =~ s/->conn//; } print " if (result) {\n"; -- 2.14.4