docs/api.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>The libvirt API concepts</h1>
   6
   7     <p> This page describes the main principles and architecture choices
   8     behind the definition of the libvirt API:</p>
   9
  10     <ul id="toc"></ul>
  11
  12     <h2><a id="Objects">Objects Exposed</a></h2>
  13     <p> As defined in the <a href="goals.html">goals section</a>, the libvirt
  14     API is designed to expose all the resources needed to manage the
  15     virtualization support of recent operating systems. The first object
  16     manipulated through the API is the <code>virConnectPtr</code>, which
  17     represents the connection to a hypervisor. Any application using libvirt
  18     is likely to start using the
  19     API by calling one of <a href="html/libvirt-libvirt-host.html#virConnectOpen"
  20     >the virConnectOpen functions</a>. You will note that those functions take
  21     a name argument which is actually a <a href="uri.html">connection URI</a>
  22     to select the right hypervisor to open.
  23     A URI is needed to allow remote connections and also select between
  24     different possible hypervisors. For example, on a Linux system it may be
  25     possible to use both KVM and LinuxContainers on the same node. A NULL
  26     name will default to a preselected hypervisor, but it's probably not a
  27     wise thing to do in most cases. See the <a href="uri.html">connection
  28     URI</a> page for a full descriptions of the values allowed.</p>
  29     <p> OnDevice the application obtains a
  30       <a href="/html/libvirt-libvirt-host.html#virConnectPtr">
  31         <code>virConnectPtr</code>
  32       </a>
  33     connection to the hypervisor it can then use it to manage the hypervisor's
  34     available domains and related virtualization
  35     resources, such as storage and networking. All those are
  36     exposed as first class objects and connected to the hypervisor connection
  37     (and the node or cluster where it is available).</p>
  38     <p class="image">
  39       <img alt="first class objects exposed by the API"
  40            src="libvirt-object-model.png"/>
  41     </p>
  42     <p> The figure above shows the five main objects exported by the API:</p>
  43     <ul>
  44       <li>
  45         <a href="html/libvirt-libvirt-host.html#virConnectPtr">
  46           <code>virConnectPtr</code>
  47         </a>
  48       <p>Represents the connection to a hypervisor. Use one of the
  49       <a href="html/libvirt-libvirt-host.html#virConnectOpen">virConnectOpen</a>
  50       functions to obtain connection to the hypervisor which is then used
  51       as a parameter to other connection API's.</p></li>
  52       <li>
  53         <a href="html/libvirt-libvirt-domain.html#virDomainPtr">
  54           <code>virDomainPtr</code>
  55         </a>
  56       <p>Represents one domain either active or defined (i.e. existing as
  57       permanent config file and storage but not currently running on that
  58       node). The function
  59         <a href="html/libvirt-libvirt-domain.html#virConnectListAllDomains">
  60           <code>virConnectListAllDomains</code>
  61         </a>
  62       lists all the domains for the hypervisor.</p></li>
  63       <li>
  64         <a href="html/libvirt-libvirt-network.html#virNetworkPtr">
  65           <code>virNetworkPtr</code>
  66         </a>
  67       <p>Represents one network either active or defined (i.e. existing
  68       as permanent config file and storage but not currently activated).
  69       The function
  70         <a href="html/libvirt-libvirt-network.html#virConnectListAllNetworks">
  71           <code>virConnectListAllNetworks</code>
  72         </a>
  73       lists all the virtualization networks for the hypervisor.</p></li>
  74       <li>
  75         <a href="html/libvirt-libvirt-storage.html#virStorageVolPtr">
  76           <code>virStorageVolPtr</code>
  77         </a>
  78       <p>Represents one storage volume generally used
  79       as a block device available to one of the domains. The function
  80         <a href="html/libvirt-libvirt-storage.html#virStorageVolLookupByPath">
  81           <code>virStorageVolLookupByPath</code>
  82         </a>
  83       finds the storage volume object based on its path on the node.</p></li>
  84       <li>
  85         <a href="html/libvirt-libvirt-storage.html#virStoragePoolPtr">
  86           <code>virStoragePoolPtr</code>
  87         </a>
  88       <p>Represents a storage pool, which is a logical area
  89       used to allocate and store storage volumes. The function
  90         <a href="html/libvirt-libvirt-storage.html#virConnectListAllStoragePools">
  91           <code>virConnectListAllStoragePools</code>
  92         </a>
  93       lists all of the virtualization storage pools on the hypervisor.
  94       The function
  95         <a href="html/libvirt-libvirt-storage.html#virStoragePoolLookupByVolume">
  96           <code>virStoragePoolLookupByVolume</code>
  97         </a>
  98       finds the storage pool containing a given storage volume.</p></li>
  99     </ul>
 100     <p> Most objects manipulated by the library can also be represented using
 101       XML descriptions. This is used primarily to create those object, but is
 102       also helpful to modify or save their description back.</p>
 103     <p> Domains, networks, and storage pools can be either <code>active</code>
 104       i.e. either running or available for immediate use, or
 105       <code>defined</code> in which case they are inactive but there is
 106       a permanent definition available in the system for them. Based on this
 107       they can be activated dynamically in order to be used.</p>
 108     <p> Most objects can also be named in various ways:</p>
 109     <ul>
 110       <li><code>name</code>
 111       <p>A user friendly identifier but whose uniqueness
 112       cannot be guaranteed between two nodes.</p></li>
 113       <li><code>ID</code>
 114       <p>A runtime unique identifier
 115       provided by the hypervisor for one given activation of the object;
 116       however, it becomes invalid once the resource is deactivated.</p></li >
 117       <li><code>UUID</code>
 118       <p> A 16 byte unique identifier
 119       as defined in <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>,
 120       which is guaranteed to be unique for long term usage and across a
 121       set of nodes.</p></li>
 122     </ul>
 123
 124     <h2><a id="Functions">Functions and Naming Conventions</a></h2>
 125     <p> The naming of the functions present in the library is usually
 126       composed by a prefix describing the object associated to the function
 127       and a verb describing the action on that object.</p>
 128     <p> For each first class object you will find APIs
 129       for the following actions:</p>
 130     <ul>
 131       <li><b>Lookup</b> [...LookupBy...]
 132       <p>Used to perform lookups on objects by some type of identifier,
 133       such as:</p>
 134           <ul>
 135             <li>
 136               <a href="html/libvirt-libvirt-domain.html#virDomainLookupByID">
 137                 <code>virDomainLookupByID</code>
 138               </a>
 139             </li>
 140             <li>
 141               <a href="html/libvirt-libvirt-domain.html#virDomainLookupByName">
 142                 <code>virDomainLookupByName</code>
 143               </a>
 144             </li>
 145             <li>
 146               <a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUID">
 147                 <code>virDomainLookupByUUID</code>
 148               </a>
 149             </li>
 150             <li>
 151               <a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString">
 152                 <code>virDomainLookupByUUIDString</code>
 153               </a>
 154             </li>
 155           </ul>
 156       </li>
 157       <li><b>Enumeration</b> [virConnectList..., virConnectNumOf...]
 158       <p>Used to enumerate a set of object available to a given
 159       hypervisor connection such as:</p>
 160           <ul>
 161             <li>
 162               <a href="html/libvirt-libvirt-domain.html#virConnectListDomains">
 163                 <code>virConnectListDomains</code>
 164               </a>
 165             </li>
 166             <li>
 167               <a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">
 168                 <code>virConnectNumOfDomains</code>
 169               </a>
 170             </li>
 171             <li>
 172               <a href="html/libvirt-libvirt-network.html#virConnectListNetworks">
 173                 <code>virConnectListNetworks</code>
 174               </a>
 175             </li>
 176             <li>
 177               <a href="html/libvirt-libvirt-storage.html#virConnectListStoragePools">
 178                 <code>virConnectListStoragePools</code>
 179               </a>
 180             </li>
 181           </ul>
 182       </li>
 183       <li><b>Description</b> [...GetInfo]
 184       <p>Generic accessor providing a set of generic information about an
 185       object, such as: </p>
 186         <ul>
 187           <li>
 188             <a href="html/libvirt-libvirt-host.html#virNodeGetInfo">
 189               <code>virNodeGetInfo</code>
 190             </a>
 191           </li>
 192           <li>
 193             <a href="html/libvirt-libvirt-domain.html#virDomainGetInfo">
 194               <code>virDomainGetInfo</code>
 195             </a>
 196           </li>
 197           <li>
 198             <a href="html/libvirt-libvirt-storage.html#virStoragePoolGetInfo">
 199               <code>virStoragePoolGetInfo</code>
 200             </a>
 201           </li>
 202           <li>
 203             <a href="html/libvirt-libvirt-storage.html#virStorageVolGetInfo">
 204               <code>virStorageVolGetInfo</code>
 205             </a>
 206           </li>
 207         </ul>
 208       </li>
 209       <li><b>Accessors</b> [...Get..., ...Set...]
 210       <p>Specific accessors used to query or modify data for the given object,
 211       such as: </p>
 212         <ul>
 213           <li>
 214             <a href="html/libvirt-libvirt-host.html#virConnectGetType">
 215               <code>virConnectGetType</code>
 216             </a>
 217           </li>
 218           <li>
 219             <a href="html/libvirt-libvirt-domain.html#virDomainGetMaxMemory">
 220               <code>virDomainGetMaxMemory</code>
 221             </a>
 222           </li>
 223           <li>
 224             <a href="html/libvirt-libvirt-domain.html#virDomainSetMemory">
 225               <code>virDomainSetMemory</code>
 226             </a>
 227           </li>
 228           <li>
 229             <a href="html/libvirt-libvirt-domain.html#virDomainGetVcpus">
 230               <code>virDomainGetVcpus</code>
 231             </a>
 232           </li>
 233           <li>
 234             <a href="html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart">
 235               <code>virStoragePoolSetAutostart</code>
 236             </a>
 237           </li>
 238           <li>
 239             <a href="html/libvirt-libvirt-network.html#virNetworkGetBridgeName">
 240               <code>virNetworkGetBridgeName</code>
 241             </a>
 242           </li>
 243         </ul>
 244       </li>
 245       <li><b>Creation</b> [...Create, ...CreateXML]
 246       <p>Used to create and start objects.  The ...CreateXML APIs will create
 247       the object based on an XML description, while the ...Create APIs will
 248       create the object based on existing object pointer, such as: </p>
 249         <ul>
 250           <li>
 251             <a href="html/libvirt-libvirt-domain.html#virDomainCreate">
 252               <code>virDomainCreate</code>
 253             </a>
 254           </li>
 255           <li>
 256             <a href="html/libvirt-libvirt-domain.html#virDomainCreateXML">
 257               <code>virDomainCreateXML</code>
 258             </a>
 259           </li>
 260           <li>
 261             <a href="html/libvirt-libvirt-network.html#virNetworkCreate">
 262               <code>virNetworkCreate</code>
 263             </a>
 264           </li>
 265           <li>
 266             <a href="html/libvirt-libvirt-network.html#virNetworkCreateXML">
 267               <code>virNetworkCreateXML</code>
 268             </a>
 269           </li>
 270         </ul>
 271       </li>
 272       <li><b>Destruction</b> [...Destroy]
 273       <p>Used to shutdown or deactivate and destroy objects, such as: </p>
 274         <ul>
 275           <li>
 276             <a href="html/libvirt-libvirt-domain.html#virDomainDestroy">
 277               <code>virDomainDestroy</code>
 278             </a>
 279           </li>
 280           <li>
 281             <a href="html/libvirt-libvirt-network.html#virNetworkDestroy">
 282               <code>virNetworkDestroy</code>
 283             </a>
 284           </li>
 285           <li>
 286             <a href="html/libvirt-libvirt-storage.html#virStoragePoolDestroy">
 287               <code>virStoragePoolDestroy</code>
 288             </a>
 289           </li>
 290         </ul>
 291       </li>
 292     </ul>
 293     <p>Note: functions returning vir*Ptr (like the virDomainLookup functions)
 294     allocate memory which needs to be freed by the caller by the corresponding
 295     vir*Free function (e.g. virDomainFree for a virDomainPtr object).
 296     </p>
 297     <p> For more in-depth details of the storage related APIs see
 298       <a href="storage.html">the storage management page</a>.
 299     </p>
 300     <h2><a id="Drivers">The libvirt Drivers</a></h2>
 301     <p>Drivers are the basic building block for libvirt functionality
 302     to support the capability to handle specific hypervisor driver calls.
 303     Drivers are discovered and registered during connection processing as
 304     part of the
 305       <a href="html/libvirt-libvirt-host.html#virInitialize">
 306         <code>virInitialize</code>
 307       </a>
 308     API. Each driver
 309     has a registration API which loads up the driver specific function
 310     references for the libvirt APIs to call. The following is a simplistic
 311     view of the hypervisor driver mechanism. Consider the stacked list of
 312     drivers as a series of modules that can be plugged into the architecture
 313     depending on how libvirt is configured to be built.</p>
 314     <p class="image">
 315       <img alt="The libvirt driver architecture"
 316            src="libvirt-driver-arch.png"/>
 317     </p>
 318     <p>The driver architecture is also used to support other virtualization
 319     components such as storage, storage pools, host device, networking,
 320     network interfaces, and network filters.</p>
 321     <p>See the <a href="drivers.html">libvirt drivers</a> page for more
 322     information on hypervisor and storage specific drivers.</p>
 323     <p>Not all drivers support every virtualization function possible.
 324     The <a href="hvsupport.html">libvirt API support matrix</a> lists
 325     the various functions and support found in each driver by the version
 326     support was added into libvirt.
 327     </p>
 328     <h2><a id="Remote">Daemon and Remote Access</a></h2>
 329     <p>Access to libvirt drivers is primarily handled by the libvirtd
 330     daemon through the <a href="remote.html">remote</a> driver via an
 331     <a href="internals/rpc.html">RPC</a>. Some hypervisors do support
 332     client-side connections and responses, such as Test, OpenVZ, VMware,
 333     Power VM (phyp), VirtualBox (vbox), ESX, Hyper-V, Xen, and Virtuozzo.
 334     The libvirtd daemon service is started on the host at system boot
 335     time and can also be restarted at any time by a properly privileged
 336     user, such as root. The libvirtd daemon uses the same libvirt API
 337     <a href="html/libvirt-libvirt-host.html#virInitialize">
 338       <code>virInitialize</code>
 339     </a>
 340     sequence as applications
 341     for client-side driver registrations, but then extends the registered
 342     driver list to encompass all known drivers supported for all driver
 343     types supported on the host. </p>
 344     <p>The libvirt client <a href="apps.html">applications</a> use a
 345     <a href="uri.html">URI</a> to obtain the <code>virConnectPtr</code>.
 346     The <code>virConnectPtr</code> keeps track of the driver connection
 347     plus a variety of other connections (network, interface, storage, etc.).
 348     The <code>virConnectPtr</code> is then used as a parameter to other
 349     virtualization <a href="#Functions">functions</a>. Depending upon the
 350     driver being used, calls will be routed through the remote driver to
 351     the libvirtd daemon. The daemon will reference the connection specific
 352     driver in order to retrieve the requested information and then pass
 353     back status and/or data through the connection back to the application.
 354     The application can then decide what to do with that data, such as
 355     display, write log data, etc. <a href="migration.html">Migration</a>
 356     is an example of many facets of the architecture in use.</p>
 357
 358     <p class="image">
 359       <img alt="The libvirt daemon and remote architecture"
 360            src="libvirt-daemon-arch.png"/>
 361     </p>
 362     <p>
 363     The key takeaway from the above diagram is that there is a remote driver
 364     which handles transactions for a majority of the drivers. The libvirtd
 365     daemon running on the host will receive transaction requests from the
 366     remote driver and will then query the hypervisor driver as specified in
 367     the <code>virConnectPtr</code> in order to fetch the data. The data will
 368     then be returned through the remote driver to the client application
 369     for processing.
 370     </p>
 371     <p>If you are interested in contributing to libvirt, read the
 372     <a href="http://wiki.libvirt.org/page/FAQ">FAQ</a> and
 373     <a href="hacking.html">hacking</a> guidelines to gain an understanding
 374     of basic rules and guidelines.  In order to add new API functionality
 375     follow the instructions regarding
 376     <a href="api_extension.html">implementing a new API in libvirt</a>.
 377     </p>
 378
 379   </body>
 380 </html>