mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-06 18:05:45 +00:00
da13f2c70c
This adds two new pages to the website, acl.html describing the general access control framework and permissions models, and aclpolkit.html describing the use of polkit as an access control driver. page.xsl is modified to support a new syntax <div id="include" filename="somefile.htmlinc"/> which will cause the XSL transform to replace that <div> with the contents of 'somefile.htmlinc'. We use this in the acl.html.in file, to pull the table of permissions for each libvirt object. This table is autogenerated from the enums in src/access/viraccessperms.h by the genaclperms.pl script. newapi.xsl is modified so that the list of permissions checks shown against each API will link to the description of the permissions in acl.html Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
101 lines
3.9 KiB
XML
101 lines
3.9 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<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 name="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" 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 name="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="http://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 name="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/libvirt-libvirt.html">API reference manual</a>
|
|
documentation for the API in question.
|
|
</p>
|
|
|
|
<div id="include" filename="aclperms.htmlinc"/>
|
|
|
|
</body>
|
|
</html>
|