mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-01-03 03:25:20 +00:00
docs: html.in: Convert api to rst
There were a number of occurrences where we used nested inline markup (verbatim + refs) which is currently not possible with RST syntax [1]. There is a possible workaround involving substitution definitions like .. |virConnectPtr| replace:: ``virConnectPtr`` .. _virConnectPtr: /html/libvirt-libvirt-host.html#virConnectPtr Substitutions cannot be made generic, hence we cannot create a template for substitution and use a single template everywhere, so we'd end up with a lot of clutter and convolution. Therefore, we can make an exception and just link the data type without further style markup. [1] https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible Signed-off-by: Erik Skultety <eskultet@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com>
This commit is contained in:
Erik Skultety
parent
9d503ea9dc
commit
39a80474f6
380
docs/api.html.in
380
docs/api.html.in
@ -1,380 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE html>
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<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 id="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-host.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> OnDevice the application obtains a
|
||||
<a href="/html/libvirt-libvirt-host.html#virConnectPtr">
|
||||
<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">
|
||||
<code>virConnectPtr</code>
|
||||
</a>
|
||||
<p>Represents the connection to a hypervisor. Use one of the
|
||||
<a href="html/libvirt-libvirt-host.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>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainPtr">
|
||||
<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">
|
||||
<code>virConnectListAllDomains</code>
|
||||
</a>
|
||||
lists all the domains for the hypervisor.</p></li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-network.html#virNetworkPtr">
|
||||
<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">
|
||||
<code>virConnectListAllNetworks</code>
|
||||
</a>
|
||||
lists all the virtualization networks for the hypervisor.</p></li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-storage.html#virStorageVolPtr">
|
||||
<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">
|
||||
<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">
|
||||
<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">
|
||||
<code>virConnectListAllStoragePools</code>
|
||||
</a>
|
||||
lists all of the virtualization storage pools on the hypervisor.
|
||||
The function
|
||||
<a href="html/libvirt-libvirt-storage.html#virStoragePoolLookupByVolume">
|
||||
<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="https://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 id="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>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByID">
|
||||
<code>virDomainLookupByID</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByName">
|
||||
<code>virDomainLookupByName</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUID">
|
||||
<code>virDomainLookupByUUID</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString">
|
||||
<code>virDomainLookupByUUIDString</code>
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><b>Enumeration</b> [virConnectList..., virConnectNumOf...]
|
||||
<p>Used to enumerate a set of object available to a given
|
||||
hypervisor connection such as:</p>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virConnectListDomains">
|
||||
<code>virConnectListDomains</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">
|
||||
<code>virConnectNumOfDomains</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-network.html#virConnectListNetworks">
|
||||
<code>virConnectListNetworks</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-storage.html#virConnectListStoragePools">
|
||||
<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">
|
||||
<code>virNodeGetInfo</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainGetInfo">
|
||||
<code>virDomainGetInfo</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-storage.html#virStoragePoolGetInfo">
|
||||
<code>virStoragePoolGetInfo</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-storage.html#virStorageVolGetInfo">
|
||||
<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">
|
||||
<code>virConnectGetType</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainGetMaxMemory">
|
||||
<code>virDomainGetMaxMemory</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainSetMemory">
|
||||
<code>virDomainSetMemory</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainGetVcpus">
|
||||
<code>virDomainGetVcpus</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart">
|
||||
<code>virStoragePoolSetAutostart</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-network.html#virNetworkGetBridgeName">
|
||||
<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">
|
||||
<code>virDomainCreate</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-domain.html#virDomainCreateXML">
|
||||
<code>virDomainCreateXML</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-network.html#virNetworkCreate">
|
||||
<code>virNetworkCreate</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-network.html#virNetworkCreateXML">
|
||||
<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">
|
||||
<code>virDomainDestroy</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-network.html#virNetworkDestroy">
|
||||
<code>virNetworkDestroy</code>
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="html/libvirt-libvirt-storage.html#virStoragePoolDestroy">
|
||||
<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">the storage management page</a>.
|
||||
</p>
|
||||
<h2><a id="Drivers">The libvirt Drivers</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">
|
||||
<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">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">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 id="Remote">Daemon and Remote Access</a></h2>
|
||||
<p>Access to libvirt drivers is primarily handled by the libvirtd
|
||||
daemon through the <a href="remote.html">remote</a> driver via an
|
||||
<a href="internals/rpc.html">RPC</a>. Some hypervisors do support
|
||||
client-side connections and responses, such as Test, OpenVZ, VMware,
|
||||
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">
|
||||
<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">applications</a> use a
|
||||
<a href="uri.html">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">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">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="https://wiki.libvirt.org/page/FAQ">FAQ</a> and
|
||||
<a href="hacking.html">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">implementing a new API in libvirt</a>.
|
||||
</p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
265
docs/api.rst
Normal file
265
docs/api.rst
Normal file
@ -0,0 +1,265 @@
|
||||
========================
|
||||
The libvirt API concepts
|
||||
========================
|
||||
|
||||
This page describes the main principles and architecture choices behind
|
||||
the definition of the libvirt API:
|
||||
|
||||
.. contents::
|
||||
|
||||
Objects Exposed
|
||||
---------------
|
||||
|
||||
As defined in the `goals section <goals.html>`__, 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 ``virConnectPtr``, which represents the
|
||||
connection to a hypervisor. Any application using libvirt is likely to
|
||||
start using the API by calling one of `the virConnectOpen
|
||||
functions <html/libvirt-libvirt-host.html#virConnectOpen>`__. You will
|
||||
note that those functions take a name argument which is actually a
|
||||
`connection URI <uri.html>`__ 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 `connection URI <uri.html>`__
|
||||
page for a full descriptions of the values allowed.
|
||||
|
||||
OnDevice the application obtains a
|
||||
`virConnectPtr </html/libvirt-libvirt-host.html#virConnectPtr>`__
|
||||
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).
|
||||
|
||||
|first class objects exposed by the API|
|
||||
|
||||
The figure above shows the five main objects exported by the API:
|
||||
|
||||
- `virConnectPtr <html/libvirt-libvirt-host.html#virConnectPtr>`__
|
||||
|
||||
Represents the connection to a hypervisor. Use one of the
|
||||
`virConnectOpen <html/libvirt-libvirt-host.html#virConnectOpen>`__
|
||||
functions to obtain connection to the hypervisor which is then used
|
||||
as a parameter to other connection API's.
|
||||
|
||||
- `virDomainPtr <html/libvirt-libvirt-domain.html#virDomainPtr>`__
|
||||
|
||||
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
|
||||
`virConnectListAllDomains <html/libvirt-libvirt-domain.html#virConnectListAllDomains>`__
|
||||
lists all the domains for the hypervisor.
|
||||
|
||||
- `virNetworkPtr <html/libvirt-libvirt-network.html#virNetworkPtr>`__
|
||||
|
||||
Represents one network either active or defined (i.e. existing as
|
||||
permanent config file and storage but not currently activated). The
|
||||
function
|
||||
`virConnectListAllNetworks <html/libvirt-libvirt-network.html#virConnectListAllNetworks>`__
|
||||
lists all the virtualization networks for the hypervisor.
|
||||
|
||||
- `virStorageVolPtr <html/libvirt-libvirt-storage.html#virStorageVolPtr>`__
|
||||
|
||||
Represents one storage volume generally used as a block device
|
||||
available to one of the domains. The function
|
||||
`virStorageVolLookupByPath <html/libvirt-libvirt-storage.html#virStorageVolLookupByPath>`__
|
||||
finds the storage volume object based on its path on the node.
|
||||
|
||||
- `virStoragePoolPtr <html/libvirt-libvirt-storage.html#virStoragePoolPtr>`__
|
||||
|
||||
Represents a storage pool, which is a logical area used to allocate
|
||||
and store storage volumes. The function
|
||||
`virConnectListAllStoragePools <html/libvirt-libvirt-storage.html#virConnectListAllStoragePools>`__
|
||||
lists all of the virtualization storage pools on the hypervisor. The
|
||||
function
|
||||
`virStoragePoolLookupByVolume <html/libvirt-libvirt-storage.html#virStoragePoolLookupByVolume>`__
|
||||
finds the storage pool containing a given storage volume.
|
||||
|
||||
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.
|
||||
|
||||
Domains, networks, and storage pools can be either ``active`` i.e.
|
||||
either running or available for immediate use, or ``defined`` 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.
|
||||
|
||||
Most objects can also be named in various ways:
|
||||
|
||||
- ``name``
|
||||
|
||||
A user friendly identifier but whose uniqueness cannot be guaranteed
|
||||
between two nodes.
|
||||
|
||||
- ``ID``
|
||||
|
||||
A runtime unique identifier provided by the hypervisor for one given
|
||||
activation of the object; however, it becomes invalid once the
|
||||
resource is deactivated.
|
||||
|
||||
- ``UUID``
|
||||
|
||||
A 16 byte unique identifier as defined in `RFC
|
||||
4122 <https://www.ietf.org/rfc/rfc4122.txt>`__, which is guaranteed
|
||||
to be unique for long term usage and across a set of nodes.
|
||||
|
||||
Functions and Naming Conventions
|
||||
--------------------------------
|
||||
|
||||
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.
|
||||
|
||||
For each first class object you will find APIs for the following
|
||||
actions:
|
||||
|
||||
- **Lookup** [...LookupBy...]
|
||||
|
||||
Used to perform lookups on objects by some type of identifier, such
|
||||
as:
|
||||
|
||||
- `virDomainLookupByID <html/libvirt-libvirt-domain.html#virDomainLookupByID>`__
|
||||
- `virDomainLookupByName <html/libvirt-libvirt-domain.html#virDomainLookupByName>`__
|
||||
- `virDomainLookupByUUID <html/libvirt-libvirt-domain.html#virDomainLookupByUUID>`__
|
||||
- `virDomainLookupByUUIDString <html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString>`__
|
||||
|
||||
- **Enumeration** [virConnectList..., virConnectNumOf...]
|
||||
|
||||
Used to enumerate a set of object available to a given hypervisor
|
||||
connection such as:
|
||||
|
||||
- `virConnectListDomains <html/libvirt-libvirt-domain.html#virConnectListDomains>`__
|
||||
- `virConnectNumOfDomains <html/libvirt-libvirt-domain.html#virConnectNumOfDomains>`__
|
||||
- `virConnectListNetworks <html/libvirt-libvirt-network.html#virConnectListNetworks>`__
|
||||
- `virConnectListStoragePools <html/libvirt-libvirt-storage.html#virConnectListStoragePools>`__
|
||||
|
||||
- **Description** [...GetInfo]
|
||||
|
||||
Generic accessor providing a set of generic information about an
|
||||
object, such as:
|
||||
|
||||
- `virNodeGetInfo <html/libvirt-libvirt-host.html#virNodeGetInfo>`__
|
||||
- `virDomainGetInfo <html/libvirt-libvirt-domain.html#virDomainGetInfo>`__
|
||||
- `virStoragePoolGetInfo <html/libvirt-libvirt-storage.html#virStoragePoolGetInfo>`__
|
||||
- `virStorageVolGetInfo <html/libvirt-libvirt-storage.html#virStorageVolGetInfo>`__
|
||||
|
||||
- **Accessors** [...Get..., ...Set...]
|
||||
|
||||
Specific accessors used to query or modify data for the given object,
|
||||
such as:
|
||||
|
||||
- `virConnectGetType <html/libvirt-libvirt-host.html#virConnectGetType>`__
|
||||
- `virDomainGetMaxMemory <html/libvirt-libvirt-domain.html#virDomainGetMaxMemory>`__
|
||||
- `virDomainSetMemory <html/libvirt-libvirt-domain.html#virDomainSetMemory>`__
|
||||
- `virDomainGetVcpus <html/libvirt-libvirt-domain.html#virDomainGetVcpus>`__
|
||||
- `virStoragePoolSetAutostart <html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart>`__
|
||||
- `virNetworkGetBridgeName <html/libvirt-libvirt-network.html#virNetworkGetBridgeName>`__
|
||||
|
||||
- **Creation** [...Create, ...CreateXML]
|
||||
|
||||
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:
|
||||
|
||||
- `virDomainCreate <html/libvirt-libvirt-domain.html#virDomainCreate>`__
|
||||
- `virDomainCreateXML <html/libvirt-libvirt-domain.html#virDomainCreateXML>`__
|
||||
- `virNetworkCreate <html/libvirt-libvirt-network.html#virNetworkCreate>`__
|
||||
- `virNetworkCreateXML <html/libvirt-libvirt-network.html#virNetworkCreateXML>`__
|
||||
|
||||
- **Destruction** [...Destroy]
|
||||
|
||||
Used to shutdown or deactivate and destroy objects, such as:
|
||||
|
||||
- `virDomainDestroy <html/libvirt-libvirt-domain.html#virDomainDestroy>`__
|
||||
- `virNetworkDestroy <html/libvirt-libvirt-network.html#virNetworkDestroy>`__
|
||||
- `virStoragePoolDestroy <html/libvirt-libvirt-storage.html#virStoragePoolDestroy>`__
|
||||
|
||||
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).
|
||||
|
||||
For more in-depth details of the storage related APIs see `the storage
|
||||
management page <storage.html>`__.
|
||||
|
||||
The libvirt Drivers
|
||||
-------------------
|
||||
|
||||
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
|
||||
`virInitialize <html/libvirt-libvirt-host.html#virInitialize>`__
|
||||
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.
|
||||
|
||||
|The libvirt driver architecture|
|
||||
|
||||
The driver architecture is also used to support other virtualization
|
||||
components such as storage, storage pools, host device, networking,
|
||||
network interfaces, and network filters.
|
||||
|
||||
See the `libvirt drivers <drivers.html>`__ page for more information on
|
||||
hypervisor and storage specific drivers.
|
||||
|
||||
Not all drivers support every virtualization function possible. The
|
||||
`libvirt API support matrix <hvsupport.html>`__ lists the various
|
||||
functions and support found in each driver by the version support was
|
||||
added into libvirt.
|
||||
|
||||
Daemon and Remote Access
|
||||
------------------------
|
||||
|
||||
Access to libvirt drivers is primarily handled by the libvirtd daemon
|
||||
through the `remote <remote.html>`__ driver via an
|
||||
`RPC <internals/rpc.html>`__. Some hypervisors do support client-side
|
||||
connections and responses, such as Test, OpenVZ, VMware, 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
|
||||
`virInitialize <html/libvirt-libvirt-host.html#virInitialize>`__
|
||||
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.
|
||||
|
||||
The libvirt client `applications <apps.html>`__ use a `URI <uri.html>`__
|
||||
to obtain the ``virConnectPtr``. The ``virConnectPtr`` keeps track of
|
||||
the driver connection plus a variety of other connections (network,
|
||||
interface, storage, etc.). The ``virConnectPtr`` is then used as a
|
||||
parameter to other virtualization `functions <#Functions>`__. 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. `Migration <migration.html>`__ is
|
||||
an example of many facets of the architecture in use.
|
||||
|
||||
|The libvirt daemon and remote architecture|
|
||||
|
||||
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 ``virConnectPtr`` in order to fetch the data. The data will then be
|
||||
returned through the remote driver to the client application for
|
||||
processing.
|
||||
|
||||
If you are interested in contributing to libvirt, read the
|
||||
`FAQ <https://wiki.libvirt.org/page/FAQ>`__ and
|
||||
`hacking <hacking.html>`__ guidelines to gain an understanding of basic
|
||||
rules and guidelines. In order to add new API functionality follow the
|
||||
instructions regarding `implementing a new API in
|
||||
libvirt <api_extension.html>`__.
|
||||
|
||||
.. |first class objects exposed by the API| image:: libvirt-object-model.png
|
||||
.. |The libvirt driver architecture| image:: libvirt-driver-arch.png
|
||||
.. |The libvirt daemon and remote architecture| image:: libvirt-daemon-arch.png
|
||||
@ -32,7 +32,6 @@ docs_assets = [
|
||||
|
||||
docs_html_in_files = [
|
||||
'404',
|
||||
'api',
|
||||
'apps',
|
||||
'architecture',
|
||||
'auditlog',
|
||||
@ -107,6 +106,7 @@ docs_rst_files = [
|
||||
'aclpolkit',
|
||||
'advanced-tests',
|
||||
'api_extension',
|
||||
'api',
|
||||
'best-practices',
|
||||
'ci',
|
||||
'coding-style',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user