mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-21 21:25:25 +00:00
docs: acl: Convert to 'rst'
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> Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
Peter Krempa
parent
0f1d6ef6e7
commit
c0a06c081c
101
docs/acl.html.in
101
docs/acl.html.in
@ -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>
|
||||
76
docs/acl.rst
Normal file
76
docs/acl.rst
Normal file
@ -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"/>
|
||||
@ -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:
|
||||
|
||||
::
|
||||
|
||||
@ -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,
|
||||
}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user