Re: [PATCH v6 7/9] backup: Introduce virDomainCheckpoint APIs

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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



[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux