[libvirt PATCH 1/9] docs: html.in: Convert aclpolkit to rst

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Erik Skultety <eskultet@xxxxxxxxxx>
---
 docs/aclpolkit.html.in | 523 -----------------------------------------
 docs/aclpolkit.rst     | 310 ++++++++++++++++++++++++
 docs/meson.build       |   2 +-
 3 files changed, 311 insertions(+), 524 deletions(-)
 delete mode 100644 docs/aclpolkit.html.in
 create mode 100644 docs/aclpolkit.rst

diff --git a/docs/aclpolkit.html.in b/docs/aclpolkit.html.in
deleted file mode 100644
index a82001187e..0000000000
--- a/docs/aclpolkit.html.in
+++ /dev/null
@@ -1,523 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml";>
-  <body>
-    <h1>Polkit access control</h1>
-
-    <p>
-      Libvirt's client <a href="acl.html">access control framework</a> allows
-      administrators to setup fine grained permission rules across client users,
-      managed objects and API operations. This allows client connections
-      to be locked down to a minimal set of privileges. The polkit driver
-      provides a simple implementation of the access control framework.
-    </p>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="intro">Introduction</a></h2>
-
-    <p>
-      A default install of libvirt will typically use
-      <a href="https://www.freedesktop.org/wiki/Software/polkit/";>polkit</a>
-      to authenticate the initial user connection to libvirtd. This is a
-      very coarse grained check though, either allowing full read-write
-      access to all APIs, or just read-only access. The polkit access
-      control driver in libvirt builds on this capability to allow for
-      fine grained control over the operations a user may perform on an
-      object.
-    </p>
-
-    <h2><a id="perms">Permission names</a></h2>
-
-    <p>
-      The libvirt <a href="acl.html#perms">object names and permission names</a>
-      are mapped onto polkit action names using the simple pattern:
-    </p>
-
-    <pre>org.libvirt.api.$object.$permission
-</pre>
-
-    <p>
-      The only caveat is that any underscore characters in the
-      object or permission names are converted to hyphens. So,
-      for example, the <code>search_storage_vols</code> permission
-      on the <code>storage_pool</code> object maps to the polkit
-      action:
-    </p>
-    <pre>org.libvirt.api.storage-pool.search-storage-vols
-</pre>
-
-    <p>
-      The default policy for any permission which corresponds to
-      a "read only" operation, is to allow access. All other
-      permissions default to deny access.
-    </p>
-
-    <h2><a id="attrs">Object identity attributes</a></h2>
-
-    <p>
-      To allow polkit authorization rules to be written to match
-      against individual object instances, libvirt provides a number
-      of authorization detail attributes when performing a permission
-      check. The set of attributes varies according to the type
-      of object being checked
-    </p>
-
-    <h3><a id="object_connect">virConnectPtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h3><a id="object_domain">virDomainPtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-        <tr>
-          <td>domain_name</td>
-          <td>Name of the domain, unique to the local host</td>
-        </tr>
-        <tr>
-          <td>domain_uuid</td>
-          <td>UUID of the domain, globally unique</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h3><a id="object_interface">virInterfacePtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-        <tr>
-          <td>interface_name</td>
-          <td>Name of the network interface, unique to the local host</td>
-        </tr>
-        <tr>
-          <td>interface_macaddr</td>
-          <td>MAC address of the network interface, not unique</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h3><a id="object_network">virNetworkPtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-        <tr>
-          <td>network_name</td>
-          <td>Name of the network, unique to the local host</td>
-        </tr>
-        <tr>
-          <td>network_uuid</td>
-          <td>UUID of the network, globally unique</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h3><a id="object_node_device">virNodeDevicePtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-        <tr>
-          <td>node_device_name</td>
-          <td>Name of the node device, unique to the local host</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h3><a id="object_nwfilter">virNWFilterPtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-        <tr>
-          <td>nwfilter_name</td>
-          <td>Name of the network filter, unique to the local host</td>
-        </tr>
-        <tr>
-          <td>nwfilter_uuid</td>
-          <td>UUID of the network filter, globally unique</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h3><a id="object_secret">virSecretPtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-        <tr>
-          <td>secret_uuid</td>
-          <td>UUID of the secret, globally unique</td>
-        </tr>
-        <tr>
-          <td>secret_usage_volume</td>
-          <td>Name of the associated volume, if any</td>
-        </tr>
-        <tr>
-          <td>secret_usage_ceph</td>
-          <td>Name of the associated Ceph server, if any</td>
-        </tr>
-        <tr>
-          <td>secret_usage_target</td>
-          <td>Name of the associated iSCSI target, if any</td>
-        </tr>
-        <tr>
-          <td>secret_usage_name</td>
-          <td>Name of the associated TLS secret, if any</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h3><a id="object_storage_pool">virStoragePoolPtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-        <tr>
-          <td>pool_name</td>
-          <td>Name of the storage pool, unique to the local host</td>
-        </tr>
-        <tr>
-          <td>pool_uuid</td>
-          <td>UUID of the storage pool, globally unique</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h3><a id="object_storage_vol">virStorageVolPtr</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Attribute</th>
-          <th>Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>connect_driver</td>
-          <td>Name of the libvirt connection driver</td>
-        </tr>
-        <tr>
-          <td>pool_name</td>
-          <td>Name of the storage pool, unique to the local host</td>
-        </tr>
-        <tr>
-          <td>pool_uuid</td>
-          <td>UUID of the storage pool, globally unique</td>
-        </tr>
-        <tr>
-          <td>vol_name</td>
-          <td>Name of the storage volume, unique to the pool</td>
-        </tr>
-        <tr>
-          <td>vol_key</td>
-          <td>Key of the storage volume, globally unique</td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h2><a id="connect_driver">Hypervisor Driver connect_driver</a></h2>
-    <p>
-      The <code>connect_driver</code> parameter describes the
-      client's <a href="remote.html">remote Connection Driver</a>
-      name based on the <a href="uri.html">URI</a> used for the
-      connection.
-    </p>
-    <p>
-      <span class="since">Since 4.1.0</span>, when calling an API
-      outside the scope of the primary connection driver, the
-      primary driver will attempt to open a secondary connection
-      to the specific API driver in order to process the API. For
-      example, when hypervisor domain processing needs to make an
-      API call within the storage driver or the network filter driver
-      an attempt to open a connection to the "storage" or "nwfilter"
-      driver will be made. Similarly, a "storage" primary connection
-      may need to create a connection to the "secret" driver in order
-      to process secrets for the API. If successful, then calls to
-      those API's will occur in the <code>connect_driver</code> context
-      of the secondary connection driver rather than in the context of
-      the primary driver. This affects the <code>connect_driver</code>
-      returned from rule generation from the <code>action.loookup</code>
-      function. The following table provides a list of the various
-      connection drivers and the <code>connect_driver</code> name
-      used by each regardless of primary or secondary connection.
-      The access denied error message from libvirt will list the
-      connection driver by name that denied the access.
-    </p>
-
-    <h3><a id="object_connect_driver">Connection Driver Name</a></h3>
-    <table>
-      <thead>
-        <tr>
-          <th>Connection Driver</th>
-          <th><code>connect_driver</code> name</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>bhyve</td>
-          <td>bhyve</td>
-        </tr>
-        <tr>
-          <td>esx</td>
-          <td>ESX</td>
-        </tr>
-        <tr>
-          <td>hyperv</td>
-          <td>Hyper-V</td>
-        </tr>
-        <tr>
-          <td>interface</td>
-          <td>interface</td>
-        </tr>
-        <tr>
-          <td>xen</td>
-          <td>Xen</td>
-        </tr>
-        <tr>
-          <td>lxc</td>
-          <td>LXC</td>
-        </tr>
-        <tr>
-          <td>network</td>
-          <td>network</td>
-        </tr>
-        <tr>
-          <td>nodedev</td>
-          <td>nodedev</td>
-        </tr>
-        <tr>
-          <td>nwfilter</td>
-          <td>NWFilter</td>
-        </tr>
-        <tr>
-          <td>openvz</td>
-          <td>OPENVZ</td>
-        </tr>
-        <tr>
-          <td>qemu</td>
-          <td>QEMU</td>
-        </tr>
-        <tr>
-          <td>secret</td>
-          <td>secret</td>
-        </tr>
-        <tr>
-          <td>storage</td>
-          <td>storage</td>
-        </tr>
-        <tr>
-          <td>vbox</td>
-          <td>VBOX</td>
-        </tr>
-        <tr>
-          <td>vmware</td>
-          <td>VMWARE</td>
-        </tr>
-        <tr>
-          <td>vz</td>
-          <td>vz</td>
-        </tr>
-      </tbody>
-    </table>
-
-
-    <h2><a id="user">User identity attributes</a></h2>
-
-    <p>
-      At this point in time, the only attribute provided by
-      libvirt to identify the user invoking the operation
-      is the PID of the client program. This means that the
-      polkit access control driver is only useful if connections
-      to libvirt are restricted to its UNIX domain socket. If
-      connections are being made to a TCP socket, no identifying
-      information is available and access will be denied.
-      Also note that if the client is connecting via an SSH
-      tunnel, it is the local SSH user that will be identified.
-      In future versions, it is expected that more information
-      about the client user will be provided, including the
-      SASL / Kerberos username and/or x509 distinguished
-      name obtained from the authentication provider in use.
-    </p>
-
-
-    <h2><a id="checks">Writing access control policies</a></h2>
-
-    <p>
-      If using versions of polkit prior to 0.106 then it is only
-      possible to validate (user, permission) pairs via the <code>.pkla</code>
-      files. Fully validation of the (user, permission, object) triple
-      requires the new JavaScript <code>.rules</code> support that
-      was introduced in version 0.106. The latter is what will be
-      described here.
-    </p>
-
-    <p>
-      Libvirt does not ship any rules files by default. It merely
-      provides a definition of the default behaviour for each
-      action (permission). As noted earlier, permissions which
-      correspond to read-only operations in libvirt will be allowed
-      to all users by default; everything else is denied by default.
-      Defining custom rules requires creation of a file in the
-      <code>/etc/polkit-1/rules.d</code> directory with a name
-      chosen by the administrator (<code>100-libvirt-acl.rules</code>
-      would be a reasonable choice). See the <code>polkit(8)</code>
-      manual page for a description of how to write these files
-      in general. The key idea is to create a file containing
-      something like
-    </p>
-
-    <pre>
-polkit.addRule(function(action, subject) {
-  ....logic to check 'action' and 'subject'...
-});
-    </pre>
-
-    <p>
-      In this code snippet above, the <code>action</code> object
-      instance will represent the libvirt permission being checked
-      along with identifying attributes for the object it is being
-      applied to. The <code>subject</code> meanwhile will identify
-      the libvirt client app (with the caveat above about it only
-      dealing with local clients connected via the UNIX socket).
-      On the <code>action</code> object, the permission name is
-      accessible via the <code>id</code> attribute, while the
-      object identifying attributes are exposed via the
-      <code>lookup</code> method.
-    </p>
-
-    <p>
-    See
-    <a href="https://gitlab.com/libvirt/libvirt/-/tree/master/examples/polkit";>source code</a>
-    for a more complex example.
-    </p>
-
-    <h3><a id="exconnect">Example: restricting ability to connect to drivers</a></h3>
-
-    <p>
-      Consider a local user <code>berrange</code>
-      who has been granted permission to connect to libvirt in
-      full read-write mode. The goal is to only allow them to
-      use the <code>QEMU</code> driver and not the Xen or LXC
-      drivers which are also available in libvirtd.
-      To achieve this we need to write a rule which checks
-      whether the <code>connect_driver</code> attribute
-      is <code>QEMU</code>, and match on an action
-      name of <code>org.libvirt.api.connect.getattr</code>. Using
-      the javascript rules format, this ends up written as
-    </p>
-
-    <pre>
-polkit.addRule(function(action, subject) {
-    if (action.id == "org.libvirt.api.connect.getattr" &amp;&amp;
-        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" &amp;&amp;
-        subject.user == "berrange") {
-          if (action.lookup("connect_driver") == 'LXC' &amp;&amp;
-              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




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux