[libvirt PATCH 0/9] docs: Convert html.in to rst (volume 1)
'#itsfriday' Erik Skultety (9): docs: html.in: Convert aclpolkit to rst docs: html.in: Convert api_extension to rst docs: html.in: Convert api to rst docs: html.in: Convert apps to rst docs: html.in: Convert architecture to rst docs: html.in: Convert auditlog to rst docs: html.in: Convert auth to rst docs: html.in: Convert bindings to rst docs: html.in: Convert 'compiling' to rst docs/aclpolkit.html.in | 523 ------------------------------------- docs/aclpolkit.rst | 310 ++++++++++++++++++++++ docs/api.html.in | 380 --------------------------- docs/api.rst | 265 +++++++++++++++++++ docs/api_extension.html.in | 376 -------------------------- docs/api_extension.rst | 291 +++++++++++++++++++++ docs/apps.html.in | 488 ---------------------------------- docs/apps.rst | 348 ++++++++++++++++++++++++ docs/architecture.html.in | 82 ------ docs/architecture.rst | 83 ++++++ docs/auditlog.html.in | 375 -------------------------- docs/auditlog.rst | 321 +++++++++++++++++++++++ docs/auth.html.in | 368 -------------------------- docs/auth.rst | 343 ++++++++++++++++++++++++ docs/bindings.html.in | 101 ------- docs/bindings.rst | 62 +++++ docs/compiling.html.in | 115 -------- docs/compiling.rst | 95 +++++++ docs/meson.build | 18 +- 19 files changed, 2127 insertions(+), 2817 deletions(-) delete mode 100644 docs/aclpolkit.html.in create mode 100644 docs/aclpolkit.rst delete mode 100644 docs/api.html.in create mode 100644 docs/api.rst delete mode 100644 docs/api_extension.html.in create mode 100644 docs/api_extension.rst delete mode 100644 docs/apps.html.in create mode 100644 docs/apps.rst delete mode 100644 docs/architecture.html.in create mode 100644 docs/architecture.rst delete mode 100644 docs/auditlog.html.in create mode 100644 docs/auditlog.rst delete mode 100644 docs/auth.html.in create mode 100644 docs/auth.rst delete mode 100644 docs/bindings.html.in create mode 100644 docs/bindings.rst delete mode 100644 docs/compiling.html.in create mode 100644 docs/compiling.rst -- 2.29.2
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/aclpolkit.html.in | 523 ----------------------------------------- docs/aclpolkit.rst | 310 ++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 311 insertions(+), 524 deletions(-) delete mode 100644 docs/aclpolkit.html.in create mode 100644 docs/aclpolkit.rst diff --git a/docs/aclpolkit.html.in b/docs/aclpolkit.html.in deleted file mode 100644 index a82001187e..0000000000 --- a/docs/aclpolkit.html.in +++ /dev/null @@ -1,523 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Polkit access control</h1> - - <p> - Libvirt's client <a href="acl.html">access control framework</a> allows - administrators to setup fine grained permission rules across client users, - managed objects and API operations. This allows client connections - to be locked down to a minimal set of privileges. The polkit driver - provides a simple implementation of the access control framework. - </p> - - <ul id="toc"></ul> - - <h2><a id="intro">Introduction</a></h2> - - <p> - A default install of libvirt will typically use - <a href="https://www.freedesktop.org/wiki/Software/polkit/">polkit</a> - to authenticate the initial user connection to libvirtd. This is a - very coarse grained check though, either allowing full read-write - access to all APIs, or just read-only access. The polkit access - control driver in libvirt builds on this capability to allow for - fine grained control over the operations a user may perform on an - object. - </p> - - <h2><a id="perms">Permission names</a></h2> - - <p> - The libvirt <a href="acl.html#perms">object names and permission names</a> - are mapped onto polkit action names using the simple pattern: - </p> - - <pre>org.libvirt.api.$object.$permission -</pre> - - <p> - The only caveat is that any underscore characters in the - object or permission names are converted to hyphens. So, - for example, the <code>search_storage_vols</code> permission - on the <code>storage_pool</code> object maps to the polkit - action: - </p> - <pre>org.libvirt.api.storage-pool.search-storage-vols -</pre> - - <p> - The default policy for any permission which corresponds to - a "read only" operation, is to allow access. All other - permissions default to deny access. - </p> - - <h2><a id="attrs">Object identity attributes</a></h2> - - <p> - To allow polkit authorization rules to be written to match - against individual object instances, libvirt provides a number - of authorization detail attributes when performing a permission - check. The set of attributes varies according to the type - of object being checked - </p> - - <h3><a id="object_connect">virConnectPtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - </tbody> - </table> - - <h3><a id="object_domain">virDomainPtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - <tr> - <td>domain_name</td> - <td>Name of the domain, unique to the local host</td> - </tr> - <tr> - <td>domain_uuid</td> - <td>UUID of the domain, globally unique</td> - </tr> - </tbody> - </table> - - <h3><a id="object_interface">virInterfacePtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - <tr> - <td>interface_name</td> - <td>Name of the network interface, unique to the local host</td> - </tr> - <tr> - <td>interface_macaddr</td> - <td>MAC address of the network interface, not unique</td> - </tr> - </tbody> - </table> - - <h3><a id="object_network">virNetworkPtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - <tr> - <td>network_name</td> - <td>Name of the network, unique to the local host</td> - </tr> - <tr> - <td>network_uuid</td> - <td>UUID of the network, globally unique</td> - </tr> - </tbody> - </table> - - <h3><a id="object_node_device">virNodeDevicePtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - <tr> - <td>node_device_name</td> - <td>Name of the node device, unique to the local host</td> - </tr> - </tbody> - </table> - - <h3><a id="object_nwfilter">virNWFilterPtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - <tr> - <td>nwfilter_name</td> - <td>Name of the network filter, unique to the local host</td> - </tr> - <tr> - <td>nwfilter_uuid</td> - <td>UUID of the network filter, globally unique</td> - </tr> - </tbody> - </table> - - <h3><a id="object_secret">virSecretPtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - <tr> - <td>secret_uuid</td> - <td>UUID of the secret, globally unique</td> - </tr> - <tr> - <td>secret_usage_volume</td> - <td>Name of the associated volume, if any</td> - </tr> - <tr> - <td>secret_usage_ceph</td> - <td>Name of the associated Ceph server, if any</td> - </tr> - <tr> - <td>secret_usage_target</td> - <td>Name of the associated iSCSI target, if any</td> - </tr> - <tr> - <td>secret_usage_name</td> - <td>Name of the associated TLS secret, if any</td> - </tr> - </tbody> - </table> - - <h3><a id="object_storage_pool">virStoragePoolPtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - <tr> - <td>pool_name</td> - <td>Name of the storage pool, unique to the local host</td> - </tr> - <tr> - <td>pool_uuid</td> - <td>UUID of the storage pool, globally unique</td> - </tr> - </tbody> - </table> - - <h3><a id="object_storage_vol">virStorageVolPtr</a></h3> - <table> - <thead> - <tr> - <th>Attribute</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>connect_driver</td> - <td>Name of the libvirt connection driver</td> - </tr> - <tr> - <td>pool_name</td> - <td>Name of the storage pool, unique to the local host</td> - </tr> - <tr> - <td>pool_uuid</td> - <td>UUID of the storage pool, globally unique</td> - </tr> - <tr> - <td>vol_name</td> - <td>Name of the storage volume, unique to the pool</td> - </tr> - <tr> - <td>vol_key</td> - <td>Key of the storage volume, globally unique</td> - </tr> - </tbody> - </table> - - <h2><a id="connect_driver">Hypervisor Driver connect_driver</a></h2> - <p> - The <code>connect_driver</code> parameter describes the - client's <a href="remote.html">remote Connection Driver</a> - name based on the <a href="uri.html">URI</a> used for the - connection. - </p> - <p> - <span class="since">Since 4.1.0</span>, when calling an API - outside the scope of the primary connection driver, the - primary driver will attempt to open a secondary connection - to the specific API driver in order to process the API. For - example, when hypervisor domain processing needs to make an - API call within the storage driver or the network filter driver - an attempt to open a connection to the "storage" or "nwfilter" - driver will be made. Similarly, a "storage" primary connection - may need to create a connection to the "secret" driver in order - to process secrets for the API. If successful, then calls to - those API's will occur in the <code>connect_driver</code> context - of the secondary connection driver rather than in the context of - the primary driver. This affects the <code>connect_driver</code> - returned from rule generation from the <code>action.loookup</code> - function. The following table provides a list of the various - connection drivers and the <code>connect_driver</code> name - used by each regardless of primary or secondary connection. - The access denied error message from libvirt will list the - connection driver by name that denied the access. - </p> - - <h3><a id="object_connect_driver">Connection Driver Name</a></h3> - <table> - <thead> - <tr> - <th>Connection Driver</th> - <th><code>connect_driver</code> name</th> - </tr> - </thead> - <tbody> - <tr> - <td>bhyve</td> - <td>bhyve</td> - </tr> - <tr> - <td>esx</td> - <td>ESX</td> - </tr> - <tr> - <td>hyperv</td> - <td>Hyper-V</td> - </tr> - <tr> - <td>interface</td> - <td>interface</td> - </tr> - <tr> - <td>xen</td> - <td>Xen</td> - </tr> - <tr> - <td>lxc</td> - <td>LXC</td> - </tr> - <tr> - <td>network</td> - <td>network</td> - </tr> - <tr> - <td>nodedev</td> - <td>nodedev</td> - </tr> - <tr> - <td>nwfilter</td> - <td>NWFilter</td> - </tr> - <tr> - <td>openvz</td> - <td>OPENVZ</td> - </tr> - <tr> - <td>qemu</td> - <td>QEMU</td> - </tr> - <tr> - <td>secret</td> - <td>secret</td> - </tr> - <tr> - <td>storage</td> - <td>storage</td> - </tr> - <tr> - <td>vbox</td> - <td>VBOX</td> - </tr> - <tr> - <td>vmware</td> - <td>VMWARE</td> - </tr> - <tr> - <td>vz</td> - <td>vz</td> - </tr> - </tbody> - </table> - - - <h2><a id="user">User identity attributes</a></h2> - - <p> - At this point in time, the only attribute provided by - libvirt to identify the user invoking the operation - is the PID of the client program. This means that the - polkit access control driver is only useful if connections - to libvirt are restricted to its UNIX domain socket. If - connections are being made to a TCP socket, no identifying - information is available and access will be denied. - Also note that if the client is connecting via an SSH - tunnel, it is the local SSH user that will be identified. - In future versions, it is expected that more information - about the client user will be provided, including the - SASL / Kerberos username and/or x509 distinguished - name obtained from the authentication provider in use. - </p> - - - <h2><a id="checks">Writing access control policies</a></h2> - - <p> - If using versions of polkit prior to 0.106 then it is only - possible to validate (user, permission) pairs via the <code>.pkla</code> - files. Fully validation of the (user, permission, object) triple - requires the new JavaScript <code>.rules</code> support that - was introduced in version 0.106. The latter is what will be - described here. - </p> - - <p> - Libvirt does not ship any rules files by default. It merely - provides a definition of the default behaviour for each - action (permission). As noted earlier, permissions which - correspond to read-only operations in libvirt will be allowed - to all users by default; everything else is denied by default. - Defining custom rules requires creation of a file in the - <code>/etc/polkit-1/rules.d</code> directory with a name - chosen by the administrator (<code>100-libvirt-acl.rules</code> - would be a reasonable choice). See the <code>polkit(8)</code> - manual page for a description of how to write these files - in general. The key idea is to create a file containing - something like - </p> - - <pre> -polkit.addRule(function(action, subject) { - ....logic to check 'action' and 'subject'... -}); - </pre> - - <p> - In this code snippet above, the <code>action</code> object - instance will represent the libvirt permission being checked - along with identifying attributes for the object it is being - applied to. The <code>subject</code> meanwhile will identify - the libvirt client app (with the caveat above about it only - dealing with local clients connected via the UNIX socket). - On the <code>action</code> object, the permission name is - accessible via the <code>id</code> attribute, while the - object identifying attributes are exposed via the - <code>lookup</code> method. - </p> - - <p> - See - <a href="https://gitlab.com/libvirt/libvirt/-/tree/master/examples/polkit">source code</a> - for a more complex example. - </p> - - <h3><a id="exconnect">Example: restricting ability to connect to drivers</a></h3> - - <p> - Consider a local user <code>berrange</code> - who has been granted permission to connect to libvirt in - full read-write mode. The goal is to only allow them to - use the <code>QEMU</code> driver and not the Xen or LXC - drivers which are also available in libvirtd. - To achieve this we need to write a rule which checks - whether the <code>connect_driver</code> attribute - is <code>QEMU</code>, and match on an action - name of <code>org.libvirt.api.connect.getattr</code>. Using - the javascript rules format, this ends up written as - </p> - - <pre> -polkit.addRule(function(action, subject) { - if (action.id == "org.libvirt.api.connect.getattr" && - subject.user == "berrange") { - if (action.lookup("connect_driver") == 'QEMU') { - return polkit.Result.YES; - } else { - return polkit.Result.NO; - } - } -}); - </pre> - - <h3><a id="exdomain">Example: restricting access to a single domain</a></h3> - - <p> - Consider a local user <code>berrange</code> - who has been granted permission to connect to libvirt in - full read-write mode. The goal is to only allow them to - see the domain called <code>demo</code> on the LXC driver. - To achieve this we need to write a rule which checks - whether the <code>connect_driver</code> attribute - is <code>LXC</code> and the <code>domain_name</code> - attribute is <code>demo</code>, and match on an action - name of <code>org.libvirt.api.domain.getattr</code>. Using - the javascript rules format, this ends up written as - </p> - - <pre> -polkit.addRule(function(action, subject) { - if (action.id == "org.libvirt.api.domain.getattr" && - subject.user == "berrange") { - if (action.lookup("connect_driver") == 'LXC' && - action.lookup("domain_name") == 'demo') { - return polkit.Result.YES; - } else { - return polkit.Result.NO; - } - } -}); - </pre> - </body> -</html> diff --git a/docs/aclpolkit.rst b/docs/aclpolkit.rst new file mode 100644 index 0000000000..09e5d9ea27 --- /dev/null +++ b/docs/aclpolkit.rst @@ -0,0 +1,310 @@ +.. role:: since + +===================== +Polkit access control +===================== + +Libvirt's client `access control framework <acl.html>`__ allows +administrators to setup fine grained permission rules across client +users, managed objects and API operations. This allows client +connections to be locked down to a minimal set of privileges. The polkit +driver provides a simple implementation of the access control framework. + +.. contents:: + +Introduction +------------ + +A default install of libvirt will typically use +`polkit <https://www.freedesktop.org/wiki/Software/polkit/>`__ to +authenticate the initial user connection to libvirtd. This is a very +coarse grained check though, either allowing full read-write access to +all APIs, or just read-only access. The polkit access control driver in +libvirt builds on this capability to allow for fine grained control over +the operations a user may perform on an object. + +Permission names +---------------- + +The libvirt `object names and permission names <acl.html#perms>`__ are +mapped onto polkit action names using the simple pattern: + +:: + + org.libvirt.api.$object.$permission + +The only caveat is that any underscore characters in the object or +permission names are converted to hyphens. So, for example, the +``search_storage_vols`` permission on the ``storage_pool`` object maps +to the polkit action: + +:: + + org.libvirt.api.storage-pool.search-storage-vols + +The default policy for any permission which corresponds to a "read only" +operation, is to allow access. All other permissions default to deny +access. + +Object identity attributes +-------------------------- + +To allow polkit authorization rules to be written to match against +individual object instances, libvirt provides a number of authorization +detail attributes when performing a permission check. The set of +attributes varies according to the type of object being checked + +virConnectPtr +~~~~~~~~~~~~~ + +============== ===================================== +Attribute Description +============== ===================================== +connect_driver Name of the libvirt connection driver +============== ===================================== + +virDomainPtr +~~~~~~~~~~~~ + +============== ============================================ +Attribute Description +============== ============================================ +connect_driver Name of the libvirt connection driver +domain_name Name of the domain, unique to the local host +domain_uuid UUID of the domain, globally unique +============== ============================================ + +virInterfacePtr +~~~~~~~~~~~~~~~ + ++-------------------+---------------------------------------------------------+ +| Attribute | Description | ++===================+=========================================================+ +| connect_driver | Name of the libvirt connection driver | ++-------------------+---------------------------------------------------------+ +| interface_name | Name of the network interface, unique to the local host | ++-------------------+---------------------------------------------------------+ +| interface_macaddr | MAC address of the network interface, not unique | ++-------------------+---------------------------------------------------------+ + +virNetworkPtr +~~~~~~~~~~~~~ + +============== ============================================= +Attribute Description +============== ============================================= +connect_driver Name of the libvirt connection driver +network_name Name of the network, unique to the local host +network_uuid UUID of the network, globally unique +============== ============================================= + +virNodeDevicePtr +~~~~~~~~~~~~~~~~ + +================ ================================================= +Attribute Description +================ ================================================= +connect_driver Name of the libvirt connection driver +node_device_name Name of the node device, unique to the local host +================ ================================================= + +virNWFilterPtr +~~~~~~~~~~~~~~ + +============== ==================================================== +Attribute Description +============== ==================================================== +connect_driver Name of the libvirt connection driver +nwfilter_name Name of the network filter, unique to the local host +nwfilter_uuid UUID of the network filter, globally unique +============== ==================================================== + +virSecretPtr +~~~~~~~~~~~~ + +=================== =========================================== +Attribute Description +=================== =========================================== +connect_driver Name of the libvirt connection driver +secret_uuid UUID of the secret, globally unique +secret_usage_volume Name of the associated volume, if any +secret_usage_ceph Name of the associated Ceph server, if any +secret_usage_target Name of the associated iSCSI target, if any +secret_usage_name Name of the associated TLS secret, if any +=================== =========================================== + +virStoragePoolPtr +~~~~~~~~~~~~~~~~~ + +============== ================================================== +Attribute Description +============== ================================================== +connect_driver Name of the libvirt connection driver +pool_name Name of the storage pool, unique to the local host +pool_uuid UUID of the storage pool, globally unique +============== ================================================== + +virStorageVolPtr +~~~~~~~~~~~~~~~~ + +============== ================================================== +Attribute Description +============== ================================================== +connect_driver Name of the libvirt connection driver +pool_name Name of the storage pool, unique to the local host +pool_uuid UUID of the storage pool, globally unique +vol_name Name of the storage volume, unique to the pool +vol_key Key of the storage volume, globally unique +============== ================================================== + +Hypervisor Driver connect_driver +-------------------------------- + +The ``connect_driver`` parameter describes the client's `remote +Connection Driver <remote.html>`__ name based on the `URI <uri.html>`__ +used for the connection. + +:since:`Since 4.1.0`, when calling an API outside the scope of the primary +connection driver, the primary driver will attempt to open a secondary +connection to the specific API driver in order to process the API. For +example, when hypervisor domain processing needs to make an API call +within the storage driver or the network filter driver an attempt to +open a connection to the "storage" or "nwfilter" driver will be made. +Similarly, a "storage" primary connection may need to create a +connection to the "secret" driver in order to process secrets for the +API. If successful, then calls to those API's will occur in the +``connect_driver`` context of the secondary connection driver rather +than in the context of the primary driver. This affects the +``connect_driver`` returned from rule generation from the +``action.loookup`` function. The following table provides a list of the +various connection drivers and the ``connect_driver`` name used by each +regardless of primary or secondary connection. The access denied error +message from libvirt will list the connection driver by name that denied +the access. + +Connection Driver Name +~~~~~~~~~~~~~~~~~~~~~~ + +================= ======================= +Connection Driver ``connect_driver`` name +================= ======================= +bhyve bhyve +esx ESX +hyperv Hyper-V +interface interface +xen Xen +lxc LXC +network network +nodedev nodedev +nwfilter NWFilter +openvz OPENVZ +qemu QEMU +secret secret +storage storage +vbox VBOX +vmware VMWARE +vz vz +================= ======================= + +User identity attributes +------------------------ + +At this point in time, the only attribute provided by libvirt to +identify the user invoking the operation is the PID of the client +program. This means that the polkit access control driver is only useful +if connections to libvirt are restricted to its UNIX domain socket. If +connections are being made to a TCP socket, no identifying information +is available and access will be denied. Also note that if the client is +connecting via an SSH tunnel, it is the local SSH user that will be +identified. In future versions, it is expected that more information +about the client user will be provided, including the SASL / Kerberos +username and/or x509 distinguished name obtained from the authentication +provider in use. + +Writing access control policies +------------------------------- + +If using versions of polkit prior to 0.106 then it is only possible to +validate (user, permission) pairs via the ``.pkla`` files. Fully +validation of the (user, permission, object) triple requires the new +JavaScript ``.rules`` support that was introduced in version 0.106. The +latter is what will be described here. + +Libvirt does not ship any rules files by default. It merely provides a +definition of the default behaviour for each action (permission). As +noted earlier, permissions which correspond to read-only operations in +libvirt will be allowed to all users by default; everything else is +denied by default. Defining custom rules requires creation of a file in +the ``/etc/polkit-1/rules.d`` directory with a name chosen by the +administrator (``100-libvirt-acl.rules`` would be a reasonable choice). +See the ``polkit(8)`` manual page for a description of how to write +these files in general. The key idea is to create a file containing +something like + +:: + + polkit.addRule(function(action, subject) { + ....logic to check 'action' and 'subject'... + }); + +In this code snippet above, the ``action`` object instance will +represent the libvirt permission being checked along with identifying +attributes for the object it is being applied to. The ``subject`` +meanwhile will identify the libvirt client app (with the caveat above +about it only dealing with local clients connected via the UNIX socket). +On the ``action`` object, the permission name is accessible via the +``id`` attribute, while the object identifying attributes are exposed +via the ``lookup`` method. + +See `source +code <https://gitlab.com/libvirt/libvirt/-/tree/master/examples/polkit>`__ +for a more complex example. + +Example: restricting ability to connect to drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Consider a local user ``berrange`` who has been granted permission to +connect to libvirt in full read-write mode. The goal is to only allow +them to use the ``QEMU`` driver and not the Xen or LXC drivers which are +also available in libvirtd. To achieve this we need to write a rule +which checks whether the ``connect_driver`` attribute is ``QEMU``, and +match on an action name of ``org.libvirt.api.connect.getattr``. Using +the javascript rules format, this ends up written as + +:: + + polkit.addRule(function(action, subject) { + if (action.id == "org.libvirt.api.connect.getattr" && + subject.user == "berrange") { + if (action.lookup("connect_driver") == 'QEMU') { + return polkit.Result.YES; + } else { + return polkit.Result.NO; + } + } + }); + +Example: restricting access to a single domain +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Consider a local user ``berrange`` who has been granted permission to +connect to libvirt in full read-write mode. The goal is to only allow +them to see the domain called ``demo`` on the LXC driver. To achieve +this we need to write a rule which checks whether the ``connect_driver`` +attribute is ``LXC`` and the ``domain_name`` attribute is ``demo``, and +match on an action name of ``org.libvirt.api.domain.getattr``. Using the +javascript rules format, this ends up written as + +:: + + polkit.addRule(function(action, subject) { + if (action.id == "org.libvirt.api.domain.getattr" && + subject.user == "berrange") { + if (action.lookup("connect_driver") == 'LXC' && + action.lookup("domain_name") == 'demo') { + return polkit.Result.YES; + } else { + return polkit.Result.NO; + } + } + }); diff --git a/docs/meson.build b/docs/meson.build index 5536005125..0f402bbf6a 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'aclpolkit', 'api_extension', 'api', 'apps', @@ -106,6 +105,7 @@ docs_html_in_files = [ ] docs_rst_files = [ + 'aclpolkit', 'advanced-tests', 'best-practices', 'ci', -- 2.29.2
On Fri, Mar 12, 2021 at 12:43:04 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/aclpolkit.html.in | 523 ----------------------------------------- docs/aclpolkit.rst | 310 ++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 311 insertions(+), 524 deletions(-) delete mode 100644 docs/aclpolkit.html.in create mode 100644 docs/aclpolkit.rst
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/api_extension.html.in | 376 ------------------------------------- docs/api_extension.rst | 291 ++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 292 insertions(+), 377 deletions(-) delete mode 100644 docs/api_extension.html.in create mode 100644 docs/api_extension.rst diff --git a/docs/api_extension.html.in b/docs/api_extension.html.in deleted file mode 100644 index e44c1c37b0..0000000000 --- a/docs/api_extension.html.in +++ /dev/null @@ -1,376 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Implementing a new API in Libvirt</h1> - - <ul id="toc"></ul> - - <p> - This document walks you through the process of implementing a new - API in libvirt. Remember that new API consists of any new public - functions, as well as the addition of flags or extensions of XML used by - existing functions. - </p> - - <p> - Before you begin coding, it is critical that you propose your - changes on the libvirt mailing list and get feedback on your ideas to - make sure what you're proposing fits with the general direction of the - project. Even before doing a proof of concept implementation, send an - email giving an overview of the functionality you think should be - added to libvirt. Someone may already be working on the feature you - want. Also, recognize that everything you write is likely to undergo - significant rework as you discuss it with the other developers, so - don't wait too long before getting feedback. - </p> - - <p> - Adding a new API to libvirt is not difficult, but there are quite a - few steps. This document assumes that you are familiar with C - programming and have checked out the libvirt code from the source code - repository and successfully built the existing tree. Instructions on - how to check out and build the code can be found at: - </p> - - <p> - <a href="https://libvirt.org/downloads.html">https://libvirt.org/downloads.html</a> - </p> - - <p> - Once you have a working development environment, the steps to create a - new API are: - </p> - <ol> - <li>define the public API</li> - <li>define the internal driver API</li> - <li>implement the public API</li> - <li>implement the remote protocol: - <ol> - <li>define the wire protocol format</li> - <li>implement the RPC client</li> - <li>implement the server side dispatcher</li> - </ol> - </li> - <li>use new API where appropriate in drivers</li> - <li>add virsh support</li> - <li>add common handling for new API</li> - <li>for each driver that can support the new API: - <ol> - <li>add prerequisite support</li> - <li>fully implement new API</li> - </ol> - </li> - </ol> - - <p> - It is, of course, possible to implement the pieces in any order, but - if the development tasks are completed in the order listed, the code - will compile after each step. Given the number of changes required, - verification after each step is highly recommended. - </p> - - <p> - Submit new code in the form of one patch per step. That's not to say - submit patches before you have working functionality--get the whole thing - working and make sure you're happy with it. Then use git to break the - changes into pieces so you don't drop a big blob of code on the - mailing list in one go. Also, you should follow the upstream tree, and - rebase your series to adapt your patches to work with any other changes - that were accepted upstream during your development. - </p> - - <p> - Don't mix anything else into the patches you submit. The patches - should be the minimal changes required to implement the functionality - you're adding. If you notice a bug in unrelated code (i.e., code you - don't have to touch to implement your API change) during development, - create a patch that just addresses that bug and submit it - separately. - </p> - - <h2><a id='publicapi'>Defining the public API</a></h2> - - <p>The first task is to define the public API. If the new API - involves an XML extension, you have to enhance the RelaxNG - schema and document the new elements or attributes:</p> - - <p><code> - docs/schemas/domaincommon.rng<br/> - docs/formatdomain.html.in - </code></p> - - <p>If the API extension involves a new function, you have to add a - declaration in the public header, and arrange to export the - function name (symbol) so other programs can link against the - libvirt library and call the new function:</p> - - <p><code> - include/libvirt/libvirt-$MODULE.h.in - src/libvirt_public.syms - </code></p> - - <p> - Please consult our - <a href="coding-style.html#xml-element-and-attribute-naming">coding style</a> - guide on elements and attribute names. - </p> - - <p> - This task is in many ways the most important to get right, since once - the API has been committed to the repository, it's libvirt's policy - never to change it. Mistakes in the implementation are bugs that you - can fix. Make a mistake in the API definition and you're stuck with - it, so think carefully about the interface and don't be afraid to - rework it as you go through the process of implementing it. - </p> - - <h2><a id='internalapi'>Defining the internal API</a></h2> - - <p> - Each public API call is associated with a driver, such as a host - virtualization driver, a network virtualization driver, a storage - virtualization driver, a state driver, or a device monitor. Adding - the internal API is ordinarily a matter of adding a new member to the - struct representing one of these drivers. - </p> - - <p> - Of course, it's possible that the new API will involve the creation of - an entirely new driver type, in which case the changes will include the - creation of a new struct type to represent the new driver type. - </p> - - <p>The driver structs are defined in:</p> - - <p><code>src/driver-$MODULE.h</code></p> - - <p> - To define the internal API, first typedef the driver function - prototype and then add a new field for it to the relevant driver - struct. Then, update all existing instances of the driver to - provide a <code>NULL</code> stub for the new function. - </p> - - <h2><a id='implpublic'>Implementing the public API</a></h2> - - <p> - Implementing the public API is largely a formality in which we wire up - public API to the internal driver API. The public API implementation - takes care of some basic validity checks before passing control to the - driver implementation. In RFC 2119 vocabulary, this function: - </p> - - <ol class="ordinarylist"> - <li>SHOULD log a message with VIR_DEBUG() indicating that it is - being called and its parameters;</li> - <li>MUST call virResetLastError();</li> - <li>SHOULD confirm that the connection is valid with - virCheckConnectReturn() or virCheckConnectGoto();</li> - <li><strong>SECURITY: If the API requires a connection with write - privileges, MUST confirm that the connection flags do not - indicate that the connection is read-only with - virCheckReadOnlyGoto();</strong></li> - <li>SHOULD do basic validation of the parameters that are being - passed in, using helpers like virCheckNonNullArgGoto();</li> - <li>MUST confirm that the driver for this connection exists and that - it implements this function;</li> - <li>MUST call the internal API;</li> - <li>SHOULD log a message with VIR_DEBUG() indicating that it is - returning, its return value, and status.</li> - <li>MUST return status to the caller.</li> - </ol> - - <p>The public API calls are implemented in:</p> - - <p><code>src/libvirt-$MODULE.c</code></p> - - <h2><a id='remoteproto'>Implementing the remote protocol</a></h2> - - <p> - Implementing the remote protocol is essentially a - straightforward exercise which is probably most easily - understood by referring to the existing code. - </p> - - <h3><a id='wireproto'>Defining the wire protocol format</a></h3> - - <p> - Defining the wire protocol involves making additions to: - </p> - - <p><code>src/remote/remote_protocol.x</code></p> - - <p> - First, create two new structs for each new function that you're adding - to the API. One struct describes the parameters to be passed to the - remote function, and a second struct describes the value returned by - the remote function. The one exception to this rule is that functions - that return only 0 or -1 for status do not require a struct for returned - data. - </p> - - <p> - Second, add values to the remote_procedure enum for each new function - added to the API. - </p> - - <p> - Once these changes are in place, it's necessary to run 'make rpcgen' - in the src directory to create the .c and .h files required by the - remote protocol code. This must be done on a Linux host using the - GLibC rpcgen program. Other rpcgen versions may generate code which - results in bogus compile time warnings. This regenerates the - following files: - </p> - - <p><code> - src/remote/remote_daemon_dispatch_stubs.h - src/remote/remote_daemon_dispatch.h - src/remote/remote_daemon_dispatch.c - src/remote/remote_protocol.c - src/remote/remote_protocol.h - </code></p> - - <h3><a id='rpcclient'>Implement the RPC client</a></h3> - - <p> - Implementing the RPC client uses the rpcgen generated .h files. - The remote method calls go in: - </p> - - <p><code>src/remote/remote_driver.c</code></p> - - <p>Each remote method invocation does the following:</p> - - <ol class="ordinarylist"> - <li>locks the remote driver;</li> - <li>sets up the method arguments;</li> - <li>invokes the remote function;</li> - <li>checks the return value, if necessary;</li> - <li>extracts any returned data;</li> - <li>frees any returned data;</li> - <li>unlocks the remote driver.</li> - </ol> - - <h3><a id="serverdispatch">Implement the server side dispatcher</a></h3> - - <p> - Implementing the server side of the remote function call is simply a - matter of deserializing the parameters passed in from the remote - caller and passing them to the corresponding internal API function. - The server side dispatchers are implemented in: - </p> - - <p><code>src/remote/remote_daemon_dispatch.c</code></p> - - <p>Again, this step uses the .h files generated by make rpcgen.</p> - - <p> - After all three pieces of the remote protocol are complete, and - the generated files have been updated, it will be necessary to - update the file:</p> - - <p><code>src/remote_protocol-structs</code></p> - - <p> - This file should only have new lines added; modifications to - existing lines probably imply a backwards-incompatible API change. - </p> - - <h2><a id="internaluseapi">Use the new API internally</a></h2> - - <p> - Sometimes, a new API serves as a superset of existing API, by - adding more granularity in what can be managed. When this is - the case, it makes sense to share a common implementation by - making the older API become a trivial wrapper around the new - API, rather than duplicating the common code. This step should - not introduce any semantic differences for the old API, and is - not necessary if the new API has no relation to existing API. - </p> - - <h2><a id="virshuseapi">Expose the new API in virsh</a></h2> - - <p> - All new API should be manageable from the virsh command line - shell. This proves that the API is sufficient for the intended - purpose, and helps to identify whether the proposed API needs - slight changes for easier usage. However, remember that virsh - is used to connect to hosts running older versions of libvirtd, - so new commands should have fallbacks to an older API if - possible; implementing the virsh hooks at this point makes it - very easy to test these fallbacks. Also remember to document - virsh additions. - </p> - - <p> - A virsh command is composed of a few pieces of code. You need to - define an array of vshCmdInfo structs for each new command that - contain the help text and the command description text. You also need - an array of vshCmdOptDef structs to describe the command options. - Once you have those pieces in place you can write the function - implementing the virsh command. Finally, you need to add the new - command to the commands[] array. The following files need changes: - </p> - - <p><code> - tools/virsh-$MODULE.c<br/> - tools/virsh.pod - </code></p> - - <h2><a id="driverimpl">Implement the driver methods</a></h2> - - <p> - So, after all that, we get to the fun part. All functionality in - libvirt is implemented inside a driver. Thus, here is where you - implement whatever functionality you're adding to libvirt. You'll - either need to add additional files to the src directory or extend - files that are already there, depending on what functionality you're - adding. - </p> - - <h3><a id="commonimpl">Implement common handling</a></h3> - - <p> - If the new API is applicable to more than one driver, it may - make sense to provide some utility routines, or to factor some - of the work into the dispatcher, to avoid reimplementing the - same code in every driver. In the example code, this involved - adding a member to the virDomainDefPtr struct for mapping - between the XML API addition and the in-memory representation of - a domain, along with updating all clients to use the new member. - Up to this point, there have been no changes to existing - semantics, and the new APIs will fail unless they are used in - the same way as the older API wrappers. - </p> - - <h3><a id="drivercode">Implement driver handling</a></h3> - - <p> - The remaining patches should only touch one driver at a time. - It is possible to implement all changes for a driver in one - patch, but for review purposes it may still make sense to break - things into simpler steps. Here is where the new APIs finally - start working. - </p> - - <p> - It is always a good idea to patch the test driver in addition to the - target driver, to prove that the API can be used for more than one - driver. - </p> - - <p> - Any cleanups resulting from the changes should be added as separate - patches at the end of the series. - </p> - - <p> - Once you have working functionality, run ninja test on each patch - of the series before submitting patches. It may also be worth - writing tests for the libvirt-TCK testsuite to exercise your new API, - although those patches are not kept in the libvirt repository. - </p> - </body> -</html> diff --git a/docs/api_extension.rst b/docs/api_extension.rst new file mode 100644 index 0000000000..02b39efd82 --- /dev/null +++ b/docs/api_extension.rst @@ -0,0 +1,291 @@ +================================= +Implementing a new API in Libvirt +================================= + +.. contents:: + +This document walks you through the process of implementing a new API in +libvirt. Remember that new API consists of any new public functions, as +well as the addition of flags or extensions of XML used by existing +functions. + +Before you begin coding, it is critical that you propose your changes on +the libvirt mailing list and get feedback on your ideas to make sure +what you're proposing fits with the general direction of the project. +Even before doing a proof of concept implementation, send an email +giving an overview of the functionality you think should be added to +libvirt. Someone may already be working on the feature you want. Also, +recognize that everything you write is likely to undergo significant +rework as you discuss it with the other developers, so don't wait too +long before getting feedback. + +Adding a new API to libvirt is not difficult, but there are quite a few +steps. This document assumes that you are familiar with C programming +and have checked out the libvirt code from the source code repository +and successfully built the existing tree. Instructions on how to check +out and build the code can be found at: + +https://libvirt.org/downloads.html + +Once you have a working development environment, the steps to create a +new API are: + +#. define the public API +#. define the internal driver API +#. implement the public API +#. implement the remote protocol: + + #. define the wire protocol format + #. implement the RPC client + #. implement the server side dispatcher + +#. use new API where appropriate in drivers +#. add virsh support +#. add common handling for new API +#. for each driver that can support the new API: + + #. add prerequisite support + #. fully implement new API + +It is, of course, possible to implement the pieces in any order, but if +the development tasks are completed in the order listed, the code will +compile after each step. Given the number of changes required, +verification after each step is highly recommended. + +Submit new code in the form of one patch per step. That's not to say +submit patches before you have working functionality--get the whole +thing working and make sure you're happy with it. Then use git to break +the changes into pieces so you don't drop a big blob of code on the +mailing list in one go. Also, you should follow the upstream tree, and +rebase your series to adapt your patches to work with any other changes +that were accepted upstream during your development. + +Don't mix anything else into the patches you submit. The patches should +be the minimal changes required to implement the functionality you're +adding. If you notice a bug in unrelated code (i.e., code you don't have +to touch to implement your API change) during development, create a +patch that just addresses that bug and submit it separately. + +Defining the public API +----------------------- + +The first task is to define the public API. If the new API involves an +XML extension, you have to enhance the RelaxNG schema and document the +new elements or attributes: + +``docs/schemas/domaincommon.rng docs/formatdomain.html.in`` + +If the API extension involves a new function, you have to add a +declaration in the public header, and arrange to export the function +name (symbol) so other programs can link against the libvirt library and +call the new function: + +``include/libvirt/libvirt-$MODULE.h.in src/libvirt_public.syms`` + +Please consult our `coding +style <coding-style.html#xml-element-and-attribute-naming>`__ guide on +elements and attribute names. + +This task is in many ways the most important to get right, since once +the API has been committed to the repository, it's libvirt's policy +never to change it. Mistakes in the implementation are bugs that you can +fix. Make a mistake in the API definition and you're stuck with it, so +think carefully about the interface and don't be afraid to rework it as +you go through the process of implementing it. + +Defining the internal API +------------------------- + +Each public API call is associated with a driver, such as a host +virtualization driver, a network virtualization driver, a storage +virtualization driver, a state driver, or a device monitor. Adding the +internal API is ordinarily a matter of adding a new member to the struct +representing one of these drivers. + +Of course, it's possible that the new API will involve the creation of +an entirely new driver type, in which case the changes will include the +creation of a new struct type to represent the new driver type. + +The driver structs are defined in: + +``src/driver-$MODULE.h`` + +To define the internal API, first typedef the driver function prototype +and then add a new field for it to the relevant driver struct. Then, +update all existing instances of the driver to provide a ``NULL`` stub +for the new function. + +Implementing the public API +--------------------------- + +Implementing the public API is largely a formality in which we wire up +public API to the internal driver API. The public API implementation +takes care of some basic validity checks before passing control to the +driver implementation. In RFC 2119 vocabulary, this function: + +#. SHOULD log a message with VIR_DEBUG() indicating that it is being + called and its parameters; +#. MUST call virResetLastError(); +#. SHOULD confirm that the connection is valid with + virCheckConnectReturn() or virCheckConnectGoto(); +#. **SECURITY: If the API requires a connection with write privileges, + MUST confirm that the connection flags do not indicate that the + connection is read-only with virCheckReadOnlyGoto();** +#. SHOULD do basic validation of the parameters that are being passed + in, using helpers like virCheckNonNullArgGoto(); +#. MUST confirm that the driver for this connection exists and that it + implements this function; +#. MUST call the internal API; +#. SHOULD log a message with VIR_DEBUG() indicating that it is + returning, its return value, and status. +#. MUST return status to the caller. + +The public API calls are implemented in: + +``src/libvirt-$MODULE.c`` + +Implementing the remote protocol +-------------------------------- + +Implementing the remote protocol is essentially a straightforward +exercise which is probably most easily understood by referring to the +existing code. + +Defining the wire protocol format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Defining the wire protocol involves making additions to: + +``src/remote/remote_protocol.x`` + +First, create two new structs for each new function that you're adding +to the API. One struct describes the parameters to be passed to the +remote function, and a second struct describes the value returned by the +remote function. The one exception to this rule is that functions that +return only 0 or -1 for status do not require a struct for returned +data. + +Second, add values to the remote_procedure enum for each new function +added to the API. + +Once these changes are in place, it's necessary to run 'make rpcgen' in +the src directory to create the .c and .h files required by the remote +protocol code. This must be done on a Linux host using the GLibC rpcgen +program. Other rpcgen versions may generate code which results in bogus +compile time warnings. This regenerates the following files: + +``src/remote/remote_daemon_dispatch_stubs.h src/remote/remote_daemon_dispatch.h src/remote/remote_daemon_dispatch.c src/remote/remote_protocol.c src/remote/remote_protocol.h`` + +Implement the RPC client +~~~~~~~~~~~~~~~~~~~~~~~~ + +Implementing the RPC client uses the rpcgen generated .h files. The +remote method calls go in: + +``src/remote/remote_driver.c`` + +Each remote method invocation does the following: + +#. locks the remote driver; +#. sets up the method arguments; +#. invokes the remote function; +#. checks the return value, if necessary; +#. extracts any returned data; +#. frees any returned data; +#. unlocks the remote driver. + +Implement the server side dispatcher +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Implementing the server side of the remote function call is simply a +matter of deserializing the parameters passed in from the remote caller +and passing them to the corresponding internal API function. The server +side dispatchers are implemented in: + +``src/remote/remote_daemon_dispatch.c`` + +Again, this step uses the .h files generated by make rpcgen. + +After all three pieces of the remote protocol are complete, and the +generated files have been updated, it will be necessary to update the +file: + +``src/remote_protocol-structs`` + +This file should only have new lines added; modifications to existing +lines probably imply a backwards-incompatible API change. + +Use the new API internally +-------------------------- + +Sometimes, a new API serves as a superset of existing API, by adding +more granularity in what can be managed. When this is the case, it makes +sense to share a common implementation by making the older API become a +trivial wrapper around the new API, rather than duplicating the common +code. This step should not introduce any semantic differences for the +old API, and is not necessary if the new API has no relation to existing +API. + +Expose the new API in virsh +--------------------------- + +All new API should be manageable from the virsh command line shell. This +proves that the API is sufficient for the intended purpose, and helps to +identify whether the proposed API needs slight changes for easier usage. +However, remember that virsh is used to connect to hosts running older +versions of libvirtd, so new commands should have fallbacks to an older +API if possible; implementing the virsh hooks at this point makes it +very easy to test these fallbacks. Also remember to document virsh +additions. + +A virsh command is composed of a few pieces of code. You need to define +an array of vshCmdInfo structs for each new command that contain the +help text and the command description text. You also need an array of +vshCmdOptDef structs to describe the command options. Once you have +those pieces in place you can write the function implementing the virsh +command. Finally, you need to add the new command to the commands[] +array. The following files need changes: + +``tools/virsh-$MODULE.c tools/virsh.pod`` + +Implement the driver methods +---------------------------- + +So, after all that, we get to the fun part. All functionality in libvirt +is implemented inside a driver. Thus, here is where you implement +whatever functionality you're adding to libvirt. You'll either need to +add additional files to the src directory or extend files that are +already there, depending on what functionality you're adding. + +Implement common handling +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the new API is applicable to more than one driver, it may make sense +to provide some utility routines, or to factor some of the work into the +dispatcher, to avoid reimplementing the same code in every driver. In +the example code, this involved adding a member to the virDomainDefPtr +struct for mapping between the XML API addition and the in-memory +representation of a domain, along with updating all clients to use the +new member. Up to this point, there have been no changes to existing +semantics, and the new APIs will fail unless they are used in the same +way as the older API wrappers. + +Implement driver handling +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The remaining patches should only touch one driver at a time. It is +possible to implement all changes for a driver in one patch, but for +review purposes it may still make sense to break things into simpler +steps. Here is where the new APIs finally start working. + +It is always a good idea to patch the test driver in addition to the +target driver, to prove that the API can be used for more than one +driver. + +Any cleanups resulting from the changes should be added as separate +patches at the end of the series. + +Once you have working functionality, run ninja test on each patch of the +series before submitting patches. It may also be worth writing tests for +the libvirt-TCK testsuite to exercise your new API, although those +patches are not kept in the libvirt repository. diff --git a/docs/meson.build b/docs/meson.build index 0f402bbf6a..b031bd6717 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'api_extension', 'api', 'apps', 'architecture', @@ -107,6 +106,7 @@ docs_html_in_files = [ docs_rst_files = [ 'aclpolkit', 'advanced-tests', + 'api_extension', 'best-practices', 'ci', 'coding-style', -- 2.29.2
On Fri, Mar 12, 2021 at 12:43:05 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/api_extension.html.in | 376 ------------------------------------- docs/api_extension.rst | 291 ++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 292 insertions(+), 377 deletions(-) delete mode 100644 docs/api_extension.html.in create mode 100644 docs/api_extension.rst
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
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> --- 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
On Fri, Mar 12, 2021 at 12:43:06 +0100, Erik Skultety wrote:
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> --- 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
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/apps.html.in | 488 ---------------------------------------------- docs/apps.rst | 348 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 349 insertions(+), 489 deletions(-) delete mode 100644 docs/apps.html.in create mode 100644 docs/apps.rst diff --git a/docs/apps.html.in b/docs/apps.html.in deleted file mode 100644 index bac1e36365..0000000000 --- a/docs/apps.html.in +++ /dev/null @@ -1,488 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Applications using libvirt</h1> - - <p> - This page provides an illustration of the wide variety of - applications using the libvirt management API. - </p> - - <ul id="toc"></ul> - - <h2><a id="add">Add an application</a></h2> - - <p> - To add an application not listed on this page, send a message - to the <a href="contact.html">mailing list</a>, requesting it - be added here, or simply send a patch against the documentation - in the libvirt.git docs subdirectory. - If your application uses libvirt as its API, - the following graphics are available for your website to advertise - support for libvirt: - </p> - - <p class="image"> - <img src="logos/logo-square-powered-96.png" alt="libvirt powered"/> - <img src="logos/logo-square-powered-128.png" alt="libvirt powered"/> - <img src="logos/logo-square-powered-192.png" alt="libvirt powered"/> - <img src="logos/logo-square-powered-256.png" alt="libvirt powered"/> - </p> - - <h2><a id="command">Command line tools</a></h2> - - <dl> - <dt><a href="https://libguestfs.org">guestfish</a></dt> - <dd> - Guestfish is an interactive shell and command-line tool for examining - and modifying virtual machine filesystems. It uses libvirt to find - guests and their associated disks. - </dd> - <dt>virsh</dt> - <dd> - An interactive shell, and batch scriptable tool for performing - management tasks on all libvirt managed domains, networks and - storage. This is part of the libvirt core distribution. - </dd> - <dt><a href="https://virt-manager.org/">virt-clone</a></dt> - <dd> - Allows the disk image(s) and configuration for an existing - virtual machine to be cloned to form a new virtual machine. - It automates copying of data across to new disk images, and - updates the UUID, MAC address, and name in the configuration. - </dd> - <dt><a href="https://people.redhat.com/rjones/virt-df/">virt-df</a></dt> - <dd> - Examine the utilization of each filesystem in a virtual machine - from the comfort of the host machine. This tool peeks into the - guest disks and determines how much space is used. It can cope - with common Linux filesystems and LVM volumes. - </dd> - <dt><a href="https://virt-manager.org/">virt-image</a></dt> - <dd> - Provides a way to deploy virtual appliances. It defines a - simplified portable XML format describing the pre-requisites - of a virtual machine. At time of deployment this is translated - into the domain XML format for execution under any libvirt - hypervisor meeting the pre-requisites. - </dd> - <dt><a href="https://virt-manager.org/">virt-install</a></dt> - <dd> - Provides a way to provision new virtual machines from a - OS distribution install tree. It supports provisioning from - local CD images, and the network over NFS, HTTP and FTP. - </dd> - <dt><a href="https://people.redhat.com/rjones/virt-top/">virt-top</a></dt> - <dd> - Watch the CPU, memory, network and disk utilization of all - virtual machines running on a host. - </dd> - <dt> - <a href="https://people.redhat.com/~rjones/virt-what/">virt-what</a> - </dt> - <dd> - virt-what is a shell script for detecting if the program is running - in a virtual machine. It prints out a list of facts about the - virtual machine, derived from heuristics. - </dd> - <dt><a href="https://sourceware.org/systemtap/">stap</a></dt> - <dd> - SystemTap is a tool used to gather rich information about a running - system through the use of scripts. Starting from v2.4, the front-end - application stap can use libvirt to gather data within virtual - machines. - </dd> - <dt><a href="https://github.com/pradels/vagrant-libvirt/">vagrant-libvirt</a></dt> - <dd> - Vagrant-Libvirt is a Vagrant plugin that uses libvirt to manage virtual - machines. It is a command line tool for developers that makes it very - fast and easy to deploy and re-deploy an environment of vm's. - </dd> - <dt><a href="https://github.com/virt-lightning/virt-lightning">virt-lightning</a></dt> - <dd> - Virt-Lightning uses libvirt, cloud-init and libguestfs to allow anyone - to quickly start a new VM. Very much like a container CLI, but with a - virtual machine. - </dd> - </dl> - - <h2><a id="configmgmt">Configuration Management</a></h2> - - <dl> - <dt><a href="https://wiki.lcfg.org/bin/view/LCFG/LcfgLibvirt">LCFG</a></dt> - <dd> - LCFG is a system for automatically installing and managing the - configuration of large numbers of Unix systems. It is particularly - suitable for sites with very diverse and rapidly changing - configurations. - </dd> - <dd> - The lcfg-libvirt package adds support for virtualized systems to - LCFG, with both Xen and KVM known to work. Cloning guests is - supported, as are the bridged, routed, and isolated modes for - Virtual Networking. - </dd> - </dl> - - <h2><a id="continuousintegration">Continuous Integration</a></h2> - - <dl> - <dt><a href="https://docs.buildbot.net/latest/manual/configuration/workers-libvirt.html">BuildBot</a></dt> - <dd> - BuildBot is a system to automate the compile/test cycle required - by most software projects. CVS commits trigger new builds, run on - a variety of client machines. Build status (pass/fail/etc) are - displayed on a web page or through other protocols. - </dd> - </dl> - - <dl> - <dt><a href="https://plugins.jenkins.io/libvirt-slave/">Jenkins</a></dt> - <dd> - This plugin for Jenkins adds a way to control guest domains hosted - on Xen or QEMU/KVM. You configure a Jenkins Agent, - selecting the guest domain and hypervisor. When you need to build a - job on a specific Agent, its guest domain is started, then the job is - run. When the build process is finished, the guest domain is shut - down, ready to be used again as required. - </dd> - </dl> - - <h2><a id="conversion">Conversion</a></h2> - - <dl> - <dt><a href="https://libguestfs.org/virt-p2v.1.html">virt-p2v</a></dt> - <dd> - Convert a physical machine to run on KVM. It is a LiveCD - which is booted on the machine to be converted. It collects a - little information from the user, then copies the disks over - to a remote machine and defines the XML for a domain to run - the guest. (Note this tool is included with libguestfs) - </dd> - <dt><a href="https://libguestfs.org/virt-v2v.1.html">virt-v2v</a></dt> - <dd> - virt-v2v converts guests from a foreign hypervisor to run on - KVM, managed by libvirt. It can convert guests from VMware or - Xen to run on OpenStack, oVirt (RHEV-M), or local libvirt. It - will enable VirtIO drivers in the converted guest if possible. - (Note this tool is included with libguestfs) - </dd> - <dd> - For RHEL customers of Red Hat, conversion of Windows guests is also - possible. This conversion requires some Microsoft signed pieces, - that Red Hat can provide. - </dd> - <dt><a href="https://launchpad.net/virt-goodies">vmware2libvirt</a></dt> - <dd> - Part of the <i>virt-goodies</i> package, vmware2libvirt is a python - script for migrating a vmware image to libvirt. - </dd> - </dl> - - <h2><a id="desktop">Desktop applications</a></h2> - - <dl> - <dt><a href="https://virt-manager.org/">virt-manager</a></dt> - <dd> - A general purpose desktop management tool, able to manage - virtual machines across both local and remotely accessed - hypervisors. It is targeted at home and small office usage - up to managing 10-20 hosts and their VMs. - </dd> - <dt><a href="https://virt-manager.org/">virt-viewer</a></dt> - <dd> - A lightweight tool for accessing the graphical console - associated with a virtual machine. It can securely connect - to remote consoles supporting the VNC protocol. Also provides - an optional mozilla browser plugin. - </dd> - <dt><a href="https://f1ash.github.io/qt-virt-manager">qt-virt-manager</a></dt> - <dd> - The Qt GUI for create and control VMs and another virtual entities - (aka networks, storages, interfaces, secrets, network filters). - Contains integrated LXC/SPICE/VNC viewer for accessing the graphical or - text console associated with a virtual machine or container. - </dd> - <dt><a href="https://f1ash.github.io/qt-virt-manager/#virtual-machines-viewer">qt-remote-viewer</a></dt> - <dd> - The Qt VNC/SPICE viewer for access to remote desktops or VMs. - </dd> - </dl> - - <h2><a id="iaas">Infrastructure as a Service (IaaS)</a></h2> - - <dl> - <dt><a href="http://cc1.ifj.edu.pl">Cracow Cloud One</a></dt> - <dd>The CC1 system provides a complete solution for Private - Cloud Computing. An intuitive web access interface with an - administration module and simple installation procedure make - it easy to benefit from private Cloud Computing technology. - </dd> - - <dt><a href="https://github.com/eucalyptus/eucalyptus">Eucalyptus</a></dt> - <dd> - Eucalyptus is an on-premise Infrastructure as a Service cloud - software platform that is open source and - AWS-compatible. Eucalyptus uses libvirt virtualization API to - directly interact with Xen and KVM hypervisors. - </dd> - - <dt><a href="http://www.nimbusproject.org">Nimbus</a></dt> - <dd> - Nimbus is an open-source toolkit focused on providing - Infrastructure-as-a-Service (IaaS) capabilities to the scientific - community. It uses libvirt for communication with all KVM and Xen - virtual machines. - </dd> - - <dt><a href="http://snooze.inria.fr">Snooze</a></dt> - <dd> - Snooze is an open-source scalable, autonomic, and energy-efficient - virtual machine (VM) management framework for private clouds. It - integrates libvirt for VM monitoring, live migration, and life-cycle - management. - </dd> - - <dt><a href="https://www.openstack.org">OpenStack</a></dt> - <dd> - OpenStack is a "cloud operating system" usable for both public - and private clouds. Its various parts take care of compute, - storage and networking resources and interface with the user - using a dashboard. Compute part uses libvirt to manage VM - life-cycle, monitoring and so on. - </dd> - - <dt><a href="https://kubevirt.io/">KubeVirt</a></dt> - <dd> - KubeVirt is a virtual machine management add-on for Kubernetes. The aim - is to provide a common ground for virtualization solutions on top of - Kubernetes. - </dd> - - <dt><a href="https://github.com/gustavfranssonnyvell/cherrypop">Cherrypop</a></dt> - <dd> - A cloud software with no masters or central points. Nodes - autodetect other nodes and autodistribute virtual - machines and autodivide up the workload. Also there is no - minimum limit for hosts, well, one might be nice. It's - perfect for setting up low-end servers in a cloud or a - cloud where you want the most bang for the bucks. - </dd> - - <dt><a href="https://en.zstack.io/">ZStack</a></dt> - <dd> - ZStack is an open source IaaS software that aims to automate the - management of all resources (compute, storage, networking, etc.) in a - datacenter by using APIs, thus conforming to the principles of a - software-defined datacenter. The key strengths of ZStack in terms of - management are scalability, performance, and a fast, user-friendly - deployment. - </dd> - </dl> - - <h2><a id="libraries">Libraries</a></h2> - - <dl> - <dt><a href="https://libguestfs.org">libguestfs</a></dt> - <dd> - A library and set of tools for accessing and modifying virtual - machine disk images. It can be linked with C and C++ management - programs, and has bindings for Perl, Python, Ruby, Java, OCaml, - PHP, Haskell, and C#. - </dd> - <dd> - Using its FUSE module, you can also mount guest filesystems on the - host, and there is a subproject to allow merging changes into the - Windows Registry in Windows guests. - </dd> - - <dt><a href="https://sandbox.libvirt.org">libvirt-sandbox</a></dt> - <dd> - A library and command line tools for simplifying the creation of - application sandboxes using virtualization technology. It currently - supports either KVM, QEMU or LXC as backends. Integration with - systemd facilitates sandboxing of system services like apache. - </dd> - <dt><a href="https://github.com/ohadlevy/virt#readme">Ruby - Libvirt Object bindings</a></dt> - <dd> - Allows using simple ruby objects to manipulate - hypervisors, guests, storage, network etc. It is - based on top of - the <a href="https://libvirt.org/ruby">native ruby bindings</a>. - </dd> - </dl> - - <h2><a id="livecd">LiveCD / Appliances</a></h2> - - <dl> - <dt><a href="https://libguestfs.org/virt-v2v/">virt-p2v</a></dt> - <dd> - An older tool for converting a physical machine into a virtual - machine. It is a LiveCD which is booted on the machine to be - converted. It collects a little information from the user, then - copies the disks over to a remote machine and defines the XML for a - domain to run the guest. - </dd> - </dl> - - <h2><a id="monitoring">Monitoring</a></h2> - <dl> - <dt><a href="https://collectd.org/plugins/libvirt.shtml">collectd</a></dt> - <dd> - The libvirt-plugin is part of <a href="https://collectd.org/">collectd</a> - and gathers statistics about virtualized guests on a system. This - way, you can collect CPU, network interface and block device usage - for each guest without installing collectd on the guest systems. - For a full description, please refer to the libvirt section in the - collectd.conf(5) manual page. - </dd> - <dt><a href="https://www.sflow.net/">Host sFlow</a></dt> - <dd> - Host sFlow is a lightweight agent running on KVM hypervisors that - links to libvirt library and exports standardized cpu, memory, network - and disk metrics for all virtual machines. - </dd> - <dt><a href="https://honk.sigxcpu.org/projects/libvirt/#munin">Munin</a></dt> - <dd> - The plugins provided by Guido Günther allow to monitor various things - like network and block I/O with - <a href="http://munin.projects.linpro.no/">Munin</a>. - </dd> - <dt><a href="https://people.redhat.com/rjones/nagios-virt/">Nagios-virt</a></dt> - <dd> - Nagios-virt is a configuration tool to add monitoring of your - virtualised domains to <a href="https://www.nagios.org/">Nagios</a>. - You can use this tool to either set up a new Nagios installation for - your Xen or QEMU/KVM guests, or to integrate with your existing Nagios - installation. - </dd> - <dt><a href="https://pcp.io/man/man1/pmdalibvirt.1.html">PCP</a></dt> - <dd> - The PCP libvirt PMDA (plugin) is part of the - <a href="https://pcp.io/">PCP</a> toolkit and provides - hypervisor and guest information and complete set of guest performance - metrics. It supports pCPU, vCPU, memory, block device, network interface, - and performance event metrics for each virtual guest. - </dd> - </dl> - - <h2><a id="provisioning">Provisioning</a></h2> - - <dl> - <dt><a href="https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/Tivoli+Provisioning+Manager">Tivoli Provisioning Manager</a></dt> - <dd> - Part of the IBM Tivoli family, Tivoli Provisioning Manager (TPM) is - an IT lifecycle automation product. It - <a href="http://publib.boulder.ibm.com/infocenter/tivihelp/v38r1/index.jsp?topic=/com.ibm.tivoli.tpm.apk.doc/libvirt_package.html">uses libvirt</a> - for communication with virtualization hosts and guest domains. - </dd> - </dl> - - <dl> - <dt><a href="https://theforeman.org">Foreman</a></dt> - <dd> - Foreman is an open source web based application aimed to be a - Single Address For All Machines Life Cycle Management. Foreman: - - <ul> - <li>Creates everything you need when adding a new machine to - your network, its goal being automatically managing - everything you would normally manage manually (DNS, DHCP, - TFTP, Virtual Machines,CA, CMDB...)</li> - <li>Integrates with Puppet (and acts as web front end to it).</li> - <li>Takes care of provisioning until the point puppet is - running, allowing Puppet to do what it does best.</li> - <li>Shows you Systems Inventory (based on Facter) and - provides real time information about hosts status based on - Puppet reports.</li> - </ul> - </dd> - </dl> - - - <h2><a id="web">Web applications</a></h2> - - <dl> - <dt><a href="https://www.abiquo.com/">AbiCloud</a></dt> - <dd> - AbiCloud is an open source cloud platform manager which allows to - easily deploy a private cloud in your datacenter. One of the key - differences of AbiCloud is the web rich interface for managing the - infrastructure. You can deploy a new service just dragging and - dropping a VM. - </dd> - <dt><a href="https://kimchi-project.github.io/kimchi/">Kimchi</a></dt> - <dd> - Kimchi is an HTML5 based management tool for KVM. It is designed to - make it as easy as possible to get started with KVM and create your first guest. - - Kimchi manages KVM guests through libvirt. The management interface is accessed - over the web using a browser that supports HTML5. - </dd> - <dt><a href="https://ovirt.org/">oVirt</a></dt> - <dd> - oVirt provides the ability to manage large numbers of virtual - machines across an entire data center of hosts. It integrates - with FreeIPA for Kerberos authentication, and in the future, - certificate management. - </dd> - <dt><a href="https://ispsystem.com/en/software/vmmanager">VMmanager</a></dt> - <dd> - VMmanager is a software solution for virtualization management - that can be used both for hosting virtual machines and - building a cloud. VMmanager can manage not only one server, - but a large cluster of hypervisors. It delivers a number of - functions, such as live migration that allows for load - balancing between cluster nodes, monitoring CPU, memory. - </dd> - <dt><a href="https://mist.io/">mist.io</a></dt> - <dd> - Mist.io is an open source project and a service that can assist you in - managing your virtual machines on a unified way, providing a simple - interface for all of your infrastructure (multiple public cloud - providers, OpenStack based public/private clouds, Docker servers, bare - metal servers and now KVM hypervisors). - </dd> - <dt><a href="https://ravada.upc.edu/">Ravada</a></dt> - <dd> - Ravada is an open source tool for managing Virtual Desktop - Infrastructure (VDI). It is very easy to install and use. Following - the documentation, you'll be ready to deploy virtual machines in - minutes. The only requirements for the users are a Web browser and - a lightweight remote viewer. - </dd> - <dt><a href="https://github.com/cutelyst/Virtlyst">Virtlyst</a></dt> - <dd> - Virtlyst is an open source web application built with C++11, Cutelyst and Qt. - It features: - <ul> - <li>Low memory usage (around 5 MiB of RAM)</li> - <li>Look and feel easily customized with HTML templates that use the Django syntax</li> - <li>VNC/Spice console directly in the browser using websockets on the same HTTP port</li> - <li>Host and Domain statistics graphs (CPU, Memory, IO, Network)</li> - <li>Connect to multiple libvirtd instances (over local Unix domain socket, SSH, TCP and TLS)</li> - <li>Manage Storage Pools, Storage Volumes, Networks, Interfaces, and Secrets</li> - <li>Create and launch VMs</li> - <li>Configure VMs with easy panels or go pro and edit the VM's XML</li> - </ul> - </dd> - </dl> - - <h2><a id="other">Other</a></h2> - - <dl> - <dt><a href="https://cuckoosandbox.org/">Cuckoo Sandbox</a></dt> - <dd> - Cuckoo Sandbox is a malware analysis system. You can throw - any suspicious file at it and in a matter of seconds Cuckoo - will provide you back some detailed results outlining what - such file did when executed inside an isolated environment. - And libvirt is one of the backends that can be used for the - isolated environment. - </dd> - </dl> - - </body> -</html> diff --git a/docs/apps.rst b/docs/apps.rst new file mode 100644 index 0000000000..a21e2249ea --- /dev/null +++ b/docs/apps.rst @@ -0,0 +1,348 @@ +========================== +Applications using libvirt +========================== + +This page provides an illustration of the wide variety of applications +using the libvirt management API. + +.. contents:: + +Add an application +------------------ + +To add an application not listed on this page, send a message to the +`mailing list <contact.html>`__, requesting it be added here, or simply +send a patch against the documentation in the libvirt.git docs +subdirectory. If your application uses libvirt as its API, the following +graphics are available for your website to advertise support for +libvirt: + +|libvirt powered 96| |libvirt powered 128| |libvirt powered 192| |libvirt powered 256| + +Command line tools +------------------ + +`guestfish <https://libguestfs.org>`__ + Guestfish is an interactive shell and command-line tool for examining + and modifying virtual machine filesystems. It uses libvirt to find + guests and their associated disks. +virsh + An interactive shell, and batch scriptable tool for performing + management tasks on all libvirt managed domains, networks and + storage. This is part of the libvirt core distribution. +`virt-clone <https://virt-manager.org/>`__ + Allows the disk image(s) and configuration for an existing virtual + machine to be cloned to form a new virtual machine. It automates + copying of data across to new disk images, and updates the UUID, MAC + address, and name in the configuration. +`virt-df <https://people.redhat.com/rjones/virt-df/>`__ + Examine the utilization of each filesystem in a virtual machine from + the comfort of the host machine. This tool peeks into the guest disks + and determines how much space is used. It can cope with common Linux + filesystems and LVM volumes. +`virt-image <https://virt-manager.org/>`__ + Provides a way to deploy virtual appliances. It defines a simplified + portable XML format describing the pre-requisites of a virtual + machine. At time of deployment this is translated into the domain XML + format for execution under any libvirt hypervisor meeting the + pre-requisites. +`virt-install <https://virt-manager.org/>`__ + Provides a way to provision new virtual machines from a OS + distribution install tree. It supports provisioning from local CD + images, and the network over NFS, HTTP and FTP. +`virt-top <https://people.redhat.com/rjones/virt-top/>`__ + Watch the CPU, memory, network and disk utilization of all virtual + machines running on a host. +`virt-what <https://people.redhat.com/~rjones/virt-what/>`__ + virt-what is a shell script for detecting if the program is running + in a virtual machine. It prints out a list of facts about the virtual + machine, derived from heuristics. +`stap <https://sourceware.org/systemtap/>`__ + SystemTap is a tool used to gather rich information about a running + system through the use of scripts. Starting from v2.4, the front-end + application stap can use libvirt to gather data within virtual + machines. +`vagrant-libvirt <https://github.com/pradels/vagrant-libvirt/>`__ + Vagrant-Libvirt is a Vagrant plugin that uses libvirt to manage + virtual machines. It is a command line tool for developers that makes + it very fast and easy to deploy and re-deploy an environment of vm's. +`virt-lightning <https://github.com/virt-lightning/virt-lightning>`__ + Virt-Lightning uses libvirt, cloud-init and libguestfs to allow + anyone to quickly start a new VM. Very much like a container CLI, but + with a virtual machine. + +Configuration Management +------------------------ + +`LCFG <https://wiki.lcfg.org/bin/view/LCFG/LcfgLibvirt>`__ + LCFG is a system for automatically installing and managing the + configuration of large numbers of Unix systems. It is particularly + suitable for sites with very diverse and rapidly changing + configurations. + The lcfg-libvirt package adds support for virtualized systems to + LCFG, with both Xen and KVM known to work. Cloning guests is + supported, as are the bridged, routed, and isolated modes for Virtual + Networking. + +Continuous Integration +---------------------- + +`BuildBot <https://docs.buildbot.net/latest/manual/configuration/workers-libvirt.html>`__ + BuildBot is a system to automate the compile/test cycle required by + most software projects. CVS commits trigger new builds, run on a + variety of client machines. Build status (pass/fail/etc) are + displayed on a web page or through other protocols. + +`Jenkins <https://plugins.jenkins.io/libvirt-slave/>`__ + This plugin for Jenkins adds a way to control guest domains hosted on + Xen or QEMU/KVM. You configure a Jenkins Agent, selecting the guest + domain and hypervisor. When you need to build a job on a specific + Agent, its guest domain is started, then the job is run. When the + build process is finished, the guest domain is shut down, ready to be + used again as required. + +Conversion +---------- + +`virt-p2v <https://libguestfs.org/virt-p2v.1.html>`__ + Convert a physical machine to run on KVM. It is a LiveCD which is + booted on the machine to be converted. It collects a little + information from the user, then copies the disks over to a remote + machine and defines the XML for a domain to run the guest. (Note this + tool is included with libguestfs) +`virt-v2v <https://libguestfs.org/virt-v2v.1.html>`__ + virt-v2v converts guests from a foreign hypervisor to run on KVM, + managed by libvirt. It can convert guests from VMware or Xen to run + on OpenStack, oVirt (RHEV-M), or local libvirt. It will enable VirtIO + drivers in the converted guest if possible. (Note this tool is + included with libguestfs) + For RHEL customers of Red Hat, conversion of Windows guests is also + possible. This conversion requires some Microsoft signed pieces, that + Red Hat can provide. +`vmware2libvirt <https://launchpad.net/virt-goodies>`__ + Part of the *virt-goodies* package, vmware2libvirt is a python script + for migrating a vmware image to libvirt. + +Desktop applications +-------------------- + +`virt-manager <https://virt-manager.org/>`__ + A general purpose desktop management tool, able to manage virtual + machines across both local and remotely accessed hypervisors. It is + targeted at home and small office usage up to managing 10-20 hosts + and their VMs. +`virt-viewer <https://virt-manager.org/>`__ + A lightweight tool for accessing the graphical console associated + with a virtual machine. It can securely connect to remote consoles + supporting the VNC protocol. Also provides an optional mozilla + browser plugin. +`qt-virt-manager <https://f1ash.github.io/qt-virt-manager>`__ + The Qt GUI for create and control VMs and another virtual entities + (aka networks, storages, interfaces, secrets, network filters). + Contains integrated LXC/SPICE/VNC viewer for accessing the graphical + or text console associated with a virtual machine or container. +`qt-remote-viewer <https://f1ash.github.io/qt-virt-manager/#virtual-machines-viewer>`__ + The Qt VNC/SPICE viewer for access to remote desktops or VMs. + +Infrastructure as a Service (IaaS) +---------------------------------- + +`Cracow Cloud One <http://cc1.ifj.edu.pl>`__ + The CC1 system provides a complete solution for Private Cloud + Computing. An intuitive web access interface with an administration + module and simple installation procedure make it easy to benefit from + private Cloud Computing technology. +`Eucalyptus <https://github.com/eucalyptus/eucalyptus>`__ + Eucalyptus is an on-premise Infrastructure as a Service cloud + software platform that is open source and AWS-compatible. Eucalyptus + uses libvirt virtualization API to directly interact with Xen and KVM + hypervisors. +`Nimbus <http://www.nimbusproject.org>`__ + Nimbus is an open-source toolkit focused on providing + Infrastructure-as-a-Service (IaaS) capabilities to the scientific + community. It uses libvirt for communication with all KVM and Xen + virtual machines. +`Snooze <http://snooze.inria.fr>`__ + Snooze is an open-source scalable, autonomic, and energy-efficient + virtual machine (VM) management framework for private clouds. It + integrates libvirt for VM monitoring, live migration, and life-cycle + management. +`OpenStack <https://www.openstack.org>`__ + OpenStack is a "cloud operating system" usable for both public and + private clouds. Its various parts take care of compute, storage and + networking resources and interface with the user using a dashboard. + Compute part uses libvirt to manage VM life-cycle, monitoring and so + on. +`KubeVirt <https://kubevirt.io/>`__ + KubeVirt is a virtual machine management add-on for Kubernetes. The + aim is to provide a common ground for virtualization solutions on top + of Kubernetes. +`Cherrypop <https://github.com/gustavfranssonnyvell/cherrypop>`__ + A cloud software with no masters or central points. Nodes autodetect + other nodes and autodistribute virtual machines and autodivide up the + workload. Also there is no minimum limit for hosts, well, one might + be nice. It's perfect for setting up low-end servers in a cloud or a + cloud where you want the most bang for the bucks. +`ZStack <https://en.zstack.io/>`__ + ZStack is an open source IaaS software that aims to automate the + management of all resources (compute, storage, networking, etc.) in a + datacenter by using APIs, thus conforming to the principles of a + software-defined datacenter. The key strengths of ZStack in terms of + management are scalability, performance, and a fast, user-friendly + deployment. + +Libraries +--------- + +`libguestfs <https://libguestfs.org>`__ + A library and set of tools for accessing and modifying virtual + machine disk images. It can be linked with C and C++ management + programs, and has bindings for Perl, Python, Ruby, Java, OCaml, PHP, + Haskell, and C#. + Using its FUSE module, you can also mount guest filesystems on the + host, and there is a subproject to allow merging changes into the + Windows Registry in Windows guests. +`libvirt-sandbox <https://sandbox.libvirt.org>`__ + A library and command line tools for simplifying the creation of + application sandboxes using virtualization technology. It currently + supports either KVM, QEMU or LXC as backends. Integration with + systemd facilitates sandboxing of system services like apache. +`Ruby Libvirt Object bindings <https://github.com/ohadlevy/virt#readme>`__ + Allows using simple ruby objects to manipulate hypervisors, guests, + storage, network etc. It is based on top of the `native ruby + bindings <https://libvirt.org/ruby>`__. + +LiveCD / Appliances +------------------- + +`virt-p2v <https://libguestfs.org/virt-v2v/>`__ + An older tool for converting a physical machine into a virtual + machine. It is a LiveCD which is booted on the machine to be + converted. It collects a little information from the user, then + copies the disks over to a remote machine and defines the XML for a + domain to run the guest. + +Monitoring +---------- + +`collectd <https://collectd.org/plugins/libvirt.shtml>`__ + The libvirt-plugin is part of `collectd <https://collectd.org/>`__ + and gathers statistics about virtualized guests on a system. This + way, you can collect CPU, network interface and block device usage + for each guest without installing collectd on the guest systems. For + a full description, please refer to the libvirt section in the + collectd.conf(5) manual page. +`Host sFlow <https://www.sflow.net/>`__ + Host sFlow is a lightweight agent running on KVM hypervisors that + links to libvirt library and exports standardized cpu, memory, + network and disk metrics for all virtual machines. +`Munin <https://honk.sigxcpu.org/projects/libvirt/#munin>`__ + The plugins provided by Guido Günther allow to monitor various things + like network and block I/O with + `Munin <http://munin.projects.linpro.no/>`__. +`Nagios-virt <https://people.redhat.com/rjones/nagios-virt/>`__ + Nagios-virt is a configuration tool to add monitoring of your + virtualised domains to `Nagios <https://www.nagios.org/>`__. You can + use this tool to either set up a new Nagios installation for your Xen + or QEMU/KVM guests, or to integrate with your existing Nagios + installation. +`PCP <https://pcp.io/man/man1/pmdalibvirt.1.html>`__ + The PCP libvirt PMDA (plugin) is part of the + `PCP <https://pcp.io/>`__ toolkit and provides hypervisor and guest + information and complete set of guest performance metrics. It + supports pCPU, vCPU, memory, block device, network interface, and + performance event metrics for each virtual guest. + +Provisioning +------------ + +`Tivoli Provisioning Manager <https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/Tivoli+Provisioning+Manager>`__ + Part of the IBM Tivoli family, Tivoli Provisioning Manager (TPM) is + an IT lifecycle automation product. It `uses + libvirt <http://publib.boulder.ibm.com/infocenter/tivihelp/v38r1/index.jsp?topic=/com.ibm.tivoli.tpm.apk.doc/libvirt_package.html>`__ + for communication with virtualization hosts and guest domains. + +`Foreman <https://theforeman.org>`__ + Foreman is an open source web based application aimed to be a Single + Address For All Machines Life Cycle Management. Foreman: + + - Creates everything you need when adding a new machine to your + network, its goal being automatically managing everything you + would normally manage manually (DNS, DHCP, TFTP, Virtual + Machines,CA, CMDB...) + - Integrates with Puppet (and acts as web front end to it). + - Takes care of provisioning until the point puppet is running, + allowing Puppet to do what it does best. + - Shows you Systems Inventory (based on Facter) and provides real + time information about hosts status based on Puppet reports. + +Web applications +---------------- + +`AbiCloud <https://www.abiquo.com/>`__ + AbiCloud is an open source cloud platform manager which allows to + easily deploy a private cloud in your datacenter. One of the key + differences of AbiCloud is the web rich interface for managing the + infrastructure. You can deploy a new service just dragging and + dropping a VM. +`Kimchi <https://kimchi-project.github.io/kimchi/>`__ + Kimchi is an HTML5 based management tool for KVM. It is designed to + make it as easy as possible to get started with KVM and create your + first guest. Kimchi manages KVM guests through libvirt. The + management interface is accessed over the web using a browser that + supports HTML5. +`oVirt <https://ovirt.org/>`__ + oVirt provides the ability to manage large numbers of virtual + machines across an entire data center of hosts. It integrates with + FreeIPA for Kerberos authentication, and in the future, certificate + management. +`VMmanager <https://ispsystem.com/en/software/vmmanager>`__ + VMmanager is a software solution for virtualization management that + can be used both for hosting virtual machines and building a cloud. + VMmanager can manage not only one server, but a large cluster of + hypervisors. It delivers a number of functions, such as live + migration that allows for load balancing between cluster nodes, + monitoring CPU, memory. +`mist.io <https://mist.io/>`__ + Mist.io is an open source project and a service that can assist you + in managing your virtual machines on a unified way, providing a + simple interface for all of your infrastructure (multiple public + cloud providers, OpenStack based public/private clouds, Docker + servers, bare metal servers and now KVM hypervisors). +`Ravada <https://ravada.upc.edu/>`__ + Ravada is an open source tool for managing Virtual Desktop + Infrastructure (VDI). It is very easy to install and use. Following + the documentation, you'll be ready to deploy virtual machines in + minutes. The only requirements for the users are a Web browser and a + lightweight remote viewer. +`Virtlyst <https://github.com/cutelyst/Virtlyst>`__ + Virtlyst is an open source web application built with C++11, Cutelyst + and Qt. It features: + + - Low memory usage (around 5 MiB of RAM) + - Look and feel easily customized with HTML templates that use the + Django syntax + - VNC/Spice console directly in the browser using websockets on the + same HTTP port + - Host and Domain statistics graphs (CPU, Memory, IO, Network) + - Connect to multiple libvirtd instances (over local Unix domain + socket, SSH, TCP and TLS) + - Manage Storage Pools, Storage Volumes, Networks, Interfaces, and + Secrets + - Create and launch VMs + - Configure VMs with easy panels or go pro and edit the VM's XML + +Other +----- + +`Cuckoo Sandbox <https://cuckoosandbox.org/>`__ + Cuckoo Sandbox is a malware analysis system. You can throw any + suspicious file at it and in a matter of seconds Cuckoo will provide + you back some detailed results outlining what such file did when + executed inside an isolated environment. And libvirt is one of the + backends that can be used for the isolated environment. + +.. |libvirt powered 96| image:: logos/logo-square-powered-96.png +.. |libvirt powered 128| image:: logos/logo-square-powered-128.png +.. |libvirt powered 192| image:: logos/logo-square-powered-192.png +.. |libvirt powered 256| image:: logos/logo-square-powered-256.png diff --git a/docs/meson.build b/docs/meson.build index 942cce6fdc..b61377ea8b 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'apps', 'architecture', 'auditlog', 'auth', @@ -107,6 +106,7 @@ docs_rst_files = [ 'advanced-tests', 'api_extension', 'api', + 'apps', 'best-practices', 'ci', 'coding-style', -- 2.29.2
On Fri, Mar 12, 2021 at 12:43:07 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/apps.html.in | 488 ---------------------------------------------- docs/apps.rst | 348 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 349 insertions(+), 489 deletions(-) delete mode 100644 docs/apps.html.in create mode 100644 docs/apps.rst
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/architecture.html.in | 82 -------------------------------------- docs/architecture.rst | 83 +++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 84 insertions(+), 83 deletions(-) delete mode 100644 docs/architecture.html.in create mode 100644 docs/architecture.rst diff --git a/docs/architecture.html.in b/docs/architecture.html.in deleted file mode 100644 index 7a5cf2dca8..0000000000 --- a/docs/architecture.html.in +++ /dev/null @@ -1,82 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1 >libvirt architecture</h1> - - <p> - Currently libvirt supports 2 kind of virtualization, and its - internal structure is based on a driver model which simplifies - adding new - engines: - </p> - - <ul id="toc"></ul> - - <h2><a id="Xen">Xen support</a></h2> - - <p>When running in a Xen environment, programs using libvirt have to execute -in "Domain 0", which is the primary Linux OS loaded on the machine. That OS -kernel provides most if not all of the actual drivers used by the set of -domains. It also runs the Xen Store, a database of information shared by the -hypervisor, the backend drivers, any running domains, and libxl (aka libxenlight). -libxl provides a set of APIs for creating and managing domains, which can be used -by applications such as the xl tool provided by Xen or libvirt. The hypervisor, -drivers, kernels and daemons communicate though a shared system bus -implemented in the hypervisor. The figure below tries to provide a view of -this environment:</p> - <img src="architecture.gif" alt="The Xen architecture" /> - <p>The library will interact with libxl for all management operations -on a Xen system.</p> - <p>Note that the libvirt libxl driver only supports root access.</p> - - <h2><a id="QEMU">QEMU and KVM support</a></h2> - - <p>The model for QEMU and KVM is completely similar, basically KVM is based -on QEMU for the process controlling a new domain, only small details differs -between the two. In both case the libvirt API is provided by a controlling -process forked by libvirt in the background and which launch and control the -QEMU or KVM process. That program called libvirt_qemud talks though a specific -protocol to the library, and connects to the console of the QEMU process in -order to control and report on its status. Libvirt tries to expose all the -emulations models of QEMU, the selection is done when creating the new -domain, by specifying the architecture and machine type targeted.</p> - <p>The code controlling the QEMU process is available in the -<code>qemud/</code> directory.</p> - - <h2><a id="drivers">Driver based architecture</a></h2> - - <p>As the previous section explains, libvirt can communicate using different -channels with the current hypervisor, and should also be able to use -different kind of hypervisor. To simplify the internal design, code, ease -maintenance and simplify the support of other virtualization engine the -internals have been structured as one core component, the libvirt.c module -acting as a front-end for the library API and a set of hypervisor drivers -defining a common set of routines. That way the Xen Daemon access, the Xen -Store one, the Hypervisor hypercall are all isolated in separate C modules -implementing at least a subset of the common operations defined by the -drivers present in driver.h:</p> - <ul> - <li>xend_internal: implements the driver functions though the Xen - Daemon</li> - <li>xs_internal: implements the subset of the driver available though the - Xen Store</li> - <li>xen_internal: provide the implementation of the functions possible via - direct hypervisor access</li> - <li>proxy_internal: provide read-only Xen access via a proxy, the proxy code - is in the <code>proxy/</code> directory.</li> - <li>xm_internal: provide support for Xen defined but not running - domains.</li> - <li>qemu_internal: implement the driver functions for QEMU and - KVM virtualization engines. It also uses a qemud/ specific daemon - which interacts with the QEMU process to implement libvirt API.</li> - <li>test: this is a test driver useful for regression tests of the - front-end part of libvirt.</li> - </ul> - <p>Note that a given driver may only implement a subset of those functions, -(for example saving a Xen domain state to disk and restoring it is only -possible though the Xen Daemon), in that case the driver entry points for -unsupported functions are initialized to NULL.</p> - <p></p> - </body> -</html> diff --git a/docs/architecture.rst b/docs/architecture.rst new file mode 100644 index 0000000000..f74906d36e --- /dev/null +++ b/docs/architecture.rst @@ -0,0 +1,83 @@ +==================== +libvirt architecture +==================== + +Currently libvirt supports 2 kind of virtualization, and its internal +structure is based on a driver model which simplifies adding new +engines: + +.. contents:: + +Xen support +----------- + +When running in a Xen environment, programs using libvirt have to +execute in "Domain 0", which is the primary Linux OS loaded on the +machine. That OS kernel provides most if not all of the actual drivers +used by the set of domains. It also runs the Xen Store, a database of +information shared by the hypervisor, the backend drivers, any running +domains, and libxl (aka libxenlight). libxl provides a set of APIs for +creating and managing domains, which can be used by applications such as +the xl tool provided by Xen or libvirt. The hypervisor, drivers, kernels +and daemons communicate though a shared system bus implemented in the +hypervisor. The figure below tries to provide a view of this +environment: + +|The Xen architecture| + +The library will interact with libxl for all management operations on a +Xen system. + +Note that the libvirt libxl driver only supports root access. + +QEMU and KVM support +-------------------- + +The model for QEMU and KVM is completely similar, basically KVM is based +on QEMU for the process controlling a new domain, only small details +differs between the two. In both case the libvirt API is provided by a +controlling process forked by libvirt in the background and which launch +and control the QEMU or KVM process. That program called libvirt_qemud +talks though a specific protocol to the library, and connects to the +console of the QEMU process in order to control and report on its +status. Libvirt tries to expose all the emulations models of QEMU, the +selection is done when creating the new domain, by specifying the +architecture and machine type targeted. + +The code controlling the QEMU process is available in the ``qemud/`` +directory. + +Driver based architecture +------------------------- + +As the previous section explains, libvirt can communicate using +different channels with the current hypervisor, and should also be able +to use different kind of hypervisor. To simplify the internal design, +code, ease maintenance and simplify the support of other virtualization +engine the internals have been structured as one core component, the +libvirt.c module acting as a front-end for the library API and a set of +hypervisor drivers defining a common set of routines. That way the Xen +Daemon access, the Xen Store one, the Hypervisor hypercall are all +isolated in separate C modules implementing at least a subset of the +common operations defined by the drivers present in driver.h: + +- xend_internal: implements the driver functions though the Xen Daemon +- xs_internal: implements the subset of the driver available though the + Xen Store +- xen_internal: provide the implementation of the functions possible + via direct hypervisor access +- proxy_internal: provide read-only Xen access via a proxy, the proxy + code is in the ``proxy/`` directory. +- xm_internal: provide support for Xen defined but not running domains. +- qemu_internal: implement the driver functions for QEMU and KVM + virtualization engines. It also uses a qemud/ specific daemon which + interacts with the QEMU process to implement libvirt API. +- test: this is a test driver useful for regression tests of the + front-end part of libvirt. + +Note that a given driver may only implement a subset of those functions, +(for example saving a Xen domain state to disk and restoring it is only +possible though the Xen Daemon), in that case the driver entry points +for unsupported functions are initialized to NULL. + +.. |The Xen architecture| image:: architecture.gif diff --git a/docs/meson.build b/docs/meson.build index b61377ea8b..0e0c266cb9 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'architecture', 'auditlog', 'auth', 'bindings', @@ -107,6 +106,7 @@ docs_rst_files = [ 'api_extension', 'api', 'apps', + 'architecture', 'best-practices', 'ci', 'coding-style', -- 2.29.2
On Fri, Mar 12, 2021 at 12:43:08 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/architecture.html.in | 82 -------------------------------------- docs/architecture.rst | 83 +++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 84 insertions(+), 83 deletions(-) delete mode 100644 docs/architecture.html.in create mode 100644 docs/architecture.rst
N.B.: This file doesn't seem to be linked from anywhere on our webpage. Search finds it by name, but if you don't know what you are looking for it's pretty hidden.
On Fri, Mar 12, 2021 at 13:56:06 +0100, Peter Krempa wrote:
On Fri, Mar 12, 2021 at 12:43:08 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/architecture.html.in | 82 -------------------------------------- docs/architecture.rst | 83 +++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 84 insertions(+), 83 deletions(-) delete mode 100644 docs/architecture.html.in create mode 100644 docs/architecture.rst
N.B.: This file doesn't seem to be linked from anywhere on our webpage. Search finds it by name, but if you don't know what you are looking for it's pretty hidden.
I wanted to suggest to convert it to a kbase article since it's unlinked but now that I had a look at the contents, the documents seems very outdated. As of such I'd probably completely remove it at this point.
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/auditlog.html.in | 375 ------------------------------------------ docs/auditlog.rst | 321 ++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 322 insertions(+), 376 deletions(-) delete mode 100644 docs/auditlog.html.in create mode 100644 docs/auditlog.rst diff --git a/docs/auditlog.html.in b/docs/auditlog.html.in deleted file mode 100644 index eb00d9742e..0000000000 --- a/docs/auditlog.html.in +++ /dev/null @@ -1,375 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Audit log</h1> - - <ul id="toc"></ul> - - <h2><a id="intro">Introduction</a></h2> - - <p> - A number of the libvirt virtualization drivers (QEMU/KVM and LXC) include - support for logging details of important operations to the host's audit - subsystem. This provides administrators / auditors with a canonical historical - record of changes to virtual machines' / containers' lifecycle states and - their configuration. On hosts which are running the Linux audit daemon, - the logs will usually end up in <code>/var/log/audit/audit.log</code> - </p> - - <h2><a id="config">Configuration</a></h2> - - <p> - The libvirt audit integration is enabled by default on any host which has - the Linux audit subsystem active, and disabled otherwise. It is possible - to alter this behaviour in the <code>/etc/libvirt/libvirtd.conf</code> - configuration file, via the <code>audit_level</code> parameter - </p> - - <ul> - <li><code>audit_level=0</code> - libvirt auditing is disabled regardless - of host audit subsystem enablement.</li> - <li><code>audit_level=1</code> - libvirt auditing is enabled if the host - audit subsystem is enabled, otherwise it is disabled. This is the - default behaviour.</li> - <li><code>audit_level=2</code> - libvirt auditing is enabled regardless - of host audit subsystem enablement. If the host audit subsystem is - disabled, then libvirtd will refuse to complete startup and exit with - an error.</li> - </ul> - - <p> - In addition to have formal messages sent to the audit subsystem it is - possible to tell libvirt to inject messages into its own logging - layer. This will result in messages ending up in the systemd journal - or <code>/var/log/libvirt/libvirtd.log</code> on non-systemd hosts. - This is disabled by default, but can be requested by setting the - <code>audit_logging=1</code> configuration parameter in the same file - mentioned above. - </p> - - <h2><a id="types">Message types</a></h2> - - <p> - Libvirt defines three core audit message types each of which will - be described below. There are a number of common fields that will - be reported for all message types. - </p> - - <dl> - <dt><code>pid</code></dt> - <dd>Process ID of the libvirtd daemon generating the audit record.</dd> - <dt><code>uid</code></dt> - <dd>User ID of the libvirtd daemon process generating the audit record.</dd> - <dt><code>subj</code></dt> - <dd>Security context of the libvirtd daemon process generating the audit record.</dd> - <dt><code>msg</code></dt> - <dd>String containing a list of key=value pairs specific to the type of audit record being reported.</dd> - </dl> - - <p> - Some fields in the <code>msg</code> string are common to audit records - </p> - - <dl> - <dt><code>virt</code></dt> - <dd>Type of virtualization driver used. One of <code>qemu</code> or <code>lxc</code></dd> - <dt><code>vm</code></dt> - <dd>Host driver unique name of the guest</dd> - <dt><code>uuid</code></dt> - <dd>Globally unique identifier for the guest</dd> - <dt><code>exe</code></dt> - <dd>Path of the libvirtd daemon</dd> - <dt><code>hostname</code></dt> - <dd>Currently unused</dd> - <dt><code>addr</code></dt> - <dd>Currently unused</dd> - <dt><code>terminal</code></dt> - <dd>Currently unused</dd> - <dt><code>res</code></dt> - <dd>Result of the action, either <code>success</code> or <code>failed</code></dd> - </dl> - - <h3><a id="typecontrol">VIRT_CONTROL</a></h3> - - <p> - Reports change in the lifecycle state of a virtual machine. The <code>msg</code> - field will include the following sub-fields - </p> - - <dl> - <dt><code>op</code></dt> - <dd>Type of operation performed. One of <code>start</code>, <code>stop</code> or <code>init</code></dd> - <dt><code>reason</code></dt> - <dd>The reason which caused the operation to happen</dd> - <dt><code>vm-pid</code></dt> - <dd>ID of the primary/leading process associated with the guest</dd> - <dt><code>init-pid</code></dt> - <dd>ID of the <code>init</code> process in a container. Only if <code>op=init</code> and <code>virt=lxc</code></dd> - <dt><code>pid-ns</code></dt> - <dd>Namespace ID of the <code>init</code> process in a container. Only if <code>op=init</code> and <code>virt=lxc</code></dd> - </dl> - - <h3><a id="typemachine">VIRT_MACHINE_ID</a></h3> - - <p> - Reports the association of a security context with a guest. The <code>msg</code> - field will include the following sub-fields - </p> - - <dl> - <dt><code>model</code></dt> - <dd>The security driver type. One of <code>selinux</code> or <code>apparmor</code></dd> - <dt><code>vm-ctx</code></dt> - <dd>Security context for the guest process</dd> - <dt><code>img-ctx</code></dt> - <dd>Security context for the guest disk images and other assigned host resources</dd> - </dl> - - <h3><a id="typeresource">VIRT_RESOURCE</a></h3> - - <p> - Reports the usage of a host resource by a guest. The fields include will - vary according to the type of device being reported. When the guest is - initially booted records will be generated for all assigned resources. - If any changes are made to the running guest configuration, for example - hotplug devices, or adjust resources allocation, further records will - be generated. - </p> - - <h4><a id="typeresourcevcpu">Virtual CPU</a></h4> - - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>vcpu</code></dd> - <dt><code>old-vcpu</code></dt> - <dd>Original vCPU count, or 0</dd> - <dt><code>new-vcpu</code></dt> - <dd>Updated vCPU count</dd> - </dl> - - - <h4><a id="typeresourcemem">Memory</a></h4> - - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>mem</code></dd> - <dt><code>old-mem</code></dt> - <dd>Original memory size in bytes, or 0</dd> - <dt><code>new-mem</code></dt> - <dd>Updated memory size in bytes</dd> - </dl> - - <h4><a id="typeresourcedisk">Disk</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>disk</code></dd> - <dt><code>old-disk</code></dt> - <dd>Original host file or device path acting as the disk backing file</dd> - <dt><code>new-disk</code></dt> - <dd>Updated host file or device path acting as the disk backing file</dd> - </dl> - - <h4><a id="typeresourcenic">Network interface</a></h4> - - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>net</code></dd> - <dt><code>old-net</code></dt> - <dd>Original MAC address of the guest network interface</dd> - <dt><code>new-net</code></dt> - <dd>Updated MAC address of the guest network interface</dd> - </dl> - - <p> - If there is a host network interface associated with the guest NIC then - further records may be generated - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>net</code></dd> - <dt><code>net</code></dt> - <dd>MAC address of the host network interface</dd> - <dt><code>rdev</code></dt> - <dd>Name of the host network interface</dd> - </dl> - - <h4><a id="typeresourcefs">Filesystem</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>fs</code></dd> - <dt><code>old-fs</code></dt> - <dd>Original host directory, file or device path backing the filesystem </dd> - <dt><code>new-fs</code></dt> - <dd>Updated host directory, file or device path backing the filesystem</dd> - </dl> - - <h4><a id="typeresourcehost">Host device</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>hostdev</code> or <code>dev</code></dd> - <dt><code>dev</code></dt> - <dd>The unique bus identifier of the USB, PCI or SCSI device, if <code>resrc=dev</code></dd> - <dt><code>disk</code></dt> - <dd>The path of the block device assigned to the guest, if <code>resrc=hostdev</code></dd> - <dt><code>chardev</code></dt> - <dd>The path of the character device assigned to the guest, if <code>resrc=hostdev</code></dd> - </dl> - - <h4><a id="typeresourcetpm">TPM</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>tpm</code> or <code>tpm-emulator</code></dd> - <dt><code>device</code></dt> - <dd>The path of the host TPM device assigned to the guest</dd> - </dl> - - <h4><a id="typeresourcerng">RNG</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>rng</code></dd> - <dt><code>old-rng</code></dt> - <dd>Original path of the host entropy source for the RNG</dd> - <dt><code>new-rng</code></dt> - <dd>Updated path of the host entropy source for the RNG</dd> - </dl> - - <h4><a id="typeresourcechardev">console/serial/parallel/channel</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>chardev</code></dd> - <dt><code>old-chardev</code></dt> - <dd>Original path of the backing character device for given emulated device</dd> - <dt><code>new-chardev</code></dt> - <dd>Updated path of the backing character device for given emulated device</dd> - </dl> - - <h4><a id="typeresourcesmartcard">smartcard</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>smartcard</code></dd> - <dt><code>old-smartcard</code></dt> - <dd>Original path of the backing character device, certificate store or - "nss-smartcard-device" for host smartcard passthrough. - </dd> - <dt><code>new-smartcard</code></dt> - <dd>Updated path of the backing character device, certificate store or - "nss-smartcard-device" for host smartcard passthrough. - </dd> - </dl> - - <h4><a id="typeresourceredir">Redirected device</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>redir</code></dd> - <dt><code>bus</code></dt> - <dd>The bus type, only <code>usb</code> allowed</dd> - <dt><code>device</code></dt> - <dd>The device type, only <code>USB redir</code> allowed</dd> - </dl> - - <h4><a id="typeresourcecgroup">Control group</a></h4> - - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>cgroup</code></dd> - <dt><code>cgroup</code></dt> - <dd>The name of the cgroup controller</dd> - </dl> - - - <h4><a id="typeresourceshmem">Shared memory</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>shmem</code></dd> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>size</code></dt> - <dd>The size of the shared memory region</dd> - <dt><code>shmem</code></dt> - <dd>Name of the shared memory region</dd> - <dt><code>source</code></dt> - <dd>Path of the backing character device for given emulated device</dd> - </dl> - - </body> -</html> diff --git a/docs/auditlog.rst b/docs/auditlog.rst new file mode 100644 index 0000000000..e99374ffa8 --- /dev/null +++ b/docs/auditlog.rst @@ -0,0 +1,321 @@ +========= +Audit log +========= + +.. contents:: + +Introduction +------------ + +A number of the libvirt virtualization drivers (QEMU/KVM and LXC) +include support for logging details of important operations to the +host's audit subsystem. This provides administrators / auditors with a +canonical historical record of changes to virtual machines' / +containers' lifecycle states and their configuration. On hosts which are +running the Linux audit daemon, the logs will usually end up in +``/var/log/audit/audit.log`` + +Configuration +------------- + +The libvirt audit integration is enabled by default on any host which +has the Linux audit subsystem active, and disabled otherwise. It is +possible to alter this behaviour in the ``/etc/libvirt/libvirtd.conf`` +configuration file, via the ``audit_level`` parameter + +- ``audit_level=0`` - libvirt auditing is disabled regardless of host + audit subsystem enablement. +- ``audit_level=1`` - libvirt auditing is enabled if the host audit + subsystem is enabled, otherwise it is disabled. This is the default + behaviour. +- ``audit_level=2`` - libvirt auditing is enabled regardless of host + audit subsystem enablement. If the host audit subsystem is disabled, + then libvirtd will refuse to complete startup and exit with an error. + +In addition to have formal messages sent to the audit subsystem it is +possible to tell libvirt to inject messages into its own logging layer. +This will result in messages ending up in the systemd journal or +``/var/log/libvirt/libvirtd.log`` on non-systemd hosts. This is disabled +by default, but can be requested by setting the ``audit_logging=1`` +configuration parameter in the same file mentioned above. + +Message types +------------- + +Libvirt defines three core audit message types each of which will be +described below. There are a number of common fields that will be +reported for all message types. + +``pid`` + Process ID of the libvirtd daemon generating the audit record. +``uid`` + User ID of the libvirtd daemon process generating the audit record. +``subj`` + Security context of the libvirtd daemon process generating the audit + record. +``msg`` + String containing a list of key=value pairs specific to the type of + audit record being reported. + +Some fields in the ``msg`` string are common to audit records + +``virt`` + Type of virtualization driver used. One of ``qemu`` or ``lxc`` +``vm`` + Host driver unique name of the guest +``uuid`` + Globally unique identifier for the guest +``exe`` + Path of the libvirtd daemon +``hostname`` + Currently unused +``addr`` + Currently unused +``terminal`` + Currently unused +``res`` + Result of the action, either ``success`` or ``failed`` + +VIRT_CONTROL +~~~~~~~~~~~~ + +Reports change in the lifecycle state of a virtual machine. The ``msg`` +field will include the following sub-fields + +``op`` + Type of operation performed. One of ``start``, ``stop`` or ``init`` +``reason`` + The reason which caused the operation to happen +``vm-pid`` + ID of the primary/leading process associated with the guest +``init-pid`` + ID of the ``init`` process in a container. Only if ``op=init`` and + ``virt=lxc`` +``pid-ns`` + Namespace ID of the ``init`` process in a container. Only if + ``op=init`` and ``virt=lxc`` + +VIRT_MACHINE_ID +~~~~~~~~~~~~~~~ + +Reports the association of a security context with a guest. The ``msg`` +field will include the following sub-fields + +``model`` + The security driver type. One of ``selinux`` or ``apparmor`` +``vm-ctx`` + Security context for the guest process +``img-ctx`` + Security context for the guest disk images and other assigned host + resources + +VIRT_RESOURCE +~~~~~~~~~~~~~ + +Reports the usage of a host resource by a guest. The fields include will +vary according to the type of device being reported. When the guest is +initially booted records will be generated for all assigned resources. +If any changes are made to the running guest configuration, for example +hotplug devices, or adjust resources allocation, further records will be +generated. + +Virtual CPU +^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``vcpu`` +``old-vcpu`` + Original vCPU count, or 0 +``new-vcpu`` + Updated vCPU count + +Memory +^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``mem`` +``old-mem`` + Original memory size in bytes, or 0 +``new-mem`` + Updated memory size in bytes + +Disk +^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``disk`` +``old-disk`` + Original host file or device path acting as the disk backing file +``new-disk`` + Updated host file or device path acting as the disk backing file + +Network interface +^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``net`` +``old-net`` + Original MAC address of the guest network interface +``new-net`` + Updated MAC address of the guest network interface + +If there is a host network interface associated with the guest NIC then +further records may be generated + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``net`` +``net`` + MAC address of the host network interface +``rdev`` + Name of the host network interface + +Filesystem +^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``fs`` +``old-fs`` + Original host directory, file or device path backing the filesystem +``new-fs`` + Updated host directory, file or device path backing the filesystem + +Host device +^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``hostdev`` or ``dev`` +``dev`` + The unique bus identifier of the USB, PCI or SCSI device, if + ``resrc=dev`` +``disk`` + The path of the block device assigned to the guest, if + ``resrc=hostdev`` +``chardev`` + The path of the character device assigned to the guest, if + ``resrc=hostdev`` + +TPM +^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``tpm`` or ``tpm-emulator`` +``device`` + The path of the host TPM device assigned to the guest + +RNG +^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``rng`` +``old-rng`` + Original path of the host entropy source for the RNG +``new-rng`` + Updated path of the host entropy source for the RNG + +console/serial/parallel/channel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``chardev`` +``old-chardev`` + Original path of the backing character device for given emulated + device +``new-chardev`` + Updated path of the backing character device for given emulated + device + +smartcard +^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``smartcard`` +``old-smartcard`` + Original path of the backing character device, certificate store or + "nss-smartcard-device" for host smartcard passthrough. +``new-smartcard`` + Updated path of the backing character device, certificate store or + "nss-smartcard-device" for host smartcard passthrough. + +Redirected device +^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``redir`` +``bus`` + The bus type, only ``usb`` allowed +``device`` + The device type, only ``USB redir`` allowed + +Control group +^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``cgroup`` +``cgroup`` + The name of the cgroup controller + +Shared memory +^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``resrc`` + The type of resource assigned. Set to ``shmem`` +``reason`` + The reason which caused the resource to be assigned to happen +``size`` + The size of the shared memory region +``shmem`` + Name of the shared memory region +``source`` + Path of the backing character device for given emulated device diff --git a/docs/meson.build b/docs/meson.build index 0e0c266cb9..f80a08112e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'auditlog', 'auth', 'bindings', 'bugs', @@ -107,6 +106,7 @@ docs_rst_files = [ 'api', 'apps', 'architecture', + 'auditlog', 'best-practices', 'ci', 'coding-style', -- 2.29.2
On Fri, Mar 12, 2021 at 12:43:09 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/auditlog.html.in | 375 ------------------------------------------ docs/auditlog.rst | 321 ++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 322 insertions(+), 376 deletions(-) delete mode 100644 docs/auditlog.html.in create mode 100644 docs/auditlog.rst
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/auth.html.in | 368 ---------------------------------------------- docs/auth.rst | 343 ++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 344 insertions(+), 369 deletions(-) delete mode 100644 docs/auth.html.in create mode 100644 docs/auth.rst diff --git a/docs/auth.html.in b/docs/auth.html.in deleted file mode 100644 index 9b940a8598..0000000000 --- a/docs/auth.html.in +++ /dev/null @@ -1,368 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Connection authentication</h1> - <p> - When connecting to libvirt, some connections may require client - authentication before allowing use of the APIs. The set of possible - authentication mechanisms is administrator controlled, independent - of applications using libvirt. Once authenticated, libvirt can apply - fine grained <a href="acl.html">access control</a> to the operations - performed by a client. - </p> - - <ul id="toc"></ul> - - <h2><a id="Auth_client_config">Client configuration</a></h2> - - <p> - When connecting to a remote hypervisor which requires authentication, -most libvirt applications will prompt the user for the credentials. It is -also possible to provide a client configuration file containing all the -authentication credentials, avoiding any interaction. Libvirt will look -for the authentication file using the following sequence: - </p> - <ol> - <li>The file path specified by the $LIBVIRT_AUTH_FILE environment - variable.</li> - <li>The file path specified by the "authfile=/some/file" URI - query parameter</li> - <li>The file $XDG_CONFIG_HOME/libvirt/auth.conf</li> - <li>The file /etc/libvirt/auth.conf</li> - </ol> - - <p> - The auth configuration file uses the traditional <code>".ini"</code> - style syntax. There are two types of groups that can be present in - the config. First there are one or more <strong>credential</strong> - sets, which provide the actual authentication credentials. The keys - within the group may be: - </p> - - <ul> - <li><code>username</code>: the user login name to act as. This - is relevant for ESX, Xen, HyperV and SSH, but probably not - the one you want to libvirtd with SASL.</li> - <li><code>authname</code>: the name to authorize as. This is - what is commonly required for libvirtd with SASL.</li> - <li><code>password</code>: the secret password</li> - <li><code>realm</code>: the domain realm for SASL, mostly - unused</li> - </ul> - - <p> - Each set of credentials has a name, which is part of the group - entry name. Overall the syntax is - </p> - - <pre> -[credentials-$NAME] -credname1=value1 -credname2=value2</pre> - - <p> - For example, to define two sets of credentials used for production - and test machines, using libvirtd, and a further ESX server for dev: - </p> -<pre> -[credentials-test] -authname=fred -password=123456 - -[credentials-prod] -authname=bar -password=letmein - -[credentials-dev] -username=joe -password=hello - -[credentials-defgrp] -username=defuser -password=defpw</pre> - - <p> - The second set of groups provide mappings of credentials to - specific machine services. The config file group names compromise - the service type and host: - </p> - - <pre> -[auth-$SERVICE-$HOSTNAME] -credentials=$CREDENTIALS</pre> - - <p> - For example, following the previous example, here is how to - map some machines. For convenience libvirt supports a default - mapping of credentials to machines: - </p> - - <pre> -[auth-libvirt-test1.example.com] -credentials=test - -[auth-libvirt-test2.example.com] -credentials=test - -[auth-libvirt-demo3.example.com] -credentials=test - -[auth-libvirt-prod1.example.com] -credentials=prod - -[auth-libvirt-default] -credentials=defgrp - -[auth-esx-dev1.example.com] -credentials=dev - -[auth-esx-default] -credentials=defgrp</pre> - - - <p> - The following service types are known to libvirt: - </p> - - <ul> - <li><code>esx</code> - used for connections to an ESX or - VirtualCenter server</li> - <li><code>hyperv</code> - used for connections to an HyperV - server</li> - <li><code>libvirt</code> - used for connections to a libvirtd - server, which is configured with SASL auth</li> - <li><code>ssh</code> - used for connections to a remote QEMU driver - over SSH</li> - </ul> - - <p> - Applications using libvirt are free to use this same configuration - file for storing other credentials. For example, it can be used - to storage VNC or SPICE login credentials - </p> - - <h2><a id="ACL_server_config">Server configuration</a></h2> - <p> -The libvirt daemon allows the administrator to choose the authentication -mechanisms used for client connections on each network socket independently. -This is primarily controlled via the libvirt daemon master config file in -<code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can -have its authentication mechanism configured independently. There is -currently a choice of <code>none</code>, <code>polkit</code>, and <code>sasl</code>. -The SASL scheme can be further configured to choose between a large -number of different mechanisms. -</p> - <h2><a id="ACL_server_unix_perms">UNIX socket permissions/group</a></h2> - <p> -If libvirt does not contain support for PolicyKit, then access control for -the UNIX domain socket is done using traditional file user/group ownership -and permissions. There are 2 sockets, one for full read-write access, the -other for read-only access. The RW socket will be restricted (mode 0700) to -only allow the <code>root</code> user to connect. The read-only socket will -be open access (mode 0777) to allow any user to connect. -</p> - <p> -To allow non-root users greater access, the <code>libvirtd.conf</code> file -can be edited to change the permissions via the <code>unix_sock_rw_perms</code>, -config parameter and to set a user group via the <code>unix_sock_group</code> -parameter. For example, setting the former to mode <code>0770</code> and the -latter <code>wheel</code> would let any user in the wheel group connect to -the libvirt daemon. -</p> - <h2><a id="ACL_server_polkit">UNIX socket PolicyKit auth</a></h2> - <p> -If libvirt contains support for PolicyKit, then access control options are -more advanced. The <code>auth_unix_rw</code> parameter will default to -<code>polkit</code>, and the file permissions will default to <code>0777</code> -even on the RW socket. Upon connecting to the socket, the client application -will be required to identify itself with PolicyKit. The default policy for the -RW daemon socket will require any application running in the current desktop -session to authenticate using the user's password. This is akin to <code>sudo</code> -auth, but does not require that the client application ultimately run as root. -Default policy will still allow any application to connect to the RO socket. -</p> - <p> -The default policy can be overridden by creating a new policy file in the -<code>/etc/polkit-1/rules.d</code> directory. Information on the options -available can be found by reading the <code>polkit(8)</code> man page. The -two libvirt actions are named <code>org.libvirt.unix.manage</code> for full -management access, and <code>org.libvirt.unix.monitor</code> for read-only -access. -</p> - <p> -As an example, creating <code>/etc/polkit-1/rules.d/80-libvirt-manage.rules</code> -with the following gives the user <code>fred</code> full management access -when accessing from an active local session: - </p> -<pre>polkit.addRule(function(action, subject) { - if (action.id == "org.libvirt.unix.manage" && - subject.local && subject.active && subject.user == "fred") { - return polkit.Result.YES; - } -});</pre> - <p> -Older versions of PolicyKit used policy files ending with .pkla in the -local override directory <code>/etc/polkit-1/localauthority/50-local.d/</code>. -Compatibility with this older format is provided by <a -href="https://pagure.io/polkit-pkla-compat">polkit-pkla-compat</a>. As an -example, this gives the user <code>fred</code> full management access: - </p> -<pre>[Allow fred libvirt management permissions] -Identity=unix-user:fred -Action=org.libvirt.unix.manage -ResultAny=yes -ResultInactive=yes -ResultActive=yes</pre> - <h2><a id="ACL_server_sasl">SASL pluggable authentication</a></h2> - - <p> -Libvirt integrates with the cyrus-sasl library to provide a pluggable authentication -system using the SASL protocol. SASL can be used in combination with libvirtd's TLS -or TCP socket listeners. When used with the TCP listener, the SASL mechanism is -rqeuired to provide session encryption in addition to authentication. Only a very -few SASL mechanisms are able to do this, and of those that can do it, only the -GSSAPI plugin is considered acceptably secure by modern standards: - </p> - - <dl> - <dt>GSSAPI</dt> - <dd><strong>This is the current default mechanism to use with libvirtd</strong>. - It uses the Kerberos v5 authentication protocol underneath, and assuming - the Kerberos client/server are configured with modern ciphers (AES), - it provides strong session encryption capabilities.</dd> - - <dt>DIGEST-MD5</dt> - <dd>This was previously set as the default mechanism to use with libvirtd. - It provides a simple username/password based authentication mechanism - that includes session encryption. - <a href="https://tools.ietf.org/html/rfc6331">RFC 6331</a>, however, - documents a number of serious security flaws with DIGEST-MD5 and as a - result marks it as <code>OBSOLETE</code>. Specific concerns are that - it is vulnerable to MITM attacks and the MD5 hash can be brute-forced - to reveal the password. A replacement is provided via the SCRAM mechanism, - however, note that this does not provide encryption, so the SCRAM - mechanism can only be used on the libvirtd TLS listener. - </dd> - - <dt>PASSDSS-3DES-1</dt> - <dd>This provides a simple username/password based authentication - mechanism that includes session encryption. The current cyrus-sasl - implementation does not provide a way to validate the server's - public key identity, thus it is susceptible to a MITM attacker - impersonating the server. It is also not enabled in many OS - distros when building SASL libraries.</dd> - - <dt>KERBEROS_V4</dt> - <dd>This uses the obsolete Kerberos v4 protocol to provide both authentication - and session encryption. Kerberos v4 protocol has been obsolete since the - early 1990's and has known security vulnerabilities so this will never be - used in practice.</dd> - </dl> - - <p> - Other SASL mechanisms, not listed above, can only be used when the libvirtd - TLS or UNIX socket listeners. - </p> - - <h3><a id="ACL_server_username">Username/password auth</a></h3> - <p> -As noted above, the DIGEST-MD5 mechanism is considered obsolete and should -not be used anymore. To provide a simple username/password auth scheme on -the libvirt UNIX socket or TLS listeners, however, it is possible to use -the SCRAM mechanism. The <code>auth_unix_ro</code>, <code>auth_unix_rw</code>, -<code>auth_tls</code> config params in <code>libvirt.conf</code> can be used -to turn on SASL auth in these listeners. - </p> - <p> -Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), a -config change is required to enable plain password auth. This is done by -editing <code>/etc/sasl2/libvirt.conf</code> to set the <code>mech_list</code> -parameter to <code>scram-sha-1</code>. - </p> - <p> -Out of the box, no user accounts are defined, so no clients will be able to authenticate -on the TCP socket. Adding users and setting their passwords is done with the <code>saslpasswd2</code> -command. When running this command it is important to tell it that the appname is <code>libvirt</code>. -As an example, to add a user <code>fred</code>, run -</p> - <pre> -# saslpasswd2 -a libvirt fred -Password: xxxxxx -Again (for verification): xxxxxx -</pre> - <p> -To see a list of all accounts the <code>sasldblistusers2</code> command can be used. -This command expects to be given the path to the libvirt user database, which is kept -in <code>/etc/libvirt/passwd.db</code> -</p> - <pre> -# sasldblistusers2 -f /etc/libvirt/passwd.db -fred@t60wlan.home.berrange.com: userPassword -</pre> - <p> -Finally, to disable a user's access, the <code>saslpasswd2</code> command can be used -again: -</p> - <pre> -# saslpasswd2 -a libvirt -d fred -</pre> - <h3><a id="ACL_server_kerberos">GSSAPI/Kerberos auth</a></h3> - <p> -The plain TCP listener of the libvirt daemon defaults to using SASL for authentication. -The libvirt SASL config also defaults to GSSAPI, so there is no need to edit the -SASL config when using GSSAPI. If the libvirtd TLS or UNIX listeners are used, -then the Kerberos session encryption will be disabled since it is not required -in these scenarios - only the plain TCP listener needs encryption -</p> - <p> -Some operating systems do not install the SASL kerberos plugin by default. It -may be necessary to install a sub-package such as <code>cyrus-sasl-gssapi</code>. -To check whether the Kerberos plugin is installed run the <code>pluginviewer</code> -program and verify that <code>gssapi</code> is listed, e.g.: -</p> - <pre> -# pluginviewer -...snip... -Plugin "gssapiv2" [loaded], API version: 4 - SASL mechanism: GSSAPI, best SSF: 56 - security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH - features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN -</pre> - <p> -Next it is necessary for the administrator of the Kerberos realm to -issue a principal for the libvirt server. There needs to be one -principal per host running the libvirt daemon. The principal should be -named <code>libvirt/full.hostname@KERBEROS.REALM</code>. This is -typically done by running the <code>kadmin.local</code> command on the -Kerberos server, though some Kerberos servers have alternate ways of -setting up service principals. Once created, the principal should be -exported to a keytab, copied to the host running the libvirt daemon -and placed in <code>/etc/libvirt/krb5.tab</code> -</p> - <pre> -# kadmin.local -kadmin.local: add_principal libvirt/foo.example.com -Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": -Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": -Principal "libvirt/foo.example.com@EXAMPLE.COM" created. - -kadmin.local: ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.com@EXAMPLE.COM -Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab. -Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab. -Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab. -Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-example.tab. - -kadmin.local: quit - -# scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5.tab -# rm /root/libvirt-foo-example.tab -</pre> - <p> -Any client application wishing to connect to a Kerberos enabled libvirt server -merely needs to run <code>kinit</code> to gain a user principal. This may well -be done automatically when a user logs into a desktop session, if PAM is set up -to authenticate against Kerberos. -</p> - </body> -</html> diff --git a/docs/auth.rst b/docs/auth.rst new file mode 100644 index 0000000000..26fa6c950c --- /dev/null +++ b/docs/auth.rst @@ -0,0 +1,343 @@ +========================= +Connection authentication +========================= + +When connecting to libvirt, some connections may require client +authentication before allowing use of the APIs. The set of possible +authentication mechanisms is administrator controlled, independent of +applications using libvirt. Once authenticated, libvirt can apply fine +grained `access control <acl.html>`__ to the operations performed by a +client. + +.. contents:: + +Client configuration +-------------------- + +When connecting to a remote hypervisor which requires authentication, +most libvirt applications will prompt the user for the credentials. It +is also possible to provide a client configuration file containing all +the authentication credentials, avoiding any interaction. Libvirt will +look for the authentication file using the following sequence: + +#. The file path specified by the $LIBVIRT_AUTH_FILE environment + variable. +#. The file path specified by the "authfile=/some/file" URI query + parameter +#. The file $XDG_CONFIG_HOME/libvirt/auth.conf +#. The file /etc/libvirt/auth.conf + +The auth configuration file uses the traditional ``".ini"`` style +syntax. There are two types of groups that can be present in the config. +First there are one or more **credential** sets, which provide the +actual authentication credentials. The keys within the group may be: + +- ``username``: the user login name to act as. This is relevant for + ESX, Xen, HyperV and SSH, but probably not the one you want to + libvirtd with SASL. +- ``authname``: the name to authorize as. This is what is commonly + required for libvirtd with SASL. +- ``password``: the secret password +- ``realm``: the domain realm for SASL, mostly unused + +Each set of credentials has a name, which is part of the group entry +name. Overall the syntax is + +:: + + [credentials-$NAME] + credname1=value1 + credname2=value2 + +For example, to define two sets of credentials used for production and +test machines, using libvirtd, and a further ESX server for dev: + +:: + + [credentials-test] + authname=fred + password=123456 + + [credentials-prod] + authname=bar + password=letmein + + [credentials-dev] + username=joe + password=hello + + [credentials-defgrp] + username=defuser + password=defpw + +The second set of groups provide mappings of credentials to specific +machine services. The config file group names compromise the service +type and host: + +:: + + [auth-$SERVICE-$HOSTNAME] + credentials=$CREDENTIALS + +For example, following the previous example, here is how to map some +machines. For convenience libvirt supports a default mapping of +credentials to machines: + +:: + + [auth-libvirt-test1.example.com] + credentials=test + + [auth-libvirt-test2.example.com] + credentials=test + + [auth-libvirt-demo3.example.com] + credentials=test + + [auth-libvirt-prod1.example.com] + credentials=prod + + [auth-libvirt-default] + credentials=defgrp + + [auth-esx-dev1.example.com] + credentials=dev + + [auth-esx-default] + credentials=defgrp + +The following service types are known to libvirt: + +- ``esx`` - used for connections to an ESX or VirtualCenter server +- ``hyperv`` - used for connections to an HyperV server +- ``libvirt`` - used for connections to a libvirtd server, which is + configured with SASL auth +- ``ssh`` - used for connections to a remote QEMU driver over SSH + +Applications using libvirt are free to use this same configuration file +for storing other credentials. For example, it can be used to storage +VNC or SPICE login credentials + +Server configuration +-------------------- + +The libvirt daemon allows the administrator to choose the authentication +mechanisms used for client connections on each network socket +independently. This is primarily controlled via the libvirt daemon +master config file in ``/etc/libvirt/libvirtd.conf``. Each of the +libvirt sockets can have its authentication mechanism configured +independently. There is currently a choice of ``none``, ``polkit``, and +``sasl``. The SASL scheme can be further configured to choose between a +large number of different mechanisms. + +UNIX socket permissions/group +----------------------------- + +If libvirt does not contain support for PolicyKit, then access control +for the UNIX domain socket is done using traditional file user/group +ownership and permissions. There are 2 sockets, one for full read-write +access, the other for read-only access. The RW socket will be restricted +(mode 0700) to only allow the ``root`` user to connect. The read-only +socket will be open access (mode 0777) to allow any user to connect. + +To allow non-root users greater access, the ``libvirtd.conf`` file can +be edited to change the permissions via the ``unix_sock_rw_perms``, +config parameter and to set a user group via the ``unix_sock_group`` +parameter. For example, setting the former to mode ``0770`` and the +latter ``wheel`` would let any user in the wheel group connect to the +libvirt daemon. + +UNIX socket PolicyKit auth +-------------------------- + +If libvirt contains support for PolicyKit, then access control options +are more advanced. The ``auth_unix_rw`` parameter will default to +``polkit``, and the file permissions will default to ``0777`` even on +the RW socket. Upon connecting to the socket, the client application +will be required to identify itself with PolicyKit. The default policy +for the RW daemon socket will require any application running in the +current desktop session to authenticate using the user's password. This +is akin to ``sudo`` auth, but does not require that the client +application ultimately run as root. Default policy will still allow any +application to connect to the RO socket. + +The default policy can be overridden by creating a new policy file in +the ``/etc/polkit-1/rules.d`` directory. Information on the options +available can be found by reading the ``polkit(8)`` man page. The two +libvirt actions are named ``org.libvirt.unix.manage`` for full +management access, and ``org.libvirt.unix.monitor`` for read-only +access. + +As an example, creating +``/etc/polkit-1/rules.d/80-libvirt-manage.rules`` with the following +gives the user ``fred`` full management access when accessing from an +active local session: + +:: + + polkit.addRule(function(action, subject) { + if (action.id == "org.libvirt.unix.manage" && + subject.local && subject.active && subject.user == "fred") { + return polkit.Result.YES; + } + }); + +Older versions of PolicyKit used policy files ending with .pkla in the +local override directory ``/etc/polkit-1/localauthority/50-local.d/``. +Compatibility with this older format is provided by +`polkit-pkla-compat <https://pagure.io/polkit-pkla-compat>`__. As an +example, this gives the user ``fred`` full management access: + +:: + + [Allow fred libvirt management permissions] + Identity=unix-user:fred + Action=org.libvirt.unix.manage + ResultAny=yes + ResultInactive=yes + ResultActive=yes + +SASL pluggable authentication +----------------------------- + +Libvirt integrates with the cyrus-sasl library to provide a pluggable +authentication system using the SASL protocol. SASL can be used in +combination with libvirtd's TLS or TCP socket listeners. When used with +the TCP listener, the SASL mechanism is rqeuired to provide session +encryption in addition to authentication. Only a very few SASL +mechanisms are able to do this, and of those that can do it, only the +GSSAPI plugin is considered acceptably secure by modern standards: + +GSSAPI + **This is the current default mechanism to use with libvirtd**. It + uses the Kerberos v5 authentication protocol underneath, and assuming + the Kerberos client/server are configured with modern ciphers (AES), + it provides strong session encryption capabilities. +DIGEST-MD5 + This was previously set as the default mechanism to use with + libvirtd. It provides a simple username/password based authentication + mechanism that includes session encryption. `RFC + 6331 <https://tools.ietf.org/html/rfc6331>`__, however, documents a + number of serious security flaws with DIGEST-MD5 and as a result + marks it as ``OBSOLETE``. Specific concerns are that it is vulnerable + to MITM attacks and the MD5 hash can be brute-forced to reveal the + password. A replacement is provided via the SCRAM mechanism, however, + note that this does not provide encryption, so the SCRAM mechanism + can only be used on the libvirtd TLS listener. +PASSDSS-3DES-1 + This provides a simple username/password based authentication + mechanism that includes session encryption. The current cyrus-sasl + implementation does not provide a way to validate the server's public + key identity, thus it is susceptible to a MITM attacker impersonating + the server. It is also not enabled in many OS distros when building + SASL libraries. +KERBEROS_V4 + This uses the obsolete Kerberos v4 protocol to provide both + authentication and session encryption. Kerberos v4 protocol has been + obsolete since the early 1990's and has known security + vulnerabilities so this will never be used in practice. + +Other SASL mechanisms, not listed above, can only be used when the +libvirtd TLS or UNIX socket listeners. + +Username/password auth +~~~~~~~~~~~~~~~~~~~~~~ + +As noted above, the DIGEST-MD5 mechanism is considered obsolete and +should not be used anymore. To provide a simple username/password auth +scheme on the libvirt UNIX socket or TLS listeners, however, it is +possible to use the SCRAM mechanism. The ``auth_unix_ro``, +``auth_unix_rw``, ``auth_tls`` config params in ``libvirt.conf`` can be +used to turn on SASL auth in these listeners. + +Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), +a config change is required to enable plain password auth. This is done +by editing ``/etc/sasl2/libvirt.conf`` to set the ``mech_list`` +parameter to ``scram-sha-1``. + +Out of the box, no user accounts are defined, so no clients will be able +to authenticate on the TCP socket. Adding users and setting their +passwords is done with the ``saslpasswd2`` command. When running this +command it is important to tell it that the appname is ``libvirt``. As +an example, to add a user ``fred``, run + +:: + + # saslpasswd2 -a libvirt fred + Password: xxxxxx + Again (for verification): xxxxxx + +To see a list of all accounts the ``sasldblistusers2`` command can be +used. This command expects to be given the path to the libvirt user +database, which is kept in ``/etc/libvirt/passwd.db`` + +:: + + # sasldblistusers2 -f /etc/libvirt/passwd.db + fred@t60wlan.home.berrange.com: userPassword + +Finally, to disable a user's access, the ``saslpasswd2`` command can be +used again: + +:: + + # saslpasswd2 -a libvirt -d fred + +GSSAPI/Kerberos auth +~~~~~~~~~~~~~~~~~~~~ + +The plain TCP listener of the libvirt daemon defaults to using SASL for +authentication. The libvirt SASL config also defaults to GSSAPI, so +there is no need to edit the SASL config when using GSSAPI. If the +libvirtd TLS or UNIX listeners are used, then the Kerberos session +encryption will be disabled since it is not required in these scenarios +- only the plain TCP listener needs encryption + +Some operating systems do not install the SASL kerberos plugin by +default. It may be necessary to install a sub-package such as +``cyrus-sasl-gssapi``. To check whether the Kerberos plugin is installed +run the ``pluginviewer`` program and verify that ``gssapi`` is listed, +e.g.: + +:: + + # pluginviewer + ...snip... + Plugin "gssapiv2" [loaded], API version: 4 + SASL mechanism: GSSAPI, best SSF: 56 + security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH + features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN + +Next it is necessary for the administrator of the Kerberos realm to +issue a principal for the libvirt server. There needs to be one +principal per host running the libvirt daemon. The principal should be +named ``libvirt/full.hostname@KERBEROS.REALM``. This is typically done +by running the ``kadmin.local`` command on the Kerberos server, though +some Kerberos servers have alternate ways of setting up service +principals. Once created, the principal should be exported to a keytab, +copied to the host running the libvirt daemon and placed in +``/etc/libvirt/krb5.tab`` + +:: + + # kadmin.local + kadmin.local: add_principal libvirt/foo.example.com + Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": + Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": + Principal "libvirt/foo.example.com@EXAMPLE.COM" created. + + kadmin.local: ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.com@EXAMPLE.COM + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-example.tab. + + kadmin.local: quit + + # scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5.tab + # rm /root/libvirt-foo-example.tab + +Any client application wishing to connect to a Kerberos enabled libvirt +server merely needs to run ``kinit`` to gain a user principal. This may +well be done automatically when a user logs into a desktop session, if +PAM is set up to authenticate against Kerberos. diff --git a/docs/meson.build b/docs/meson.build index f80a08112e..0179a68908 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'auth', 'bindings', 'bugs', 'cgroups', @@ -107,6 +106,7 @@ docs_rst_files = [ 'apps', 'architecture', 'auditlog', + 'auth', 'best-practices', 'ci', 'coding-style', -- 2.29.2
On Fri, Mar 12, 2021 at 12:43:10 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/auth.html.in | 368 ---------------------------------------------- docs/auth.rst | 343 ++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 344 insertions(+), 369 deletions(-) delete mode 100644 docs/auth.html.in create mode 100644 docs/auth.rst
diff --git a/docs/auth.html.in b/docs/auth.html.in deleted file mode 100644 index 9b940a8598..0000000000 --- a/docs/auth.html.in +++ /dev/null @@ -1,368 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Connection authentication</h1> - <p> - When connecting to libvirt, some connections may require client - authentication before allowing use of the APIs. The set of possible - authentication mechanisms is administrator controlled, independent - of applications using libvirt. Once authenticated, libvirt can apply - fine grained <a href="acl.html">access control</a> to the operations - performed by a client. - </p> - - <ul id="toc"></ul> - - <h2><a id="Auth_client_config">Client configuration</a></h2>
docs/kbase/locking-sanlock.rst links to this anchor: file <auth.html#Auth_client_config>`__ needs to contain something like [...]
diff --git a/docs/auth.rst b/docs/auth.rst new file mode 100644 index 0000000000..26fa6c950c --- /dev/null +++ b/docs/auth.rst @@ -0,0 +1,343 @@ +========================= +Connection authentication +========================= + +When connecting to libvirt, some connections may require client +authentication before allowing use of the APIs. The set of possible +authentication mechanisms is administrator controlled, independent of +applications using libvirt. Once authenticated, libvirt can apply fine +grained `access control <acl.html>`__ to the operations performed by a +client. + +.. contents:: + +Client configuration +--------------------
But docutils will generate an anchor with a different name here, since the name is based on the heading. You'll need to tweak the other file too in this case. I think that breaking the anchor is okay though in this instance and ugly hacks to preserve anchor names as done in formatdomain.rst are not needed.
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/bindings.html.in | 101 ------------------------------------------ docs/bindings.rst | 62 ++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 63 insertions(+), 102 deletions(-) delete mode 100644 docs/bindings.html.in create mode 100644 docs/bindings.rst diff --git a/docs/bindings.html.in b/docs/bindings.html.in deleted file mode 100644 index a1520707c5..0000000000 --- a/docs/bindings.html.in +++ /dev/null @@ -1,101 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1 >Bindings for other languages and integration API modules</h1> - - <p> - Libvirt supports C and C++ directly, and has bindings available - for other languages: - </p> - - <ul> - <li> - <strong>C#</strong>: Arnaud Champion develops - <a href="csharp.html">C# bindings</a>. - </li> - <li> - <strong>Go</strong>: Daniel Berrange develops - <a href="https://pkg.go.dev/libvirt.org/libvirt-go">Go bindings</a>. - </li> - <li> - <strong>Java</strong>: Daniel Veillard develops - <a href="java.html">Java bindings</a>. - </li> - <li> - <strong>OCaml</strong>: Richard Jones develops - <a href="https://libvirt.org/ocaml/">OCaml bindings</a>. - </li> - <li> - <strong>Perl</strong>: Daniel Berrange develops - <a href="https://search.cpan.org/dist/Sys-Virt/">Perl bindings</a>. - </li> - <li> - <p> - <strong>PHP</strong>: Radek Hladik started developing - <a href="https://libvirt.org/php">PHP bindings</a> in 2010. - </p> - <p> - In February 2011 the binding development has been moved to the libvirt.org website as - libvirt-php project. - </p> - <p> - The project is now maintained by Michal Novotny and it's heavily based - on Radek's version. For more information, including - information on posting patches to libvirt-php, please refer - to the <a href="https://libvirt.org/php">PHP bindings</a> site. - </p> - </li> - <li> - <p> - <strong>Python</strong>: Libvirt's python bindings are split to a - separate <a href="https://gitlab.com/libvirt/libvirt-python">package</a> - since version 1.2.0, older versions came with direct support for the - Python language. - </p> - <p> - If your libvirt is installed as packages, rather than compiled - by you from source code, ensure you have the appropriate - package installed. - </p> - <p> - This is named <b>libvirt-python</b> on RHEL/Fedora, - <a href="https://packages.ubuntu.com/search?keywords=python-libvirt"><b>python-libvirt</b></a> - on Ubuntu, and may be named differently on others. - </p> - <p> - For usage information, see the - <a href="python.html">Python API bindings</a> page. - </p> - </li> - <li> - <strong>Ruby</strong>: Chris Lalancette develops - <a href="https://libvirt.org/ruby/">Ruby bindings</a>. - </li> - </ul> - - <p> - Integration API modules: - </p> - - <ul> - <li> - <strong>D-Bus</strong>: Pavel Hrdina develops - <a href="dbus.html">D-Bus API</a>. - </li> - </ul> - - <p> - For information on using libvirt on <strong>Windows</strong> - <a href="windows.html">please see the Windows support page</a>. - </p> - - <p> - Support, requests or help for libvirt bindings are welcome on the - <a href="https://www.redhat.com/mailman/listinfo/libvir-list/">mailing list</a>, - as usual try to provide enough background information and make sure - you use recent version, see the <a href="bugs.html">help page</a>. - </p> - - </body> -</html> diff --git a/docs/bindings.rst b/docs/bindings.rst new file mode 100644 index 0000000000..c5b6b94519 --- /dev/null +++ b/docs/bindings.rst @@ -0,0 +1,62 @@ +======================================================== +Bindings for other languages and integration API modules +======================================================== + +.. contents:: + +Libvirt supports C and C++ directly, and has bindings available for +other languages: + +- **C#**: Arnaud Champion develops `C# bindings <csharp.html>`__. + +- **Go**: Daniel Berrange develops `Go + bindings <https://pkg.go.dev/libvirt.org/libvirt-go>`__. + +- **Java**: Daniel Veillard develops `Java bindings <java.html>`__. + +- **OCaml**: Richard Jones develops `OCaml + bindings <https://libvirt.org/ocaml/>`__. + +- **Perl**: Daniel Berrange develops `Perl + bindings <https://search.cpan.org/dist/Sys-Virt/>`__. + +- **PHP**: Radek Hladik started developing `PHP + bindings <https://libvirt.org/php>`__ in 2010. + + In February 2011 the binding development has been moved to the + libvirt.org website as libvirt-php project. + + The project is now maintained by Michal Novotny and it's heavily + based on Radek's version. For more information, including information + on posting patches to libvirt-php, please refer to the `PHP + bindings <https://libvirt.org/php>`__ site. + +- **Python**: Libvirt's python bindings are split to a separate + `package <https://gitlab.com/libvirt/libvirt-python>`__ since version + 1.2.0, older versions came with direct support for the Python + language. + + If your libvirt is installed as packages, rather than compiled by you + from source code, ensure you have the appropriate package installed. + + This is named **libvirt-python** on RHEL/Fedora, + `python-libvirt <https://packages.ubuntu.com/search?keywords=python-libvirt>`__ + on Ubuntu, and may be named differently on others. + + For usage information, see the `Python API bindings <python.html>`__ + page. + +- **Ruby**: Chris Lalancette develops `Ruby + bindings <https://libvirt.org/ruby/>`__. + +Integration API modules: + +- **D-Bus**: Pavel Hrdina develops `D-Bus API <dbus.html>`__. + +For information on using libvirt on **Windows** `please see the Windows +support page <windows.html>`__. + +Support, requests or help for libvirt bindings are welcome on the +`mailing list <https://www.redhat.com/mailman/listinfo/libvir-list/>`__, +as usual try to provide enough background information and make sure you +use recent version, see the `help page <bugs.html>`__. diff --git a/docs/meson.build b/docs/meson.build index 0179a68908..f4b29a2e59 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'bindings', 'bugs', 'cgroups', 'compiling', @@ -107,6 +106,7 @@ docs_rst_files = [ 'architecture', 'auditlog', 'auth', + 'bindings', 'best-practices', 'ci', 'coding-style', -- 2.29.2
On Fri, Mar 12, 2021 at 12:43:11 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/bindings.html.in | 101 ------------------------------------------ docs/bindings.rst | 62 ++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 63 insertions(+), 102 deletions(-) delete mode 100644 docs/bindings.html.in create mode 100644 docs/bindings.rst
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/compiling.html.in | 115 ----------------------------------------- docs/compiling.rst | 95 ++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 96 insertions(+), 116 deletions(-) delete mode 100644 docs/compiling.html.in create mode 100644 docs/compiling.rst diff --git a/docs/compiling.html.in b/docs/compiling.html.in deleted file mode 100644 index df6074780f..0000000000 --- a/docs/compiling.html.in +++ /dev/null @@ -1,115 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1><a id="installation">libvirt Installation</a></h1> - - <ul id="toc"></ul> - - <h2><a id="compiling">Compiling a release tarball</a></h2> - - <p> - libvirt uses the standard setup/build/install steps and mandates - that the build directory is different from the source directory: - </p> - - <pre> -$ xz -dc libvirt-x.x.x.tar.xz | tar xvf - -$ cd libvirt-x.x.x -$ meson build</pre> - - <p> - The <i>meson</i> script can be given options to change its default - behaviour. - </p> - - <p> - To get the complete list of the options run the following command: - </p> - - <pre> -$ meson configure</pre> - - <p> - When you have determined which options you want to use (if any), - continue the process. - </p> - - <p> - Note the use of <b>sudo</b> with the <i>ninja install</i> command - below. Using sudo is only required when installing to a location your - user does not have write access to. Installing to a system location - is a good example of this. - </p> - - <p> - If you are installing to a location that your user <i>does</i> have write - access to, then you can instead run the <i>ninja install</i> command - without putting <b>sudo</b> before it. - </p> - - <pre> -$ meson build <i>[possible options]</i> -$ ninja -C build -$ <b>sudo</b> <i>ninja -C build install</i></pre> - - <p> - At this point you <b>may</b> have to run ldconfig or a similar utility - to update your list of installed shared libs. - </p> - - <h2><a id="building">Building from a GIT checkout</a></h2> - - <p> - The libvirt build process uses Meson build system. By default when - the <code>meson</code> is run from within a GIT checkout, it - will turn on -Werror for builds. This can be disabled with - --werror=false, but this is not recommended. - </p> - - <p>To build & install libvirt to your home - directory the following commands can be run: - </p> - - <pre> -$ meson build --prefix=$HOME/usr -$ ninja -C build -$ <b>sudo</b> ninja -C build install</pre> - - <p> - Be aware though, that binaries built with a custom prefix will not - interoperate with OS vendor provided binaries, since the UNIX socket - paths will all be different. To produce a build that is compatible - with normal OS vendor prefixes, use - </p> - - <pre> -$ meson build -Dsystem=true -$ ninja -C build - </pre> - - <p> - When doing this for day-to-day development purposes, it is recommended - not to install over the OS vendor provided binaries. Instead simply - run libvirt directly from the source tree. For example to run - a privileged libvirtd instance - </p> - - <pre> -$ su - -# service libvirtd stop (or systemctl stop libvirtd.service) -# /home/to/your/checkout/build/src/libvirtd - </pre> - - <p> - It is also possible to run virsh directly from the build tree - using the ./run script (which sets some environment variables): - </p> - - <pre> -$ pwd -/home/to/your/checkout/build -$ ./run ./tools/virsh .... - </pre> - </body> -</html> diff --git a/docs/compiling.rst b/docs/compiling.rst new file mode 100644 index 0000000000..62519b6bdb --- /dev/null +++ b/docs/compiling.rst @@ -0,0 +1,95 @@ +==================== +libvirt Installation +==================== + +.. contents:: + +Compiling a release tarball +--------------------------- + +libvirt uses the standard setup/build/install steps and mandates that +the build directory is different from the source directory: + +:: + + $ xz -dc libvirt-x.x.x.tar.xz | tar xvf - + $ cd libvirt-x.x.x + $ meson build + +The *meson* script can be given options to change its default behaviour. + +To get the complete list of the options run the following command: + +:: + + $ meson configure + +When you have determined which options you want to use (if any), +continue the process. + +Note the use of **sudo** with the *ninja install* command below. Using +sudo is only required when installing to a location your user does not +have write access to. Installing to a system location is a good example +of this. + +If you are installing to a location that your user *does* have write +access to, then you can instead run the *ninja install* command without +putting **sudo** before it. + +:: + + $ meson build [possible options] + $ ninja -C build + $ sudo ninja -C build install + +At this point you **may** have to run ldconfig or a similar utility to +update your list of installed shared libs. + +Building from a GIT checkout +---------------------------- + +The libvirt build process uses Meson build system. By default when the +``meson`` is run from within a GIT checkout, it will turn on -Werror for +builds. This can be disabled with --werror=false, but this is not +recommended. + +To build & install libvirt to your home directory the following commands +can be run: + +:: + + $ meson build --prefix=$HOME/usr + $ ninja -C build + $ sudo ninja -C build install + +Be aware though, that binaries built with a custom prefix will not +interoperate with OS vendor provided binaries, since the UNIX socket +paths will all be different. To produce a build that is compatible with +normal OS vendor prefixes, use + +:: + + $ meson build -Dsystem=true + $ ninja -C build + + +When doing this for day-to-day development purposes, it is recommended +not to install over the OS vendor provided binaries. Instead simply run +libvirt directly from the source tree. For example to run a privileged +libvirtd instance + +:: + + $ su - + # service libvirtd stop (or systemctl stop libvirtd.service) + # /home/to/your/checkout/build/src/libvirtd + + +It is also possible to run virsh directly from the build tree using the +./run script (which sets some environment variables): + +:: + + $ pwd + /home/to/your/checkout/build + $ ./run ./tools/virsh .... diff --git a/docs/meson.build b/docs/meson.build index f4b29a2e59..e816953bf4 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -34,7 +34,6 @@ docs_html_in_files = [ '404', 'bugs', 'cgroups', - 'compiling', 'contact', 'contribute', 'csharp', @@ -111,6 +110,7 @@ docs_rst_files = [ 'ci', 'coding-style', 'committer-guidelines', + 'compiling', 'daemons', 'developer-tooling', 'formatbackup', -- 2.29.2
On Fri, Mar 12, 2021 at 12:43:12 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/compiling.html.in | 115 ----------------------------------------- docs/compiling.rst | 95 ++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 96 insertions(+), 116 deletions(-) delete mode 100644 docs/compiling.html.in create mode 100644 docs/compiling.rst
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
On Fri, Mar 12, 2021 at 01:57:30PM +0100, Peter Krempa wrote:
On Fri, Mar 12, 2021 at 12:43:03 +0100, Erik Skultety wrote:
'#itsfriday'
For docs changes a good help for reviewers is to push to your private gitlab clone and provide a link to the artifacts of the 'webpage' job so that the output can be viewed easily.
Okay, I'll push patches 1-4 and 6,8,9 since the patches are independent and resolve the review comments for the rest in v2. Thanks, Erik
participants (2)
-
Erik Skultety -
Peter Krempa