/usr/share/doc/libvirt-doc/api.html is in libvirt-doc 1.3.1-1ubuntu10.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 | <?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><li>
<div>
<a title="Secure usage of the libvirt APIs" class="inactive" href="secureusage.html">Secure usage</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><li>
<div>
<a title="Project governance and code of conduct" class="inactive" href="governance.html">Governance</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="#Drivers">The libvirt Drivers</a>
</li><li>
<a href="#Remote">Daemon and Remote Access</a>
</li></ul>
<h2>
<a name="Objects" shape="rect" id="Objects">Objects Exposed</a>
<a class="headerlink" href="#Objects" title="Permalink to this headline">¶</a>
</h2>
<p> As defined in the <a href="goals.html" shape="rect">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-host.html#virConnectOpen" shape="rect">the virConnectOpen functions</a>. You will note that those functions take
a name argument which is actually a <a href="uri.html" shape="rect">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" shape="rect">connection
URI</a> page for a full descriptions of the values allowed.</p>
<p> OnDevice the application obtains a
<a href="/html/libvirt-libvirt-host.html#virConnectPtr" shape="rect">
<code>virConnectPtr</code>
</a>
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>
<a href="html/libvirt-libvirt-host.html#virConnectPtr" shape="rect">
<code>virConnectPtr</code>
</a>
<p>Represents the connection to a hypervisor. Use one of the
<a href="html/libvirt-libvirt-host.html#virConnectOpen" shape="rect">virConnectOpen</a>
functions to obtain connection to the hypervisor which is then used
as a parameter to other connection API's.</p></li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainPtr" shape="rect">
<code>virDomainPtr</code>
</a>
<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
<a href="html/libvirt-libvirt-domain.html#virConnectListAllDomains" shape="rect">
<code>virConnectListAllDomains</code>
</a>
lists all the domains for the hypervisor.</p></li><li>
<a href="html/libvirt-libvirt-network.html#virNetworkPtr" shape="rect">
<code>virNetworkPtr</code>
</a>
<p>Represents 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-network.html#virConnectListAllNetworks" shape="rect">
<code>virConnectListAllNetworks</code>
</a>
lists all the virtualization networks for the hypervisor.</p></li><li>
<a href="html/libvirt-libvirt-storage.html#virStorageVolPtr" shape="rect">
<code>virStorageVolPtr</code>
</a>
<p>Represents one storage volume generally used
as a block device available to one of the domains. The function
<a href="html/libvirt-libvirt-storage.html#virStorageVolLookupByPath" shape="rect">
<code>virStorageVolLookupByPath</code>
</a>
finds the storage volume object based on its path on the node.</p></li><li>
<a href="html/libvirt-libvirt-storage.html#virStoragePoolPtr" shape="rect">
<code>virStoragePoolPtr</code>
</a>
<p>Represents a storage pool, which is a logical area
used to allocate and store storage volumes. The function
<a href="html/libvirt-libvirt-storage.html#virConnectListAllStoragePools" shape="rect">
<code>virConnectListAllStoragePools</code>
</a>
lists all of the virtualization storage pools on the hypervisor.
The function
<a href="html/libvirt-libvirt-storage.html#virStoragePoolLookupByVolume" shape="rect">
<code>virStoragePoolLookupByVolume</code>
</a>
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" shape="rect">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" shape="rect" id="Functions">Functions and Naming Conventions</a>
<a class="headerlink" href="#Functions" title="Permalink to this headline">¶</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>
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByID" shape="rect">
<code>virDomainLookupByID</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByName" shape="rect">
<code>virDomainLookupByName</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUID" shape="rect">
<code>virDomainLookupByUUID</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString" shape="rect">
<code>virDomainLookupByUUIDString</code>
</a>
</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>
<a href="html/libvirt-libvirt-domain.html#virConnectListDomains" shape="rect">
<code>virConnectListDomains</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains" shape="rect">
<code>virConnectNumOfDomains</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-network.html#virConnectListNetworks" shape="rect">
<code>virConnectListNetworks</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-storage.html#virConnectListStoragePools" shape="rect">
<code>virConnectListStoragePools</code>
</a>
</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>
<a href="html/libvirt-libvirt-host.html#virNodeGetInfo" shape="rect">
<code>virNodeGetInfo</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainGetInfo" shape="rect">
<code>virDomainGetInfo</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-storage.html#virStoragePoolGetInfo" shape="rect">
<code>virStoragePoolGetInfo</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-storage.html#virStorageVolGetInfo" shape="rect">
<code>virStorageVolGetInfo</code>
</a>
</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>
<a href="html/libvirt-libvirt-host.html#virConnectGetType" shape="rect">
<code>virConnectGetType</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainGetMaxMemory" shape="rect">
<code>virDomainGetMaxMemory</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainSetMemory" shape="rect">
<code>virDomainSetMemory</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainGetVcpus" shape="rect">
<code>virDomainGetVcpus</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart" shape="rect">
<code>virStoragePoolSetAutostart</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-network.html#virNetworkGetBridgeName" shape="rect">
<code>virNetworkGetBridgeName</code>
</a>
</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>
<a href="html/libvirt-libvirt-domain.html#virDomainCreate" shape="rect">
<code>virDomainCreate</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-domain.html#virDomainCreateXML" shape="rect">
<code>virDomainCreateXML</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-network.html#virNetworkCreate" shape="rect">
<code>virNetworkCreate</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-network.html#virNetworkCreateXML" shape="rect">
<code>virNetworkCreateXML</code>
</a>
</li></ul>
</li><li><b>Destruction</b> [...Destroy]
<p>Used to shutdown or deactivate and destroy objects, such as: </p>
<ul><li>
<a href="html/libvirt-libvirt-domain.html#virDomainDestroy" shape="rect">
<code>virDomainDestroy</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-network.html#virNetworkDestroy" shape="rect">
<code>virNetworkDestroy</code>
</a>
</li><li>
<a href="html/libvirt-libvirt-storage.html#virStoragePoolDestroy" shape="rect">
<code>virStoragePoolDestroy</code>
</a>
</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" shape="rect">the storage management page</a>.
</p>
<h2>
<a name="Drivers" shape="rect" id="Drivers">The libvirt Drivers</a>
<a class="headerlink" href="#Drivers" title="Permalink to this headline">¶</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
<a href="html/libvirt-libvirt-host.html#virInitialize" shape="rect">
<code>virInitialize</code>
</a>
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" shape="rect">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" shape="rect">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" shape="rect" id="Remote">Daemon and Remote Access</a>
<a class="headerlink" href="#Remote" title="Permalink to this headline">¶</a>
</h2>
<p>Access to libvirt drivers is primarily handled by the libvirtd
daemon through the <a href="remote.html" shape="rect">remote</a> driver via an
<a href="internals/rpc.html" shape="rect">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 Virtuozzo.
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
<a href="html/libvirt-libvirt-host.html#virInitialize" shape="rect">
<code>virInitialize</code>
</a>
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" shape="rect">applications</a> use a
<a href="uri.html" shape="rect">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" shape="rect">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" shape="rect">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" shape="rect">FAQ</a> and
<a href="hacking.html" shape="rect">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" shape="rect">implementing a new API in libvirt</a>.
</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>
|