docs: Enhance polkit documentation to describe secondary connection

https://bugzilla.redhat.com/show_bug.cgi?id=1631606

Since commit 8259255 usage of a primary connection driver for
a virConnect has been modified to open (virConnectOpen) and use
a connection to the specific driver in order to handle the API
calls to/for that driver. This causes some confusion and issues
for ACL polkit rule scripts to know exactly which driver by
name will be used.

Add some documentation describing the processing of the primary
and secondary connection as well as the list of the connect_driver
names used for each driver.

Signed-off-by: John Ferlan <jferlan@redhat.com>
ACKed-by: Michal Privoznik <mprivozn@redhat.com>

diff --git a/docs/aclpolkit.html.in b/docs/aclpolkit.html.in
index ee00b984616726572d0703465d22da4cc07ec768..ac54f125dad1cdf4f7f249d8bee6f1959a5510cf 100644 (file)
--- a/docs/aclpolkit.html.in
+++ b/docs/aclpolkit.html.in
@@ -287,6 +287,123 @@
       </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 class="acl">
+      <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>libxl</td>
+          <td>xenlight</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>phyp</td>
+          <td>PHYP</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>uml</td>
+          <td>UML</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>
+        <tr>
+          <td>xenapi</td>
+          <td>XenAPI</td>
+        </tr>
+      </tbody>
+    </table>
+
 
     <h2><a id="user">User identity attributes</a></h2>
 

diff --git a/docs/libvirt.css b/docs/libvirt.css
index b2ed33926a36b3c820a75982bd49d2030992d360..e590b33cfb9ab1264e0ec654e12bb4e92bad1456 100644 (file)
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -393,6 +393,7 @@ table.acl {
 
 table.acl tr, table.acl td {
     padding: 0.3em;
+    border: 1px solid #ccc;
 }
 
 table.acl thead {