mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-03 11:51:11 +00:00
f854e051b9
The phyp driver was added in 2009 and does not appear to have had any real feature change since 2011. There's virtually no evidence online of users actually using it. IMO it's time to kill it. This was discussed a bit in April 2016: https://www.redhat.com/archives/libvir-list/2016-April/msg01060.html Final discussion is here: https://www.redhat.com/archives/libvir-list/2019-December/msg01162.html Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Signed-off-by: Cole Robinson <crobinso@redhat.com>
381 lines
16 KiB
XML
381 lines
16 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<body>
|
|
<h1>The libvirt API concepts</h1>
|
|
|
|
<p> This page describes the main principles and architecture choices
|
|
behind the definition of the libvirt API:</p>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<h2><a id="Objects">Objects Exposed</a></h2>
|
|
<p> As defined in the <a href="goals.html">goals section</a>, 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 <code>virConnectPtr</code>, which
|
|
represents the connection to a hypervisor. Any application using libvirt
|
|
is likely to start using the
|
|
API by calling one of <a href="html/libvirt-libvirt-host.html#virConnectOpen"
|
|
>the virConnectOpen functions</a>. You will note that those functions take
|
|
a name argument which is actually a <a href="uri.html">connection URI</a>
|
|
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 <a href="uri.html">connection
|
|
URI</a> page for a full descriptions of the values allowed.</p>
|
|
<p> OnDevice the application obtains a
|
|
<a href="/html/libvirt-libvirt-host.html#virConnectPtr">
|
|
<code>virConnectPtr</code>
|
|
</a>
|
|
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).</p>
|
|
<p class="image">
|
|
<img alt="first class objects exposed by the API"
|
|
src="libvirt-object-model.png"/>
|
|
</p>
|
|
<p> The figure above shows the five main objects exported by the API:</p>
|
|
<ul>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-host.html#virConnectPtr">
|
|
<code>virConnectPtr</code>
|
|
</a>
|
|
<p>Represents the connection to a hypervisor. Use one of the
|
|
<a href="html/libvirt-libvirt-host.html#virConnectOpen">virConnectOpen</a>
|
|
functions to obtain connection to the hypervisor which is then used
|
|
as a parameter to other connection API's.</p></li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainPtr">
|
|
<code>virDomainPtr</code>
|
|
</a>
|
|
<p>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
|
|
<a href="html/libvirt-libvirt-domain.html#virConnectListAllDomains">
|
|
<code>virConnectListAllDomains</code>
|
|
</a>
|
|
lists all the domains for the hypervisor.</p></li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-network.html#virNetworkPtr">
|
|
<code>virNetworkPtr</code>
|
|
</a>
|
|
<p>Represents one network either active or defined (i.e. existing
|
|
as permanent config file and storage but not currently activated).
|
|
The function
|
|
<a href="html/libvirt-libvirt-network.html#virConnectListAllNetworks">
|
|
<code>virConnectListAllNetworks</code>
|
|
</a>
|
|
lists all the virtualization networks for the hypervisor.</p></li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-storage.html#virStorageVolPtr">
|
|
<code>virStorageVolPtr</code>
|
|
</a>
|
|
<p>Represents one storage volume generally used
|
|
as a block device available to one of the domains. The function
|
|
<a href="html/libvirt-libvirt-storage.html#virStorageVolLookupByPath">
|
|
<code>virStorageVolLookupByPath</code>
|
|
</a>
|
|
finds the storage volume object based on its path on the node.</p></li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-storage.html#virStoragePoolPtr">
|
|
<code>virStoragePoolPtr</code>
|
|
</a>
|
|
<p>Represents a storage pool, which is a logical area
|
|
used to allocate and store storage volumes. The function
|
|
<a href="html/libvirt-libvirt-storage.html#virConnectListAllStoragePools">
|
|
<code>virConnectListAllStoragePools</code>
|
|
</a>
|
|
lists all of the virtualization storage pools on the hypervisor.
|
|
The function
|
|
<a href="html/libvirt-libvirt-storage.html#virStoragePoolLookupByVolume">
|
|
<code>virStoragePoolLookupByVolume</code>
|
|
</a>
|
|
finds the storage pool containing a given storage volume.</p></li>
|
|
</ul>
|
|
<p> 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.</p>
|
|
<p> Domains, networks, and storage pools can be either <code>active</code>
|
|
i.e. either running or available for immediate use, or
|
|
<code>defined</code> 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.</p>
|
|
<p> Most objects can also be named in various ways:</p>
|
|
<ul>
|
|
<li><code>name</code>
|
|
<p>A user friendly identifier but whose uniqueness
|
|
cannot be guaranteed between two nodes.</p></li>
|
|
<li><code>ID</code>
|
|
<p>A runtime unique identifier
|
|
provided by the hypervisor for one given activation of the object;
|
|
however, it becomes invalid once the resource is deactivated.</p></li >
|
|
<li><code>UUID</code>
|
|
<p> A 16 byte unique identifier
|
|
as defined in <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>,
|
|
which is guaranteed to be unique for long term usage and across a
|
|
set of nodes.</p></li>
|
|
</ul>
|
|
|
|
<h2><a id="Functions">Functions and Naming Conventions</a></h2>
|
|
<p> The naming of the functions present in the library is usually
|
|
composed by a prefix describing the object associated to the function
|
|
and a verb describing the action on that object.</p>
|
|
<p> For each first class object you will find APIs
|
|
for the following actions:</p>
|
|
<ul>
|
|
<li><b>Lookup</b> [...LookupBy...]
|
|
<p>Used to perform lookups on objects by some type of identifier,
|
|
such as:</p>
|
|
<ul>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByID">
|
|
<code>virDomainLookupByID</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByName">
|
|
<code>virDomainLookupByName</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUID">
|
|
<code>virDomainLookupByUUID</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString">
|
|
<code>virDomainLookupByUUIDString</code>
|
|
</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><b>Enumeration</b> [virConnectList..., virConnectNumOf...]
|
|
<p>Used to enumerate a set of object available to a given
|
|
hypervisor connection such as:</p>
|
|
<ul>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virConnectListDomains">
|
|
<code>virConnectListDomains</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">
|
|
<code>virConnectNumOfDomains</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-network.html#virConnectListNetworks">
|
|
<code>virConnectListNetworks</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-storage.html#virConnectListStoragePools">
|
|
<code>virConnectListStoragePools</code>
|
|
</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><b>Description</b> [...GetInfo]
|
|
<p>Generic accessor providing a set of generic information about an
|
|
object, such as: </p>
|
|
<ul>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-host.html#virNodeGetInfo">
|
|
<code>virNodeGetInfo</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainGetInfo">
|
|
<code>virDomainGetInfo</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-storage.html#virStoragePoolGetInfo">
|
|
<code>virStoragePoolGetInfo</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-storage.html#virStorageVolGetInfo">
|
|
<code>virStorageVolGetInfo</code>
|
|
</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><b>Accessors</b> [...Get..., ...Set...]
|
|
<p>Specific accessors used to query or modify data for the given object,
|
|
such as: </p>
|
|
<ul>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-host.html#virConnectGetType">
|
|
<code>virConnectGetType</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainGetMaxMemory">
|
|
<code>virDomainGetMaxMemory</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainSetMemory">
|
|
<code>virDomainSetMemory</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainGetVcpus">
|
|
<code>virDomainGetVcpus</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart">
|
|
<code>virStoragePoolSetAutostart</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-network.html#virNetworkGetBridgeName">
|
|
<code>virNetworkGetBridgeName</code>
|
|
</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><b>Creation</b> [...Create, ...CreateXML]
|
|
<p>Used to create and start objects. The ...CreateXML APIs will create
|
|
the object based on an XML description, while the ...Create APIs will
|
|
create the object based on existing object pointer, such as: </p>
|
|
<ul>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainCreate">
|
|
<code>virDomainCreate</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainCreateXML">
|
|
<code>virDomainCreateXML</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-network.html#virNetworkCreate">
|
|
<code>virNetworkCreate</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-network.html#virNetworkCreateXML">
|
|
<code>virNetworkCreateXML</code>
|
|
</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><b>Destruction</b> [...Destroy]
|
|
<p>Used to shutdown or deactivate and destroy objects, such as: </p>
|
|
<ul>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-domain.html#virDomainDestroy">
|
|
<code>virDomainDestroy</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-network.html#virNetworkDestroy">
|
|
<code>virNetworkDestroy</code>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="html/libvirt-libvirt-storage.html#virStoragePoolDestroy">
|
|
<code>virStoragePoolDestroy</code>
|
|
</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Note: functions returning vir*Ptr (like the virDomainLookup functions)
|
|
allocate memory which needs to be freed by the caller by the corresponding
|
|
vir*Free function (e.g. virDomainFree for a virDomainPtr object).
|
|
</p>
|
|
<p> For more in-depth details of the storage related APIs see
|
|
<a href="storage.html">the storage management page</a>.
|
|
</p>
|
|
<h2><a id="Drivers">The libvirt Drivers</a></h2>
|
|
<p>Drivers are the basic building block for libvirt functionality
|
|
to support the capability to handle specific hypervisor driver calls.
|
|
Drivers are discovered and registered during connection processing as
|
|
part of the
|
|
<a href="html/libvirt-libvirt-host.html#virInitialize">
|
|
<code>virInitialize</code>
|
|
</a>
|
|
API. Each driver
|
|
has a registration API which loads up the driver specific function
|
|
references for the libvirt APIs to call. The following is a simplistic
|
|
view of the hypervisor driver mechanism. Consider the stacked list of
|
|
drivers as a series of modules that can be plugged into the architecture
|
|
depending on how libvirt is configured to be built.</p>
|
|
<p class="image">
|
|
<img alt="The libvirt driver architecture"
|
|
src="libvirt-driver-arch.png"/>
|
|
</p>
|
|
<p>The driver architecture is also used to support other virtualization
|
|
components such as storage, storage pools, host device, networking,
|
|
network interfaces, and network filters.</p>
|
|
<p>See the <a href="drivers.html">libvirt drivers</a> page for more
|
|
information on hypervisor and storage specific drivers.</p>
|
|
<p>Not all drivers support every virtualization function possible.
|
|
The <a href="hvsupport.html">libvirt API support matrix</a> lists
|
|
the various functions and support found in each driver by the version
|
|
support was added into libvirt.
|
|
</p>
|
|
<h2><a id="Remote">Daemon and Remote Access</a></h2>
|
|
<p>Access to libvirt drivers is primarily handled by the libvirtd
|
|
daemon through the <a href="remote.html">remote</a> driver via an
|
|
<a href="internals/rpc.html">RPC</a>. Some hypervisors do support
|
|
client-side connections and responses, such as Test, OpenVZ, VMware,
|
|
VirtualBox (vbox), ESX, Hyper-V, Xen, and Virtuozzo.
|
|
The libvirtd daemon service is started on the host at system boot
|
|
time and can also be restarted at any time by a properly privileged
|
|
user, such as root. The libvirtd daemon uses the same libvirt API
|
|
<a href="html/libvirt-libvirt-host.html#virInitialize">
|
|
<code>virInitialize</code>
|
|
</a>
|
|
sequence as applications
|
|
for client-side driver registrations, but then extends the registered
|
|
driver list to encompass all known drivers supported for all driver
|
|
types supported on the host. </p>
|
|
<p>The libvirt client <a href="apps.html">applications</a> use a
|
|
<a href="uri.html">URI</a> to obtain the <code>virConnectPtr</code>.
|
|
The <code>virConnectPtr</code> keeps track of the driver connection
|
|
plus a variety of other connections (network, interface, storage, etc.).
|
|
The <code>virConnectPtr</code> is then used as a parameter to other
|
|
virtualization <a href="#Functions">functions</a>. Depending upon the
|
|
driver being used, calls will be routed through the remote driver to
|
|
the libvirtd daemon. The daemon will reference the connection specific
|
|
driver in order to retrieve the requested information and then pass
|
|
back status and/or data through the connection back to the application.
|
|
The application can then decide what to do with that data, such as
|
|
display, write log data, etc. <a href="migration.html">Migration</a>
|
|
is an example of many facets of the architecture in use.</p>
|
|
|
|
<p class="image">
|
|
<img alt="The libvirt daemon and remote architecture"
|
|
src="libvirt-daemon-arch.png"/>
|
|
</p>
|
|
<p>
|
|
The key takeaway from the above diagram is that there is a remote driver
|
|
which handles transactions for a majority of the drivers. The libvirtd
|
|
daemon running on the host will receive transaction requests from the
|
|
remote driver and will then query the hypervisor driver as specified in
|
|
the <code>virConnectPtr</code> in order to fetch the data. The data will
|
|
then be returned through the remote driver to the client application
|
|
for processing.
|
|
</p>
|
|
<p>If you are interested in contributing to libvirt, read the
|
|
<a href="http://wiki.libvirt.org/page/FAQ">FAQ</a> and
|
|
<a href="hacking.html">hacking</a> guidelines to gain an understanding
|
|
of basic rules and guidelines. In order to add new API functionality
|
|
follow the instructions regarding
|
|
<a href="api_extension.html">implementing a new API in libvirt</a>.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|