This page describes the main principles and architecture choices behind the definition of the libvirt API:
As defined in the goals section, the libvirt
API is designed to expose all the resources needed to manage the
virtualization support of recent operating systems. The first object
manipulated through the API is the virConnectPtr
, which
represents the connection to a hypervisor. Any application using libvirt
is likely to start using the
API by calling one of the virConnectOpen functions. You will note that those functions take
a name argument which is actually a connection URI
to select the right hypervisor to open.
A URI is needed to allow remote connections and also select between
different possible hypervisors. For example, on a Linux system it may be
possible to use both KVM and LinuxContainers on the same node. A NULL
name will default to a preselected hypervisor, but it's probably not a
wise thing to do in most cases. See the connection
URI page for a full descriptions of the values allowed.
Once the application obtains a virConnectPtr
connection to the hypervisor it can then use it to manage the hypervisor's
available domains and related virtualization
resources, such as storage and networking. All those are
exposed as first class objects and connected to the hypervisor connection
(and the node or cluster where it is available).
The figure above shows the five main objects exported by the API:
virConnectPtr
Represents the connection to a hypervisor. Use one of the virConnectOpen functions to obtain connection to the hypervisor which is then used as a parameter to other connection API's.
virDomainPtr
Represents one domain either active or defined (i.e. existing as
permanent config file and storage but not currently running on that
node). The function virConnectListAllDomains
lists all the domains for the hypervisor.
virNetworkPtr
Represents one network either active or defined (i.e. existing
as permanent config file and storage but not currently activated).
The function virConnectListAllNetworks
lists all the virtualization networks for the hypervisor.
virStorageVolPtr
Represents one storage volume generally used
as a block device available to one of the domains. The function
virStorageVolLookupByPath
finds
the storage volume object based on its path on the node.
virStoragePoolPtr
Represents a storage pool, which is a logical area
used to allocate and store storage volumes. The function
virConnectListAllStoragePools
lists
all of the virtualization storage pools on the hypervisor. The function
virStoragePoolLookupByVolume
finds
the storage pool containing a given storage volume.
Most objects manipulated by the library can also be represented using XML descriptions. This is used primarily to create those object, but is also helpful to modify or save their description back.
Domains, networks, and storage pools can be either active
i.e. either running or available for immediate use, or
defined
in which case they are inactive but there is
a permanent definition available in the system for them. Based on this
they can be activated dynamically in order to be used.
Most objects can also be named in various ways:
name
A user friendly identifier but whose uniqueness cannot be guaranteed between two nodes.
ID
A runtime unique identifier provided by the hypervisor for one given activation of the object; however, it becomes invalid once the resource is deactivated.
UUID
A 16 byte unique identifier as defined in RFC 4122, which is guaranteed to be unique for long term usage and across a set of nodes.
The naming of the functions present in the library is usually made of a prefix describing the object associated to the function and a verb describing the action on that object.
For each first class object you will find apis for the following actions:
virConnectListDomains
,
virConnectNumOfDomains
,
virConnectListNetworks
,
virConnectListStoragePools
, etc.virNodeGetInfo
,
virDomainGetInfo
,
virStoragePoolGetInfo
,
virStorageVolGetInfo
.virConnectGetType
,
virDomainGetMaxMemory
,
virDomainSetMemory
,
virDomainGetVcpus
,
virStoragePoolSetAutostart
,
virNetworkGetBridgeName
, etc.For more in-depth details of the storage related APIs see the storage management page.