Provides APIs for the management of domain checkpoints
typedef struct _virDomainCheckpoint virDomainCheckpoint typedef enum virDomainCheckpointCreateFlags typedef enum virDomainCheckpointDeleteFlags typedef enum virDomainCheckpointListFlags typedef virDomainCheckpoint * virDomainCheckpointPtr typedef enum virDomainCheckpointXMLFlags
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)
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 |
| VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE_VALIDATE | = | 4 (0x4; 1 << 2) | validate disk data state when redefining a checkpoint |
}
virDomainCheckpointDeleteFlags¶Delete a checkpoint
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¶Flags valid for virDomainListAllCheckpoints() and virDomainCheckpointListAllChildren(). 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.
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 |
}
virDomainCheckpointPtr¶typedef virDomainCheckpoint * virDomainCheckpointPtr;A virDomainCheckpointPtr is pointer to a virDomainCheckpoint private structure, and is the type used to reference a domain checkpoint in the API.
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 |
}
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 https://libvirt.org/formatcheckpoint.html#checkpoint-xml 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_REDEFINE_VALIDATE along with VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE the state of the metadata related to the disk state of the redefined checkpoint is validated. Note that hypervisors may require that the domain is running to perform validation.
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.
Note: A checkpoint represents point in time after which blocks changed by the hypervisor are tracked. The tracking of changed blocks notes only whether a block was modified, but does not preserve the old contents. The main purpose of checkpoints is to enable incremental backups. But for a checkpoint to be useful for this purpose, a backup must be performed at the same time as the checkpoint is created. This is done via the virDomainBackupBegin API, which also allows to create a checkpoint at the same time. Creating checkpoints with virDomainCheckpointCreateXML is generally only useful for re-creating the libvirt metadata.
| Object | Permission | Condition |
|---|---|---|
| domain | checkpoint | - |
| domain | fs-freeze | VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE |
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.
| Object | Permission | Condition |
|---|---|---|
| domain | checkpoint | - |
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.
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.
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.
virDomainCheckpointGetName¶const char * virDomainCheckpointGetName (virDomainCheckpointPtr checkpoint)
Get the public name for that checkpoint
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.
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. Note that updating the size may be expensive and data will be inaccurate once guest OS writes to the disk. Also note that hypervisors may require that the domain associated with checkpoint is running when VIR_DOMAIN_CHECKPOINT_XML_SIZE is used.
| Object | Permission | Condition |
|---|---|---|
| domain | read | - |
| domain | read-secure | VIR_DOMAIN_CHECKPOINT_XML_SECURE |
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).
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.
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.
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).
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.