Module libvirt-domain-checkpoint from libvirt

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/.

Table of Contents

Types

typedef struct _virDomainCheckpoint virDomainCheckpoint
typedef enum virDomainCheckpointCreateFlags
typedef enum virDomainCheckpointDeleteFlags
typedef enum virDomainCheckpointListFlags
typedef virDomainCheckpoint * virDomainCheckpointPtr
typedef enum virDomainCheckpointXMLFlags

Functions

virDomainCheckpointPtr	virDomainCheckpointCreateXML	(virDomainPtr domain, 
const char * xmlDesc,
unsigned int flags) int virDomainCheckpointDelete (virDomainCheckpointPtr checkpoint,
unsigned int flags) int virDomainCheckpointFree (virDomainCheckpointPtr checkpoint) virConnectPtr virDomainCheckpointGetConnect (virDomainCheckpointPtr checkpoint) virDomainPtr virDomainCheckpointGetDomain (virDomainCheckpointPtr checkpoint) const char * virDomainCheckpointGetName (virDomainCheckpointPtr checkpoint) virDomainCheckpointPtr virDomainCheckpointGetParent (virDomainCheckpointPtr checkpoint,
unsigned int flags) char * virDomainCheckpointGetXMLDesc (virDomainCheckpointPtr checkpoint,
unsigned int flags) int virDomainCheckpointListAllChildren (virDomainCheckpointPtr checkpoint,
virDomainCheckpointPtr ** children,
unsigned int flags) virDomainCheckpointPtr virDomainCheckpointLookupByName (virDomainPtr domain,
const char * name,
unsigned int flags) int virDomainCheckpointRef (virDomainCheckpointPtr checkpoint) int virDomainListAllCheckpoints (virDomainPtr domain,
virDomainCheckpointPtr ** checkpoints,
unsigned int flags)

Description

Types

virDomainCheckpoint

struct virDomainCheckpoint {
The content of this structure is not made public by the API
}

virDomainCheckpointCreateFlags

enum virDomainCheckpointCreateFlags {
VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE = 1 (0x1; 1 << 0)
Restore or alter metadata
VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE = 2 (0x2; 1 << 1)
use guest agent to quiesce all mounted file systems within the domain
}

virDomainCheckpointDeleteFlags

enum virDomainCheckpointDeleteFlags {
VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = 1 (0x1; 1 << 0)
Also delete children
VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY = 2 (0x2; 1 << 1)
Delete just metadata
VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY = 4 (0x4; 1 << 2)
Delete just children
}

virDomainCheckpointListFlags

enum virDomainCheckpointListFlags {
VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS = 1 (0x1; 1 << 0)
List all descendants, not just children, when listing a checkpoint
VIR_DOMAIN_CHECKPOINT_LIST_ROOTS = 1 (0x1; 1 << 0)
Filter by checkpoints with no parents, when listing a domain
VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL = 2 (0x2; 1 << 1)
Ensure parents occur before children in the resulting list
VIR_DOMAIN_CHECKPOINT_LIST_LEAVES = 4 (0x4; 1 << 2)
Filter by checkpoints with no children
VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES = 8 (0x8; 1 << 3)
Filter by checkpoints that have children
}

virDomainCheckpointXMLFlags

enum virDomainCheckpointXMLFlags {
VIR_DOMAIN_CHECKPOINT_XML_SECURE = 1 (0x1; 1 << 0)
Include sensitive data
VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN = 2 (0x2; 1 << 1)
Suppress <domain> subelement
VIR_DOMAIN_CHECKPOINT_XML_SIZE = 4 (0x4; 1 << 2)
Include dynamic per-<disk> size
}

Functions

virDomainCheckpointCreateXML

virDomainCheckpointPtr	virDomainCheckpointCreateXML	(virDomainPtr domain,
							 const char * xmlDesc,
							 unsigned int flags)

Create a new checkpoint using @xmlDesc, with a top-level <domaincheckpoint> element, on a running @domain. Note that @xmlDesc must validate against the <domaincheckpoint> XML schema. Typically, it is more common to create a new checkpoint as part of kicking off a backup job with virDomainBackupBegin(); however, it is also possible to start a checkpoint without a backup.

See <a href="formatcheckpoint.html#CheckpointAttributes">Checkpoint XML</a> for more details on @xmlDesc. In particular, some hypervisors may require particular disk formats, such as qcow2, in order to support this command; where @xmlDesc can be used to limit the checkpoint to a working subset of the domain's disks.

If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, then this is a request to reinstate checkpoint metadata that was previously captured from virDomainCheckpointGetXMLDesc() before removing that metadata, rather than creating a new checkpoint. Note that while original creation can omit a number of elements from @xmlDesc (and libvirt will supply sane defaults based on the domain state at that point in time), a redefinition must supply more elements (as the domain may have changed in the meantime, so that libvirt no longer has a way to resupply correct defaults). Not all hypervisors support this flag.

If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE, then the libvirt will attempt to use guest agent to freeze and thaw all file systems in use within domain OS. However, if the guest agent is not present, an error is thrown. This flag is incompatible with VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE.

domain
a domain object
xmlDesc
description of the checkpoint to create
flags
bitwise-OR of supported virDomainCheckpointCreateFlags
Returns
an (opaque) new virDomainCheckpointPtr on success or NULL on failure.

virDomainCheckpointDelete

int	virDomainCheckpointDelete	(virDomainCheckpointPtr checkpoint,
					 unsigned int flags)

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.

If @flags includes VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN, then any descendant checkpoints are also deleted. If @flags includes VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY, then any descendant checkepoints are deleted, but this checkpoint remains. These two flags are mutually exclusive.

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.

checkpoint
the checkpoint to remove
flags
bitwise-OR of supported virDomainCheckpointDeleteFlags
Returns
0 on success, -1 on error.

virDomainCheckpointFree

int	virDomainCheckpointFree		(virDomainCheckpointPtr checkpoint)

Free the domain checkpoint object. The checkpoint itself is not modified. The data structure is freed and should not be used thereafter.

checkpoint
a domain checkpoint object
Returns
0 in case of success and -1 in case of failure.

virDomainCheckpointGetConnect

virConnectPtr	virDomainCheckpointGetConnect	(virDomainCheckpointPtr checkpoint)

Provides the connection pointer associated with a checkpoint. The reference counter on the connection is not increased by this call.

checkpoint
a checkpoint object
Returns
the connection or NULL.

virDomainCheckpointGetDomain

virDomainPtr	virDomainCheckpointGetDomain	(virDomainCheckpointPtr checkpoint)

Provides the domain pointer associated with a checkpoint. The reference counter on the domain is not increased by this call.

checkpoint
a checkpoint object
Returns
the domain or NULL.

virDomainCheckpointGetName

const char *	virDomainCheckpointGetName	(virDomainCheckpointPtr checkpoint)

Get the public name for that checkpoint

checkpoint
a checkpoint object
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.

virDomainCheckpointGetParent

virDomainCheckpointPtr	virDomainCheckpointGetParent	(virDomainCheckpointPtr checkpoint,
							 unsigned int flags)

Get the parent checkpoint for @checkpoint, if any.

virDomainCheckpointFree should be used to free the resources after the checkpoint object is no longer needed.

checkpoint
a checkpoint object
flags
extra flags; not used yet, so callers should always pass 0
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.

virDomainCheckpointGetXMLDesc

char *	virDomainCheckpointGetXMLDesc	(virDomainCheckpointPtr checkpoint,
					 unsigned int flags)

Provide an XML description of the domain checkpoint.

No security-sensitive data will be included unless @flags contains VIR_DOMAIN_CHECKPOINT_XML_SECURE; this flag is rejected on read-only connections.

Normally, the XML description includes an element giving a full description of the domain at the time the checkpoint was created; to reduce parsing time, it will be suppressed when @flags contains VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN.

By default, the XML description contains only static information that does not change over time. However, when @flags contains VIR_DOMAIN_CHECKPOINT_XML_SIZE, each <disk> listing adds an additional attribute that shows an estimate of the current size in bytes that have been dirtied between the time the checkpoint was created and the current point in time.

checkpoint
a domain checkpoint object
flags
bitwise-OR of supported virDomainCheckpointXMLFlags
Returns
a 0 terminated UTF-8 encoded XML instance or NULL in case of error. The caller must free() the returned value.

virDomainCheckpointListAllChildren

int	virDomainCheckpointListAllChildren	(virDomainCheckpointPtr checkpoint,
						 virDomainCheckpointPtr ** children,
						 unsigned int flags)

Collect the list of domain checkpoints that are children of the given checkpoint, and allocate an array to store those objects.

If @flags contains VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL, @checkpoints is non-NULL, and no other connection is modifying checkpoints, then it is guaranteed that for any checkpoint in the resulting list, no checkpoints later in the list can be reached by a sequence of virDomainCheckpointGetParent() starting from that earlier checkpoint; otherwise, the order of checkpoints in the resulting list is unspecified.

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. Additional are provided via the remaining @flags values as documented in virDomainListAllCheckpoints(), with the exception that VIR_DOMAIN_CHECKPOINT_LIST_ROOTS is not supported (in fact, VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS has the same bit value but opposite semantics of widening rather than narrowing the listing).

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
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.

virDomainCheckpointLookupByName

virDomainCheckpointPtr	virDomainCheckpointLookupByName	(virDomainPtr domain,
							 const char * name,
							 unsigned int flags)

Try to lookup a domain checkpoint based on its name.

domain
a domain object
name
name for the domain checkpoint
flags
extra flags; not used yet, so callers should always pass 0
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.

virDomainCheckpointRef

int	virDomainCheckpointRef		(virDomainCheckpointPtr checkpoint)

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.

checkpoint
the checkpoint to hold a reference on
Returns
0 in case of success and -1 in case of failure.

virDomainListAllCheckpoints

int	virDomainListAllCheckpoints	(virDomainPtr domain,
					 virDomainCheckpointPtr ** checkpoints,
					 unsigned int flags)

Collect the list of domain checkpoints for the given domain and allocate an array to store those objects.

If @flags contains VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL, @checkpoints is non-NULL, and no other connection is modifying checkpoints, then it is guaranteed that for any checkpoint in the resulting list, no checkpoints later in the list can be reached by a sequence of virDomainCheckpointGetParent() starting from that earlier checkpoint; otherwise, the order of checkpoints in the resulting list is unspecified.

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 listed below. Within a group, bits are mutually exclusive, where all possible checkpoints are described by exactly one bit from the group. Some hypervisors might reject particular flags where it cannot make a distinction for filtering. If the set of filter flags selected forms an impossible combination, the 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).

domain
a domain object
checkpoints
pointer to variable to store the array containing checkpoint object, or NULL if the list is not required (just returns number of checkpoints)
flags
bitwise-OR of supported virDomainCheckpoinListFlags
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.