5:43 a.m.
'#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
5:43 a.m.
New subject: [libvirt PATCH 1/9] docs: html.in: Convert aclpolkit to rst
Signed-off-by: Erik Skultety <eskultet(a)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/">pol...
- 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/polk...
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
5:27 a.m.
New subject: [libvirt PATCH 1/9] docs: html.in: Convert aclpolkit to rst
On Fri, Mar 12, 2021 at 12:43:04 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet(a)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(a)redhat.com>
5:43 a.m.
New subject: [libvirt PATCH 2/9] docs: html.in: Convert api_extension to rst
Signed-off-by: Erik Skultety <eskultet(a)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.or...
- </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
5:30 a.m.
New subject: [libvirt PATCH 2/9] docs: html.in: Convert api_extension to rst
On Fri, Mar 12, 2021 at 12:43:05 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet(a)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(a)redhat.com>
5:43 a.m.
New subject: [libvirt PATCH 3/9] docs: html.in: Convert api to rst
There were a number of occurrences where we used nested inline markup
(verbatim + refs) which is currently not possible with RST syntax [1].
There is a possible workaround involving substitution definitions like
.. |virConnectPtr| replace:: ``virConnectPtr``
.. _virConnectPtr: /html/libvirt-libvirt-host.html#virConnectPtr
Substitutions cannot be made generic, hence we cannot create a template
for substitution and use a single template everywhere, so we'd end up
with a lot of clutter and convolution. Therefore, we can make an
exception and just link the data type without further style markup.
[1] https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible
Signed-off-by: Erik Skultety <eskultet(a)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
5:32 a.m.
New subject: [libvirt PATCH 3/9] docs: html.in: Convert api to rst
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(a)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(a)redhat.com>
5:43 a.m.
New subject: [libvirt PATCH 4/9] docs: html.in: Convert apps to rst
Signed-off-by: Erik Skultety <eskultet(a)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<...
- <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></...
- <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&l...
- <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-wha...
- </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></...
- <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-l...
- <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...
- <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&...
- <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-...
- <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...
- <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...
- <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<...
- <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></...
- <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></d...
- <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&l...
- <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">Che...
- <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>&l...
- <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&l...
- <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">Muni...
- <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-...
- <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=e...
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....
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...
- <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&g...
- <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.htm...
+ 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/Ti...
+ 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=/...
+ 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
5:34 a.m.
New subject: [libvirt PATCH 4/9] docs: html.in: Convert apps to rst
On Fri, Mar 12, 2021 at 12:43:07 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet(a)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(a)redhat.com>
5:43 a.m.
New subject: [libvirt PATCH 5/9] docs: html.in: Convert architecture to rst
Signed-off-by: Erik Skultety <eskultet(a)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
6:56 a.m.
New subject: [libvirt PATCH 5/9] docs: html.in: Convert architecture to rst
On Fri, Mar 12, 2021 at 12:43:08 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet(a)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.
5:38 a.m.
New subject: [libvirt PATCH 5/9] docs: html.in: Convert architecture to rst
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(a)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.
5:43 a.m.
New subject: [libvirt PATCH 6/9] docs: html.in: Convert auditlog to rst
Signed-off-by: Erik Skultety <eskultet(a)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
5:39 a.m.
New subject: [libvirt PATCH 6/9] docs: html.in: Convert auditlog to rst
On Fri, Mar 12, 2021 at 12:43:09 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet(a)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(a)redhat.com>
5:43 a.m.
New subject: [libvirt PATCH 7/9] docs: html.in: Convert auth to rst
Signed-off-by: Erik Skultety <eskultet(a)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(a)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(a)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(a)EXAMPLE.COM":
-Re-enter password for principal "libvirt/foo.example.com(a)EXAMPLE.COM":
-Principal "libvirt/foo.example.com(a)EXAMPLE.COM" created.
-
-kadmin.local: ktadd -k /root/libvirt-foo-example.tab
libvirt/foo.example.com(a)EXAMPLE.COM
-Entry for principal libvirt/foo.example.com(a)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(a)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(a)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(a)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(a)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(a)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(a)EXAMPLE.COM":
+ Re-enter password for principal "libvirt/foo.example.com(a)EXAMPLE.COM":
+ Principal "libvirt/foo.example.com(a)EXAMPLE.COM" created.
+
+ kadmin.local: ktadd -k /root/libvirt-foo-example.tab
libvirt/foo.example.com(a)EXAMPLE.COM
+ Entry for principal libvirt/foo.example.com(a)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(a)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(a)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(a)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
6:54 a.m.
New subject: [libvirt PATCH 7/9] docs: html.in: Convert auth to rst
On Fri, Mar 12, 2021 at 12:43:10 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet(a)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.
5:43 a.m.
New subject: [libvirt PATCH 8/9] docs: html.in: Convert bindings to rst
Signed-off-by: Erik Skultety <eskultet(a)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<...
- 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&quo...
- 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/">...
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
5:42 a.m.
New subject: [libvirt PATCH 8/9] docs: html.in: Convert bindings to rst
On Fri, Mar 12, 2021 at 12:43:11 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet(a)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(a)redhat.com>
5:43 a.m.
New subject: [libvirt PATCH 9/9] docs: html.in: Convert 'compiling' to rst
Signed-off-by: Erik Skultety <eskultet(a)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
5:43 a.m.
New subject: [libvirt PATCH 9/9] docs: html.in: Convert 'compiling' to rst
On Fri, Mar 12, 2021 at 12:43:12 +0100, Erik Skultety wrote:
Signed-off-by: Erik Skultety <eskultet(a)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(a)redhat.com>
11:46 a.m.
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
1348
days inactive
1351
days old
21 comments
2 participants
participants (2)
-
Erik Skultety -
Peter Krempa