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