On Tue, Mar 26, 2019 at 01:13:51AM -0500, Eric Blake wrote: > Introduce a bunch of new public APIs related to backup checkpoints. > Checkpoints are modeled heavily after virDomainSnapshotPtr (both > represent a point in time of the guest), although a snapshot exists > with the intent of rolling back to that state, while a checkpoint > exists to make it possible to create an incremental backup at a later > time. > > The following map shows the API relations to snapshots, with new APIs > on the right: > > Operate on a domain object to create/redefine a child: > virDomainSnapshotCreateXML virDomainCheckpointCreateXML > > Operate on a child object for lifetime management: > virDomainSnapshotDelete virDomainCheckpointDelete > virDomainSnapshotFree virDomainCheckpointFree > virDomainSnapshotRef virDomainCheckpointRef > > Operate on a child object to learn more about it: > virDomainSnapshotGetXMLDesc virDomainCheckpointGetXMLDesc > virDomainSnapshotGetConnect virDomainCheckpointGetConnect > virDomainSnapshotGetDomain virDomainCheckpointGetDomain > virDomainSnapshotGetName virDomainCheckpiontGetName > virDomainSnapshotGetParent virDomainCheckpiontGetParent > virDomainSnapshotHasMetadata virDomainCheckpointHasMetadata > virDomainSnapshotIsCurrent virDomainCheckpointIsCurrent > > Operate on a domain object to list all children: > virDomainSnapshotNum (no counterpart, this is the old > virDomainSnapshotListNames racy interface) > virDomainSnapshotListAllSnapshots virDomainListCheckpoints The snapshot API was actually virDomainListAllSnapshots. For naming consistency I'd prefer to see "All" in the name of the name API too eg virDomainListAllCheckpoints > > Operate on a child object to list descendents: > virDomainSnapshotNumChildren (no counterpart, this is the old > virDomainSnapshotListChildrenNames racy interface) > virDomainSnapshotListAllChildren virDomainCheckpointListChildren and virDomainCheckpointListAllChildren here too > Operate on a domain to locate a particular child: > virDomainSnapshotLookupByName virDomainCheckpointLookupByName > virDomainHasCurrentSnapshot virDomainHasCurrentSnapshot Presumably the second should be virDomainhasCurrentCheckpoint > virDomainSnapshotCurrent virDomainCheckpointCurrent > > Operate on a snapshot to roll back to earlier state: > virDomainSnapshotRevert (no counterpart, instead checkpoints > are used in incremental backups via > XML to virDomainBackupBegin) > > Signed-off-by: Eric Blake <eblake@xxxxxxxxxx> > --- > include/libvirt/libvirt-domain-checkpoint.h | 161 +++++ > include/libvirt/libvirt-domain.h | 6 + > include/libvirt/libvirt.h | 5 +- > src/conf/virdomainmomentobjlist.h | 5 +- > src/driver-hypervisor.h | 60 +- > docs/Makefile.am | 3 + > docs/apibuild.py | 2 + > docs/docs.html.in | 1 + > libvirt.spec.in | 1 + > mingw-libvirt.spec.in | 2 + > po/POTFILES | 1 + > src/Makefile.am | 2 + > src/libvirt-domain-checkpoint.c | 749 ++++++++++++++++++++ > src/libvirt-domain.c | 4 +- > src/libvirt_public.syms | 16 + > 15 files changed, 1010 insertions(+), 8 deletions(-) > create mode 100644 include/libvirt/libvirt-domain-checkpoint.h > create mode 100644 src/libvirt-domain-checkpoint.c > > diff --git a/include/libvirt/libvirt-domain-checkpoint.h b/include/libvirt/libvirt-domain-checkpoint.h > new file mode 100644 > index 0000000000..332df93755 > --- /dev/null > +++ b/include/libvirt/libvirt-domain-checkpoint.h > @@ -0,0 +1,161 @@ > +/* > + * libvirt-domain-checkpoint.h > + * Summary: APIs for management of domain checkpoints > + * Description: Provides APIs for the management of domain checkpoints > + * > + * Copyright (C) 2006-2019 Red Hat, Inc. > + * > + * This library is free software; you can redistribute it and/or > + * modify it under the terms of the GNU Lesser General Public > + * License as published by the Free Software Foundation; either > + * version 2.1 of the License, or (at your option) any later version. > + * > + * This library is distributed in the hope that it will be useful, > + * but WITHOUT ANY WARRANTY; without even the implied warranty of > + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU > + * Lesser General Public License for more details. > + * > + * You should have received a copy of the GNU Lesser General Public > + * License along with this library. If not, see > + * <http://www.gnu.org/licenses/>. > + */ > + > +#ifndef LIBVIRT_DOMAIN_CHECKPOINT_H > +# define LIBVIRT_DOMAIN_CHECKPOINT_H > + > +# ifndef __VIR_LIBVIRT_H_INCLUDES__ > +# error "Don't include this file directly, only use libvirt/libvirt.h" > +# endif > + > +/** > + * virDomainCheckpoint: > + * > + * A virDomainCheckpoint is a private structure representing a checkpoint of > + * a domain. A checkpoint is useful for tracking which portions of the > + * domain disks have been altered since a point in time, but by itself does > + * not allow reverting back to that point in time. > + */ > +typedef struct _virDomainCheckpoint virDomainCheckpoint; > + > +/** > + * virDomainCheckpointPtr: > + * > + * A virDomainCheckpointPtr is pointer to a virDomainCheckpoint > + * private structure, and is the type used to reference a domain > + * checkpoint in the API. > + */ > +typedef virDomainCheckpoint *virDomainCheckpointPtr; > + > +const char *virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint); > +virDomainPtr virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint); > +virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint); > + > +typedef enum { > + VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE = (1 << 0), /* Restore or alter > + metadata */ > + VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT = (1 << 1), /* With redefine, make > + checkpoint current */ > + VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA = (1 << 2), /* Make checkpoint without > + remembering it */ > + VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE = (1 << 3), /* use guest agent to > + quiesce all mounted > + file systems within > + the domain */ > +} virDomainCheckpointCreateFlags; > + > +/* Create a checkpoint using the current VM state. */ > +virDomainCheckpointPtr virDomainCheckpointCreateXML(virDomainPtr domain, > + const char *xmlDesc, > + unsigned int flags); > + > +typedef enum { > + VIR_DOMAIN_CHECKPOINT_XML_SECURE = (1 << 0), /* Include sensitive data */ > + VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN = (1 << 1), /* Suppress <domain> > + subelement */ > + VIR_DOMAIN_CHECKPOINT_XML_SIZE = (1 << 2), /* Include dynamic > + per-<disk> size */ > +} virDomainCheckpointXMLFlags; > + > +/* Dump the XML of a checkpoint */ > +char *virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, > + unsigned int flags); > + > +/** > + * virDomainCheckpointListFlags: > + * > + * Flags valid for 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_TOPOLOGICAL = (1 << 1), /* Ensure parents occur > + before children in > + the resulting list */ > + > + VIR_DOMAIN_CHECKPOINT_LIST_LEAVES = (1 << 2), /* Filter by checkpoints > + with no children */ > + VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES = (1 << 3), /* Filter by checkpoints > + that have children */ > + > + VIR_DOMAIN_CHECKPOINT_LIST_METADATA = (1 << 4), /* Filter by checkpoints > + which have metadata */ > + VIR_DOMAIN_CHECKPOINT_LIST_NO_METADATA = (1 << 5), /* 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 /* LIBVIRT_DOMAIN_CHECKPOINT_H */ > diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h > index 1d5bdb545d..94504e70a6 100644 > --- a/include/libvirt/libvirt-domain.h > +++ b/include/libvirt/libvirt-domain.h > @@ -1774,6 +1774,9 @@ typedef enum { > VIR_DOMAIN_UNDEFINE_NVRAM = (1 << 2), /* Also remove any > nvram file */ > VIR_DOMAIN_UNDEFINE_KEEP_NVRAM = (1 << 3), /* Keep nvram file */ > + VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA= (1 << 4),/* If last use of domain, > + then also remove any > + checkpoint metadata */ Whitespace missing before the "=" and between ",/" > > /* Future undefine control flags should come here. */ > } virDomainUndefineFlagsValues; > @@ -1812,6 +1815,9 @@ typedef enum { > > VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT = 1 << 12, > VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT = 1 << 13, > + > + VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT = 1 << 14, > + VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT = 1 << 15, > } virConnectListAllDomainsFlags; > > int virConnectListAllDomains (virConnectPtr conn, Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :| -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
