mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-05 04:41:20 +00:00
243 lines
13 KiB
XML
243 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<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 name="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.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> Once the application obtains a <code class='docref'>virConnectPtr</code>
|
|
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><code class='docref'>virConnectPtr</code>
|
|
<p>Represents the connection to a hypervisor. Use one of the
|
|
<a href="html/libvirt-libvirt.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><code class='docref'>virDomainPtr</code>
|
|
<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 <code class='docref'>virConnectListAllDomains</code>
|
|
lists all the domains for the hypervisor.</p></li>
|
|
<li><code class='docref'>virNetworkPtr</code>
|
|
<p>Represents one network either active or defined (i.e. existing
|
|
as permanent config file and storage but not currently activated).
|
|
The function <code class='docref'>virConnectListAllNetworks</code>
|
|
lists all the virtualization networks for the hypervisor.</p></li>
|
|
<li><code class='docref'>virStorageVolPtr</code>
|
|
<p>Represents one storage volume generally used
|
|
as a block device available to one of the domains. The function
|
|
<code class="docref">virStorageVolLookupByPath</code> finds
|
|
the storage volume object based on its path on the node.</p></li>
|
|
<li><code class='docref'>virStoragePoolPtr</code>
|
|
<p>Represents a storage pool, which is a logical area
|
|
used to allocate and store storage volumes. The function
|
|
<code class='docref'>virConnectListAllStoragePools</code> lists
|
|
all of the virtualization storage pools on the hypervisor. The function
|
|
<code class="docref">virStoragePoolLookupByVolume</code> 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 name="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><code class='docref'>virDomainLookupByID</code></li>
|
|
<li><code class='docref'>virDomainLookupByName</code></li>
|
|
<li><code class='docref'>virDomainLookupByUUID</code></li>
|
|
<li><code class='docref'>virDomainLookupByUUIDString</code></li>
|
|
</ul>
|
|
</li>
|
|
<li><b>Enumeration</b> [virConnectList..., virConnectNumOf...]
|
|
<p>Used to enumerate a set of object available to an given
|
|
hypervisor connection such as:</p>
|
|
<ul>
|
|
<li><code class='docref'>virConnectListDomains</code></li>
|
|
<li><code class='docref'>virConnectNumOfDomains</code></li>
|
|
<li><code class='docref'>virConnectListNetworks</code></li>
|
|
<li><code class='docref'>virConnectListStoragePools</code></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><code class='docref'>virNodeGetInfo</code></li>
|
|
<li><code class='docref'>virDomainGetInfo</code></li>
|
|
<li><code class='docref'>virStoragePoolGetInfo</code></li>
|
|
<li><code class='docref'>virStorageVolGetInfo</code></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><code class='docref'>virConnectGetType</code></li>
|
|
<li><code class='docref'>virDomainGetMaxMemory</code></li>
|
|
<li><code class='docref'>virDomainSetMemory</code></li>
|
|
<li><code class='docref'>virDomainGetVcpus</code></li>
|
|
<li><code class='docref'>virStoragePoolSetAutostart</code></li>
|
|
<li><code class='docref'>virNetworkGetBridgeName</code></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><code class='docref'>virDomainCreate</code></li>
|
|
<li><code class='docref'>virDomainCreateXML</code></li>
|
|
<li><code class='docref'>virNetworkCreate</code></li>
|
|
<li><code class='docref'>virNetworkCreateXML</code></li>
|
|
</ul>
|
|
</li>
|
|
<li><b>Destruction</b> [...Destroy]
|
|
<p>Used to shutdown or deactivate and destroy objects, such as: </p>
|
|
<ul>
|
|
<li><code class='docref'>virDomainDestroy</code></li>
|
|
<li><code class='docref'>virNetworkDestroy</code></li>
|
|
<li><code class='docref'>virStoragePoolDestroy</code></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 name="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 <code class='docref'>virInitialize</code> 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 name="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,
|
|
Power VM (phyp), VirtualBox (vbox), ESX, Hyper-V, Xen, and Parallels.
|
|
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
|
|
<code class='docref'>virInitialize</code> 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>
|