mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 13:45:38 +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
|
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:
|
mapped onto polkit action names using the simple pattern:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|||||||
@ -248,7 +248,8 @@ endforeach
|
|||||||
|
|
||||||
html_xslt_gen += {
|
html_xslt_gen += {
|
||||||
'name': 'acl',
|
'name': 'acl',
|
||||||
'source': 'docs' / 'acl.html.in',
|
'file': docs_rst2html5_gen.process('acl.rst'),
|
||||||
|
'source': 'docs' / 'acl.rst',
|
||||||
'depends': aclperms_gen,
|
'depends': aclperms_gen,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user