[PATCH 11/12] docs: acl: Convert to 'rst'
Peter Krempa
pkrempa at redhat.com
Tue May 16 15:31:31 UTC 2023
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 at 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
More information about the libvir-list
mailing list