[PATCH 11/12] docs: acl: Convert to 'rst'

Peter Krempa posted 12 patches 1 year ago
[PATCH 11/12] docs: acl: Convert to 'rst'
Posted by Peter Krempa 1 year ago
The only special bit about the 'acl' page was the inclusion of the
objects and permissions tables. We can do that by the '.. raw::'
directive.

One reference from 'aclpolkit.rst' needed to be updated to go with the
new header anchor naming.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---
 docs/acl.html.in   | 101 ---------------------------------------------
 docs/acl.rst       |  76 ++++++++++++++++++++++++++++++++++
 docs/aclpolkit.rst |   2 +-
 docs/meson.build   |   3 +-
 4 files changed, 79 insertions(+), 103 deletions(-)
 delete mode 100644 docs/acl.html.in
 create mode 100644 docs/acl.rst

diff --git a/docs/acl.html.in b/docs/acl.html.in
deleted file mode 100644
index 268d3aebd3..0000000000
--- a/docs/acl.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>Client access control</h1>
-    <p>
-      Libvirt's client access control framework 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.
-    </p>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="intro">Access control introduction</a></h2>
-
-    <p>
-      In a default configuration, the libvirtd daemon has three levels
-      of access control. All connections start off in an unauthenticated
-      state, where the only API operations allowed are those required
-      to complete authentication. After successful authentication, a
-      connection either has full, unrestricted access to all libvirt
-      API calls, or is locked down to only "read only" (see 'Anonymous'
-      in the table below) operations,
-      according to what socket a client connection originated on.
-    </p>
-
-    <p>
-      The access control framework allows authenticated connections to
-      have fine grained permission rules to be defined by the administrator.
-      Every API call in libvirt has a set of permissions that will
-      be validated against the object being used. For example, the
-      <code>virDomainSetSchedulerParametersFlags</code> method will
-      check whether the client user has the <code>write</code>
-      permission on the <code>domain</code> object instance passed
-      in as a parameter. Further permissions will also be checked
-      if certain flags are set in the API call. In addition to
-      checks on the object passed in to an API call, some methods
-      will filter their results. For example the <code>virConnectListAllDomains</code>
-      method will check the <code>search_domains</code> on the <code>connect</code>
-      object, but will also filter the returned <code>domain</code>
-      objects to only those on which the client user has the
-      <code>getattr</code> permission.
-    </p>
-
-    <h2><a id="drivers">Access control drivers</a></h2>
-
-    <p>
-      The access control framework is designed as a pluggable
-      system to enable future integration with arbitrary access
-      control technologies. By default, the <code>none</code>
-      driver is used, which does no access control checks at
-      all. At this time, libvirt ships with support for using
-      <a href="https://www.freedesktop.org/wiki/Software/polkit/">polkit</a> as a real access
-      control driver. To learn how to use the polkit access
-      driver consult <a href="aclpolkit.html">the configuration
-      docs</a>.
-    </p>
-
-    <p>
-      The access driver is configured in the <code>libvirtd.conf</code>
-      configuration file, using the <code>access_drivers</code>
-      parameter. This parameter accepts an array of access control
-      driver names. If more than one access driver is requested,
-      then all must succeed in order for access to be granted.
-      To enable 'polkit' as the driver:
-    </p>
-
-    <pre>
-# augtool -s set '/files/etc/libvirt/libvirtd.conf/access_drivers[1]' polkit
-    </pre>
-
-    <p>
-      And to reset back to the default (no-op) driver
-    </p>
-
-
-    <pre>
-# augtool -s rm /files/etc/libvirt/libvirtd.conf/access_drivers
-    </pre>
-
-    <p>
-      <strong>Note:</strong> changes to libvirtd.conf require that
-      the libvirtd daemon be restarted.
-    </p>
-
-    <h2><a id="perms">Objects and permissions</a></h2>
-
-    <p>
-      Libvirt applies access control to all the main object
-      types in its API. Each object type, in turn, has a set
-      of permissions defined. To determine what permissions
-      are checked for specific API call, consult the
-      <a href="html/index.html">API reference manual</a>
-      documentation for the API in question.
-    </p>
-
-    <div id="include" filename="aclperms.htmlinc"/>
-
-  </body>
-</html>
diff --git a/docs/acl.rst b/docs/acl.rst
new file mode 100644
index 0000000000..06c248333f
--- /dev/null
+++ b/docs/acl.rst
@@ -0,0 +1,76 @@
+=====================
+Client access control
+=====================
+
+Libvirt's client access control framework 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.
+
+.. contents::
+
+Access control introduction
+---------------------------
+
+In a default configuration, the libvirtd daemon has three levels of access
+control. All connections start off in an unauthenticated state, where the only
+API operations allowed are those required to complete authentication. After
+successful authentication, a connection either has full, unrestricted access to
+all libvirt API calls, or is locked down to only "read only" (see 'Anonymous' in
+the table below) operations, according to what socket a client connection
+originated on.
+
+The access control framework allows authenticated connections to have fine
+grained permission rules to be defined by the administrator. Every API call in
+libvirt has a set of permissions that will be validated against the object being
+used. For example, the ``virDomainSetSchedulerParametersFlags`` method will
+check whether the client user has the ``write`` permission on the ``domain``
+object instance passed in as a parameter. Further permissions will also be
+checked if certain flags are set in the API call. In addition to checks on the
+object passed in to an API call, some methods will filter their results. For
+example the ``virConnectListAllDomains`` method will check the
+``search_domains`` on the ``connect`` object, but will also filter the returned
+``domain`` objects to only those on which the client user has the ``getattr``
+permission.
+
+Access control drivers
+----------------------
+
+The access control framework is designed as a pluggable system to enable future
+integration with arbitrary access control technologies. By default, the ``none``
+driver is used, which does no access control checks at all. At this time,
+libvirt ships with support for using
+`polkit <https://www.freedesktop.org/wiki/Software/polkit/>`__ as a real access
+control driver. To learn how to use the polkit access driver consult `the
+configuration docs <aclpolkit.html>`__.
+
+The access driver is configured in the ``libvirtd.conf`` configuration file,
+using the ``access_drivers`` parameter. This parameter accepts an array of
+access control driver names. If more than one access driver is requested, then
+all must succeed in order for access to be granted. To enable 'polkit' as the
+driver:
+
+::
+
+   # augtool -s set '/files/etc/libvirt/libvirtd.conf/access_drivers[1]' polkit
+
+And to reset back to the default (no-op) driver
+
+::
+
+   # augtool -s rm /files/etc/libvirt/libvirtd.conf/access_drivers
+
+**Note:** changes to libvirtd.conf require that the libvirtd daemon be
+restarted.
+
+Objects and permissions
+-----------------------
+
+Libvirt applies access control to all the main object types in its API. Each
+object type, in turn, has a set of permissions defined. To determine what
+permissions are checked for specific API call, consult the `API reference
+manual <html/index.html>`__ documentation for the API in question.
+
+.. raw:: html
+
+   <div id="include" filename="aclperms.htmlinc"/>
diff --git a/docs/aclpolkit.rst b/docs/aclpolkit.rst
index 09e5d9ea27..07f4735001 100644
--- a/docs/aclpolkit.rst
+++ b/docs/aclpolkit.rst
@@ -26,7 +26,7 @@ the operations a user may perform on an object.
 Permission names
 ----------------

-The libvirt `object names and permission names <acl.html#perms>`__ are
+The libvirt `object names and permission names <acl.html#objects-and-permissions>`__ are
 mapped onto polkit action names using the simple pattern:

 ::
diff --git a/docs/meson.build b/docs/meson.build
index 68359be0b4..8edb93333a 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -248,7 +248,8 @@ endforeach

 html_xslt_gen += {
   'name': 'acl',
-  'source': 'docs' / 'acl.html.in',
+  'file': docs_rst2html5_gen.process('acl.rst'),
+  'source': 'docs' / 'acl.rst',
   'depends': aclperms_gen,
 }

-- 
2.40.1