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@xxxxxxxxxx> --- 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
