Module libvirt-domain-backup from libvirt

Provides APIs for the management of domain backups Copyright (C) 2017 Parallels International GmbH 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 _virDomainBlockSnapshotX virDomainBlockSnapshotX
typedef enum virDomainBlockSnapshotXCreateFlags
typedef virDomainBlockSnapshotX * virDomainBlockSnapshotXPtr

Functions 

int	virDomainBlockCheckpointXRemove	(virDomainPtr domain, 
					 const char * name, 
					 unsigned int flags)
int	virDomainBlockExportXStart	(virDomainPtr domain, 
					 const char * xmlDesc, 
					 unsigned int flags)
int	virDomainBlockExportXStop	(virDomainPtr domain, 
					 const char * xmlDesc, 
					 unsigned int flags)
virDomainBlockSnapshotXPtr	virDomainBlockSnapshotXCreateXML	(virDomainPtr domain, 
							 const char * xmlDesc, 
							 unsigned int flags)
int	virDomainBlockSnapshotXDelete	(virDomainBlockSnapshotXPtr snapshot, 
					 unsigned int flags)
int	virDomainBlockSnapshotXFree	(virDomainBlockSnapshotXPtr snapshot)
virConnectPtr	virDomainBlockSnapshotXGetConnect	(virDomainBlockSnapshotXPtr snapshot)
virDomainPtr	virDomainBlockSnapshotXGetDomain	(virDomainBlockSnapshotXPtr snapshot)
const char *	virDomainBlockSnapshotXGetName	(virDomainBlockSnapshotXPtr snapshot)
char *	virDomainBlockSnapshotXGetXMLDesc	(virDomainBlockSnapshotXPtr snapshot, 
						 unsigned int flags)
int	virDomainBlockSnapshotXList	(virDomainPtr domain, 
					 virDomainBlockSnapshotXPtr ** snaps, 
					 unsigned int flags)
virDomainBlockSnapshotXPtr	virDomainBlockSnapshotXLookupByName	(virDomainPtr domain, 
							 const char * name, 
							 unsigned int flags)
int	virDomainBlockSnapshotXRef	(virDomainBlockSnapshotXPtr snapshot)

Description

Types

virDomainBlockSnapshotX 

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

virDomainBlockSnapshotXCreateFlags 

enum virDomainBlockSnapshotXCreateFlags {
VIR_DOMAIN_BLOCK_SNAPSHOT_X_CREATE_QUIESCE = 1 (0x1; 1 << 0)
use guest agent to quiesce all mounted file systems within the domain
VIR_DOMAIN_BLOCK_SNAPSHOT_X_CREATE_AUTODELETE = 2 (0x2; 1 << 1)
VIR_DOMAIN_BLOCK_SNAPSHOT_X_CREATE_CHECKPOINT = 4 (0x4; 1 << 2)
VIR_DOMAIN_BLOCK_SNAPSHOT_X_CREATE_BYPASS_CACHE = 8 (0x8; 1 << 3) 
}

Functions

virDomainBlockCheckpointXRemove 

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

Delete the checkpoint from all domain disks.

domain
domain object
name
checkpoint name
flags
reserved, must be 0
Returns
0 if the checkpoint was successfully deleted, or -1 on error.

virDomainBlockExportXStart 

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

Export disks/snapshots via the protocol specified in @xmlDesc. The export server will be started if it is not yet running.

Block snaphots can only be exported in the read mode. Disks can be exported in the write mode only if both VIR_DOMAIN_START_PAUSED and VIR_DOMAIN_START_X_EXPORTABLE are set on domain start and only before the domain is resumed.

domain
domain object
xmlDesc
export XML description
flags
reserved, must be 0
Returns
0 if the export was successfully started, or -1 on error.

virDomainBlockExportXStop 

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

Delete disks/snapshots from the export through the protocol specified in @xmlDesc. The export server will be shut down if nothing is left to export.

domain
domain object
xmlDesc
export XML description
flags
reserved, must be 0
Returns
0 if the export was successfully started, or -1 on error.

virDomainBlockSnapshotXCreateXML 

virDomainBlockSnapshotXPtr	virDomainBlockSnapshotXCreateXML	(virDomainPtr domain,
							 const char * xmlDesc,
							 unsigned int flags)

Create a block snapshot based on the XML description in @xmlDesc. Block snapshots differ from plain domain disk snapshots. A plain snapshot creates a new image file backed by the original image file. The new data written to disk goes to the new image while the original image holds the data for the moment the snapshot was taken at. A block snaphot also creates a new image file backed by the original image file, but the new data still goes to the original image. Before the new data is written to the original image, however, the previous data is written to a new image (sometimes called a fleece image). As a result, the fleece image maintains the disk snapshot.

If @flags includes VIR_DOMAIN_BLOCK_SNAPSHOT_X_CREATE_CHECKPOINT, then a checkpoint will be added to every disk in the snapshot. The checkpoint provides the means to query which parts of disk have changed since the checkpoint was created. This is typically used for creating incremental backups. For example, if the first snapshot was created with a checkpoint and copied to the backup store, when the second snapshot is created, the backup agent can just copy the parts of disk that have changed since the first backup.

If @flags includes VIR_DOMAIN_BLOCK_SNAPSHOT_X_CREATE_AUTODELETE, then block snapshot will be deleted on client disconnect.

If @flags includes VIR_DOMAIN_BLOCK_SNAPSHOT_X_CREATE_QUIESCE, then libvirt will attempt to use the guest agent to freeze and thaw all file systems in use within the domain OS. If, however, the guest agent is not present, an error will be thrown.

If @flags includes VIR_DOMAIN_BLOCK_SNAPSHOT_X_CREATE_BYPASS_CACHE, then libvirt will attempt to bypass the file system cache while writing to the fleece image, or fail if it cannot do so for the given system; this can allow less pressure on file system cache, but also risks slowing saves to NFS.

domain
domain object
xmlDesc
block snapshot XML description
flags
bitwise-OR of virDomainBlockSnapshotXCreateFlags
Returns
an (opaque) virDomainBlockSnapshotXPtr on success, NULL on failure.

virDomainBlockSnapshotXDelete 

int	virDomainBlockSnapshotXDelete	(virDomainBlockSnapshotXPtr snapshot,
					 unsigned int flags)

Delete the snapshot. Fleece images are discared but checkpoints are kept.

snapshot
block snapshot object
flags
reserved, must be 0
Returns
0 if the snapshot was successfully deleted, -1 on error.

virDomainBlockSnapshotXFree 

int	virDomainBlockSnapshotXFree	(virDomainBlockSnapshotXPtr snapshot)

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

snapshot
domain snapshot object
Returns
0 in case of success, or -1 in case of failure.

virDomainBlockSnapshotXGetConnect 

virConnectPtr	virDomainBlockSnapshotXGetConnect	(virDomainBlockSnapshotXPtr snapshot)

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

WARNING: Do not use this function when writing libvirt bindings in other languages. Instead store the connection and the snapshot object together.

snapshot
snapshot object
Returns
the connection or NULL.

virDomainBlockSnapshotXGetDomain 

virDomainPtr	virDomainBlockSnapshotXGetDomain	(virDomainBlockSnapshotXPtr snapshot)

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

WARNING: Do not use this function when writing libvirt bindings in other languages. Instead store the domain and the snapshot object together.

snapshot
snapshot object
Returns
the domain or NULL.

virDomainBlockSnapshotXGetName 

const char *	virDomainBlockSnapshotXGetName	(virDomainBlockSnapshotXPtr snapshot)

Get the name of the snapshot.

snapshot
snapshot object
Returns
a pointer to the name or NULL. The string does not have to be deallocated as its lifetime will be the same as that of the snapshot object.

virDomainBlockSnapshotXGetXMLDesc 

char *	virDomainBlockSnapshotXGetXMLDesc	(virDomainBlockSnapshotXPtr snapshot,
						 unsigned int flags)

Provide an XML description of the block snapshot.

snapshot
domain snapshot object
flags
reserved, must be 0
Returns
a zero-terminated UTF-8-encoded XML instance, or NULL in case of error. The caller must free() the returned value.

virDomainBlockSnapshotXList 

int	virDomainBlockSnapshotXList	(virDomainPtr domain,
					 virDomainBlockSnapshotXPtr ** snaps,
					 unsigned int flags)

Collect the list of block snapshots for the domain, and allocates an array to store those objects.

domain
domain object
snaps
pointer to a variable to store the array containing block snapshot objects, or NULL if the list is not required (just returns the number of block snapshots then).
flags
reserved, must be 0
Returns
the number of block snapshots found or -1 and sets @snaps to NULL in case of error. On success, the array stored into @snaps 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 virDomainBlockSnapshotXFree() on each array element, then calling free() on @snaps.

virDomainBlockSnapshotXLookupByName 

virDomainBlockSnapshotXPtr	virDomainBlockSnapshotXLookupByName	(virDomainPtr domain,
							 const char * name,
							 unsigned int flags)

Look up a block snapshot by name.

domain
domain object
name
name for the block snapshot
flags
reserved, must be 0
Returns
a block snapshot object, or NULL in case of failure. If the domain snapshot cannot be found, the VIR_ERR_NO_DOMAIN_SNAPSHOT error is raised.

virDomainBlockSnapshotXRef 

int	virDomainBlockSnapshotXRef	(virDomainBlockSnapshotXPtr snapshot)

Increment the reference count on the snapshot. For each additional call to this method, there must be a corresponding call to virDomainBlockSnapshotXFree 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 snapshot. That is, each new thread using a snapshot will increment the reference count.

snapshot
snapshot to hold a reference on
Returns
0 in case of success, or -1 in case of failure.