mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-08-05 00:13:48 +00:00
178 lines
8.7 KiB
XML
178 lines
8.7 KiB
XML
<?xml version="1.0"?>
|
|
<html>
|
|
<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> For more in-depth details of the storage related APIs see
|
|
<a href="storage.html">the storage management page</a>.
|
|
</p>
|
|
<h2><a name="Driver">The libvirt drivers</a></h2>
|
|
<p></p>
|
|
<p class="image">
|
|
<img alt="The libvirt driver architecture"
|
|
src="libvirt-driver-arch.png"/>
|
|
</p>
|
|
<h2><a name="Remote">Daemon and remote access</a></h2>
|
|
<p></p>
|
|
<p class="image">
|
|
<img alt="The libvirt daemon and remote architecture"
|
|
src="libvirt-daemon-arch.png"/>
|
|
</p>
|
|
</body>
|
|
</html>
|