<?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">
<!--
This file is autogenerated from api.html.in
Do not edit this file. Changes will be lost.
-->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="SHORTCUT ICON" href="32favicon.png" />
<title>libvirt: The libvirt API concepts</title>
<meta name="description" content="libvirt, virtualization, virtualization API" />
</head>
<body>
<div id="header">
<div id="headerLogo"></div>
<div id="headerSearch">
<form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
<input id="query" name="query" type="text" size="12" value="" />
<input id="submit" name="submit" type="submit" value="Search" />
</div></form>
</div>
</div>
<div id="body">
<div id="menu">
<ul class="l0"><li>
<div>
<a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
</div>
</li><li>
<div>
<a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
</div>
</li><li>
<div>
<a title="Applications known to use libvirt" class="inactive" href="apps.html">Applications</a>
</div>
</li><li>
<div>
<a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
</div>
</li><li>
<div>
<a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
<ul class="l1"><li>
<div>
<a title="How to compile libvirt" class="inactive" href="compiling.html">Compiling</a>
</div>
</li><li>
<div>
<a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
</div>
</li><li>
<div>
<a title="Overview of the logical subsystems in the libvirt API" class="active" href="intro.html">Architecture</a>
<ul class="l2"><li>
<div>
<a title="Terminology and goals of libvirt API" class="inactive" href="goals.html">Goals</a>
</div>
</li><li>
<div>
<span class="active">API concepts</span>
</div>
</li><li>
<div>
<a title="Managing virtual machines" class="inactive" href="archdomain.html">Domains</a>
</div>
</li><li>
<div>
<a title="Providing isolated networks and NAT based network connectivity" class="inactive" href="archnetwork.html">Network</a>
</div>
</li><li>
<div>
<a title="Managing storage pools and volumes" class="inactive" href="archstorage.html">Storage</a>
</div>
</li><li>
<div>
<a title="Enumerating host node devices" class="inactive" href="archnode.html">Node Devices</a>
</div>
</li></ul>
</div>
</li><li>
<div>
<a title="Description of the XML formats used in libvirt" class="inactive" href="format.html">XML format</a>
</div>
</li><li>
<div>
<a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
</div>
</li><li>
<div>
<a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
</div>
</li><li>
<div>
<a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
</div>
</li><li>
<div>
<a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
</div>
</li><li>
<div>
<a title="A guide and reference for developing with libvirt" class="inactive" href="devguide.html">Development Guide</a>
</div>
</li><li>
<div>
<a title="Command reference for virsh" class="inactive" href="virshcmdref.html">Virsh Commands</a>
</div>
</li></ul>
</div>
</li><li>
<div>
<a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
</div>
</li><li>
<div>
<a title="Frequently asked questions" class="inactive" href="http://wiki.libvirt.org/page/FAQ">FAQ</a>
</div>
</li><li>
<div>
<a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
</div>
</li><li>
<div>
<a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
</div>
</li><li>
<div>
<a title="Available test suites for libvirt" class="inactive" href="testsuites.html">Test suites</a>
</div>
</li><li>
<div>
<a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
</div>
</li><li>
<div>
<a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
</div>
</li></ul>
</div>
<div id="content">
<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><li>
<a href="#Objects">Objects exposed</a>
</li><li>
<a href="#Functions">Functions and naming
conventions</a>
</li><li>
<a href="#Driver">The libvirt drivers</a>
</li><li>
<a href="#Remote">Daemon and remote access</a>
</li></ul>
<h2>
<a name="Objects" id="Objects">Objects exposed</a>
</h2>
<p> As defined in the <a href="goals.html">goals section</a>, libvirt
API need to expose all the resources needed to manage the virtualization
support of recent operating systems. The first object manipulated though
the API is <code>virConnectPtr</code> which represent a connection to
an 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 an URI to select the right hypervisor to
open, this 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 obtained a <a href="html/libvirt-libvirt.html#virConnectPtr"><code>virConnectPtr</code></a>
connection to the
hypervisor it can then use it to manage domains and related resources
available for virtualization like 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>virConnectPtr: represent a connection to an hypervisor.</li><li>virDomainPtr: represent 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.html#virConnectListDomains"><code>virConnectListDomains</code></a>
allows to list all the IDs for the domains active on this hypervisor.</li><li>virNetworkPtr: represent 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.html#virConnectListNetworks"><code>virConnectListNetworks</code></a>
allows to list all the virtualization networks actived on this node.</li><li>virStorageVolPtr: represent one storage volume, usually this is used
as a block device available to one of the domains. The function
<a href="html/libvirt-libvirt.html#virStorageVolLookupByPath"><code>virStorageVolLookupByPath</code></a> allows to find
the object based on its path on the node.</li><li>virStoragePoolPtr: represent a storage pool, i.e. a logical area
which can be used to allocate and store storage volumes. The function
<a href="html/libvirt-libvirt.html#virStoragePoolLookupByVolume"><code>virStoragePoolLookupByVolume</code></a> allows to find
the storage pool containing a given storage volume.</li></ul>
<p> Most object 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, network 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
thay can be activated dynamically in order to be used.</p>
<p> Most kind of object can also be named in various ways:</p>
<ul><li>by their <code>name</code>, an user friendly identifier but
whose unicity cannot be garanteed between two nodes.</li><li>by their <code>ID</code>, which is a runtime unique identifier
provided by the hypervisor for one given activation of the object,
but it becomes invalid once the resource is deactivated.</li><li>by their <code>UUID</code>, a 16 bytes unique identifier
as defined in <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>,
which is garanteed to be unique for long term usage and across a
set of nodes.</li></ul>
<h2>
<a name="Functions" id="Functions">Functions and naming
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><li><b>Lookup</b>:...LookupByName,</li><li><b>Enumeration</b>:virConnectList... and virConnectNumOf...:
those are used to enumerate a set of object available to an given
hypervisor connection like:
<a href="html/libvirt-libvirt.html#virConnectListDomains"><code>virConnectListDomains</code></a>,
<a href="html/libvirt-libvirt.html#virConnectNumOfDomains"><code>virConnectNumOfDomains</code></a>,
<a href="html/libvirt-libvirt.html#virConnectListNetworks"><code>virConnectListNetworks</code></a>,
<a href="html/libvirt-libvirt.html#virConnectListStoragePools"><code>virConnectListStoragePools</code></a>, etc.</li><li><b>Description</b>: ...GetInfo: those are generic accessor providing
a set of informations about an object, they are
<a href="html/libvirt-libvirt.html#virNodeGetInfo"><code>virNodeGetInfo</code></a>,
<a href="html/libvirt-libvirt.html#virDomainGetInfo"><code>virDomainGetInfo</code></a>,
<a href="html/libvirt-libvirt.html#virStoragePoolGetInfo"><code>virStoragePoolGetInfo</code></a>,
<a href="html/libvirt-libvirt.html#virStorageVolGetInfo"><code>virStorageVolGetInfo</code></a>.</li><li><b>Accessors</b>: ...Get... and ...Set...: those are more specific
accessors to query or modify the given object, like
<a href="html/libvirt-libvirt.html#virConnectGetType"><code>virConnectGetType</code></a>,
<a href="html/libvirt-libvirt.html#virDomainGetMaxMemory"><code>virDomainGetMaxMemory</code></a>,
<a href="html/libvirt-libvirt.html#virDomainSetMemory"><code>virDomainSetMemory</code></a>,
<a href="html/libvirt-libvirt.html#virDomainGetVcpus"><code>virDomainGetVcpus</code></a>,
<a href="html/libvirt-libvirt.html#virStoragePoolSetAutostart"><code>virStoragePoolSetAutostart</code></a>,
<a href="html/libvirt-libvirt.html#virNetworkGetBridgeName"><code>virNetworkGetBridgeName</code></a>, 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
<a href="storage.html">the storage management page</a>.
</p>
<h2>
<a name="Driver" id="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" id="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>
</div>
</div>
<div id="footer">
<p id="sponsor">
Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
</div>
</body>
</html>
