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@xxxxxxxxxx> --- docs/api.html.in | 380 ----------------------------------------------- docs/api.rst | 265 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 266 insertions(+), 381 deletions(-) delete mode 100644 docs/api.html.in create mode 100644 docs/api.rst diff --git a/docs/api.html.in b/docs/api.html.in deleted file mode 100644 index 4bff037d48..0000000000 --- a/docs/api.html.in +++ /dev/null @@ -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> diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000000..a8f527e197 --- /dev/null +++ b/docs/api.rst @@ -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 diff --git a/docs/meson.build b/docs/meson.build index b031bd6717..942cce6fdc 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -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', -- 2.29.2
