From nobody Thu Dec 18 23:25:17 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1615549501; cv=none; d=zohomail.com; s=zohoarc; b=T18UtHiRbuAddbzsOcuJMoIF5y/PmSks/iw2UzE1ioLm/GwlhYDNkPGHLiABe+7VhJfBpTDXEbGCqaPZlZTED78WTZYWWf+5RIm7AAD44VRlQFXMn+MozmBZ6ixkPb23/IrlEQM+NePTMLo0i/7Wj3fcyJx1FStiV+YrgzYPl3k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549501; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=UmMobhepDUjtAHrLz6ziolH5b/ghrXUGelHxZ6bww+k=; b=MCfZwWvUrp0AlxeqjTbRp3yVZ8l9ffQ9fDmlhOr3nA8HGVNBJqSHbLkyVOQ8BHFij7T+4+NlCRkReLMvLf05U/zeIW2wRc2VNH7lDpnuOSOi2/UMfjY7G69mb3povjJTRynI4tiloZr2YgD9TeJmt/aBgmz0N3biBvwArAf0kEQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1615549501843331.3927866245431; Fri, 12 Mar 2021 03:45:01 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-30-C6PaskOTOyKMc5Ldha8Lcg-1; Fri, 12 Mar 2021 06:44:58 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 5F09E1084C8C; Fri, 12 Mar 2021 11:44:53 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 360C45C1D5; Fri, 12 Mar 2021 11:44:53 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id B3C6B57DC4; Fri, 12 Mar 2021 11:44:52 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhKV9024853 for ; Fri, 12 Mar 2021 06:43:20 -0500 Received: by smtp.corp.redhat.com (Postfix) id 0F5FA9CA0; Fri, 12 Mar 2021 11:43:20 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 5DA2619813; Fri, 12 Mar 2021 11:43:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549500; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=UmMobhepDUjtAHrLz6ziolH5b/ghrXUGelHxZ6bww+k=; b=UIcrcYgZI0oRPlBfM875Sxw2AdWa05lPRUQ1CFtR81MDBVfZBg9pm55qKhNtxV4tUUYToi LdKMHFkjcGUoi6OF//4FIDdZ5kPDowRy3wVzHtTO4Pe+N8RzqVL/gIpfpfr+3iVjL0zMxH TtxuaoaPQVSycTfoLWuBpluZL0BySwg= X-MC-Unique: C6PaskOTOyKMc5Ldha8Lcg-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 3/9] docs: html.in: Convert api to rst Date: Fri, 12 Mar 2021 12:43:06 +0100 Message-Id: <929b6319e294d8820cf5215ab705e88de6dc61ac.1615549300.git.eskultet@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" 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-possib= le Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- 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 @@ - - - - -

The libvirt API concepts

- -

This page describes the main principles and architecture choices - behind the definition of the libvirt API:

- -
    - -

    Objects Exposed

    -

    As defined in the goals section, the li= bvirt - 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 libvi= rt - is likely to start using the - API by calling one of the virConnectOpen functions. You will note that those functions = take - a name argument which is actually a connection UR= I - 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 page for a full descriptions of the values allowed.

    -

    OnDevice the application obtains a - - virConnectPtr - - connection to the hypervisor it can then use it to manage the hypervis= or'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 connect= ion - (and the node or cluster where it is available).

    -

    - 3D"first -

    -

    The figure above shows the five main objects exported by the API:<= /p> -

    -

    Most objects manipulated by the library can also be represented us= ing - 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 th= is - 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 4= 122, - 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:

    - -

    Note: functions returning vir*Ptr (like the virDomainLookup functio= ns) - allocate memory which needs to be freed by the caller by the correspon= ding - 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. -

    -

    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 - - 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 architectu= re - depending on how libvirt is configured to be built.

    -

    - 3D"The -

    -

    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 page for more - information on hypervisor and storage specific drivers.

    -

    Not all drivers support every virtualization function possible. - The libvirt API support matrix 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 driver via an - RPC. 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 - - 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 use a - URI 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. 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 - is an example of many facets of the architecture in use.

    - -

    - 3D"The -

    -

    - The key takeaway from the above diagram is that there is a remote driv= er - 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 wi= ll - then be returned through the remote driver to the client application - for processing. -

    -

    If you are interested in contributing to libvirt, read the - FAQ and - hacking guidelines to gain an understandi= ng - of basic rules and guidelines. In order to add new API functionality - follow the instructions regarding - implementing a new API in libvirt. -

    - - - 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +The libvirt API concepts +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 `__, 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 `__. You will +note that those functions take a name argument which is actually a +`connection URI `__ 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 `__ +page for a full descriptions of the values allowed. + +OnDevice the application obtains a +`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 `__ + + Represents the connection to a hypervisor. Use one of the + `virConnectOpen `__ + functions to obtain connection to the hypervisor which is then used + as a parameter to other connection API's. + +- `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 `__ + lists all the domains for the hypervisor. + +- `virNetworkPtr `__ + + Represents one network either active or defined (i.e. existing as + permanent config file and storage but not currently activated). The + function + `virConnectListAllNetworks `__ + lists all the virtualization networks for the hypervisor. + +- `virStorageVolPtr `= __ + + Represents one storage volume generally used as a block device + available to one of the domains. The function + `virStorageVolLookupByPath `__ + finds the storage volume object based on its path on the node. + +- `virStoragePoolPtr `__ + + Represents a storage pool, which is a logical area used to allocate + and store storage volumes. The function + `virConnectListAllStoragePools `__ + lists all of the virtualization storage pools on the hypervisor. The + function + `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 `__, 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 `__ + - `virDomainLookupByName `__ + - `virDomainLookupByUUID `__ + - `virDomainLookupByUUIDString `__ + +- **Enumeration** [virConnectList..., virConnectNumOf...] + + Used to enumerate a set of object available to a given hypervisor + connection such as: + + - `virConnectListDomains `__ + - `virConnectNumOfDomains `__ + - `virConnectListNetworks `__ + - `virConnectListStoragePools `__ + +- **Description** [...GetInfo] + + Generic accessor providing a set of generic information about an + object, such as: + + - `virNodeGetInfo `__ + - `virDomainGetInfo `__ + - `virStoragePoolGetInfo `__ + - `virStorageVolGetInfo `__ + +- **Accessors** [...Get..., ...Set...] + + Specific accessors used to query or modify data for the given object, + such as: + + - `virConnectGetType `__ + - `virDomainGetMaxMemory `__ + - `virDomainSetMemory `__ + - `virDomainGetVcpus `__ + - `virStoragePoolSetAutostart `__ + - `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 `= __ + - `virDomainCreateXML `__ + - `virNetworkCreate `__ + - `virNetworkCreateXML `__ + +- **Destruction** [...Destroy] + + Used to shutdown or deactivate and destroy objects, such as: + + - `virDomainDestroy `__ + - `virNetworkDestroy `__ + - `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 `__. + +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 `__ +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 `__ page for more information on +hypervisor and storage specific drivers. + +Not all drivers support every virtualization function possible. The +`libvirt API support matrix `__ 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 `__ driver via an +`RPC `__. 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 `__ +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 `__ use a `URI `__ +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 `__ 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 `__ and +`hacking `__ 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 `__. + +.. |first class objects exposed by the API| image:: libvirt-object-model.p= ng +.. |The libvirt driver architecture| image:: libvirt-driver-arch.png +.. |The libvirt daemon and remote architecture| image:: libvirt-daemon-arc= h.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 =3D [ =20 docs_html_in_files =3D [ '404', - 'api', 'apps', 'architecture', 'auditlog', @@ -107,6 +106,7 @@ docs_rst_files =3D [ 'aclpolkit', 'advanced-tests', 'api_extension', + 'api', 'best-practices', 'ci', 'coding-style', --=20 2.29.2