2009-04-15 20:42:50 +00:00
|
|
|
<?xml version="1.0"?>
|
|
|
|
<html>
|
|
|
|
<body>
|
|
|
|
<h1>The libvirt API concepts</h1>
|
|
|
|
|
|
|
|
<p> This page describes the main principles and architecture choices
|
2011-04-01 22:02:10 +00:00
|
|
|
behind the definition of the libvirt API:</p>
|
2010-10-23 21:46:32 +00:00
|
|
|
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
|
2013-02-12 17:48:46 +00:00
|
|
|
<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
|
2009-04-15 20:42:50 +00:00
|
|
|
API by calling one of <a href="html/libvirt-libvirt.html#virConnectOpen"
|
|
|
|
>the virConnectOpen functions</a>. You will note that those functions take
|
2013-02-12 17:48:46 +00:00
|
|
|
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
|
2009-04-15 20:42:50 +00:00
|
|
|
wise thing to do in most cases. See the <a href="uri.html">connection
|
2011-04-01 22:02:10 +00:00
|
|
|
URI</a> page for a full descriptions of the values allowed.</p>
|
2013-02-12 17:48:46 +00:00
|
|
|
<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
|
2009-04-15 20:42:50 +00:00
|
|
|
(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>
|
2013-02-12 17:53:59 +00:00
|
|
|
<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
|
2009-04-15 20:42:50 +00:00
|
|
|
as a block device available to one of the domains. The function
|
2013-02-12 17:53:59 +00:00
|
|
|
<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>
|
2009-04-15 20:42:50 +00:00
|
|
|
</ul>
|
2013-02-12 17:53:59 +00:00
|
|
|
<p> Most objects manipulated by the library can also be represented using
|
2009-04-15 20:42:50 +00:00
|
|
|
XML descriptions. This is used primarily to create those object, but is
|
|
|
|
also helpful to modify or save their description back.</p>
|
2013-02-12 17:53:59 +00:00
|
|
|
<p> Domains, networks, and storage pools can be either <code>active</code>
|
2009-04-15 20:42:50 +00:00
|
|
|
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
|
2013-02-12 17:53:59 +00:00
|
|
|
they can be activated dynamically in order to be used.</p>
|
|
|
|
<p> Most objects can also be named in various ways:</p>
|
2009-04-15 20:42:50 +00:00
|
|
|
<ul>
|
2013-02-12 17:53:59 +00:00
|
|
|
<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
|
2009-04-15 20:42:50 +00:00
|
|
|
as defined in <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>,
|
2012-10-11 16:31:20 +00:00
|
|
|
which is guaranteed to be unique for long term usage and across a
|
2013-02-12 17:53:59 +00:00
|
|
|
set of nodes.</p></li>
|
2009-04-15 20:42:50 +00:00
|
|
|
</ul>
|
2009-11-06 15:04:19 +00:00
|
|
|
|
2010-09-16 10:07:19 +00:00
|
|
|
<h2><a name="Functions">Functions and naming
|
2009-04-15 20:42:50 +00:00
|
|
|
conventions</a></h2>
|
|
|
|
<p> 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.</p>
|
|
|
|
<p> For each first class object you will find apis
|
|
|
|
for the following actions:</p>
|
|
|
|
<ul>
|
2011-04-01 22:02:10 +00:00
|
|
|
<li><b>Lookup</b>:...LookupByName,</li>
|
2009-04-15 20:42:50 +00:00
|
|
|
<li><b>Enumeration</b>:virConnectList... and virConnectNumOf...:
|
|
|
|
those are used to enumerate a set of object available to an given
|
|
|
|
hypervisor connection like:
|
|
|
|
<code class='docref'>virConnectListDomains</code>,
|
|
|
|
<code class='docref'>virConnectNumOfDomains</code>,
|
|
|
|
<code class='docref'>virConnectListNetworks</code>,
|
|
|
|
<code class='docref'>virConnectListStoragePools</code>, etc.</li>
|
|
|
|
<li><b>Description</b>: ...GetInfo: those are generic accessor providing
|
|
|
|
a set of informations about an object, they are
|
|
|
|
<code class='docref'>virNodeGetInfo</code>,
|
|
|
|
<code class='docref'>virDomainGetInfo</code>,
|
|
|
|
<code class='docref'>virStoragePoolGetInfo</code>,
|
|
|
|
<code class='docref'>virStorageVolGetInfo</code>.</li>
|
|
|
|
<li><b>Accessors</b>: ...Get... and ...Set...: those are more specific
|
|
|
|
accessors to query or modify the given object, like
|
|
|
|
<code class='docref'>virConnectGetType</code>,
|
|
|
|
<code class='docref'>virDomainGetMaxMemory</code>,
|
|
|
|
<code class='docref'>virDomainSetMemory</code>,
|
|
|
|
<code class='docref'>virDomainGetVcpus</code>,
|
|
|
|
<code class='docref'>virStoragePoolSetAutostart</code>,
|
|
|
|
<code class='docref'>virNetworkGetBridgeName</code>, etc.</li>
|
|
|
|
<li><b>Creation</b>: </li>
|
|
|
|
<li><b>Destruction</b>: ... </li>
|
|
|
|
</ul>
|
|
|
|
<p> For more in-depth details of the storage related APIs see
|
2011-04-01 22:02:10 +00:00
|
|
|
<a href="storage.html">the storage management page</a>.
|
|
|
|
</p>
|
2010-09-16 10:07:19 +00:00
|
|
|
<h2><a name="Driver">The libvirt drivers</a></h2>
|
2009-04-15 20:42:50 +00:00
|
|
|
<p></p>
|
|
|
|
<p class="image">
|
|
|
|
<img alt="The libvirt driver architecture"
|
|
|
|
src="libvirt-driver-arch.png"/>
|
|
|
|
</p>
|
2010-09-16 10:07:19 +00:00
|
|
|
<h2><a name="Remote">Daemon and remote access</a></h2>
|
2009-04-15 20:42:50 +00:00
|
|
|
<p></p>
|
|
|
|
<p class="image">
|
|
|
|
<img alt="The libvirt daemon and remote architecture"
|
|
|
|
src="libvirt-daemon-arch.png"/>
|
|
|
|
</p>
|
|
|
|
</body>
|
|
|
|
</html>
|