mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-24 22:55:23 +00:00
b1c81567c7
The HTML5 doctype is simply <!DOCTYPE html> no DTD is present because HTML5 is no longer defined as an extension of SGML. XSL has no way to natively output a doctype without a public or system identifier, so we have to use an <xsl:text> hack instead. See also https://dev.w3.org/html5/html-author/#doctype-declaration Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
419 lines
13 KiB
XML
419 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<body>
|
|
<h1>Polkit access control</h1>
|
|
|
|
<p>
|
|
Libvirt's client <a href="acl.html">access control framework</a> 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. The polkit driver
|
|
provides a simple implementation of the access control framework.
|
|
</p>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<h2><a id="intro">Introduction</a></h2>
|
|
|
|
<p>
|
|
A default install of libvirt will typically use
|
|
<a href="http://www.freedesktop.org/wiki/Software/polkit/">polkit</a>
|
|
to authenticate the initial user connection to libvirtd. This is a
|
|
very coarse grained check though, either allowing full read-write
|
|
access to all APIs, or just read-only access. The polkit access
|
|
control driver in libvirt builds on this capability to allow for
|
|
fine grained control over the operations a user may perform on an
|
|
object.
|
|
</p>
|
|
|
|
<h2><a id="perms">Permission names</a></h2>
|
|
|
|
<p>
|
|
The libvirt <a href="acl.html#perms">object names and permission names</a>
|
|
are mapped onto polkit action names using the simple pattern:
|
|
</p>
|
|
|
|
<pre>org.libvirt.api.$object.$permission
|
|
</pre>
|
|
|
|
<p>
|
|
The only caveat is that any underscore characters in the
|
|
object or permission names are converted to hyphens. So,
|
|
for example, the <code>search_storage_vols</code> permission
|
|
on the <code>storage_pool</code> object maps to the polkit
|
|
action:
|
|
</p>
|
|
<pre>org.libvirt.api.storage-pool.search-storage-vols
|
|
</pre>
|
|
|
|
<p>
|
|
The default policy for any permission which corresponds to
|
|
a "read only" operation, is to allow access. All other
|
|
permissions default to deny access.
|
|
</p>
|
|
|
|
<h2><a id="attrs">Object identity attributes</a></h2>
|
|
|
|
<p>
|
|
To allow polkit authorization rules to be written to match
|
|
against individual object instances, libvirt provides a number
|
|
of authorization detail attributes when performing a permission
|
|
check. The set of attributes varies according to the type
|
|
of object being checked
|
|
</p>
|
|
|
|
<h3><a id="object_connect">virConnectPtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a id="object_domain">virDomainPtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
<tr>
|
|
<td>domain_name</td>
|
|
<td>Name of the domain, unique to the local host</td>
|
|
</tr>
|
|
<tr>
|
|
<td>domain_uuid</td>
|
|
<td>UUID of the domain, globally unique</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a id="object_interface">virInterfacePtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
<tr>
|
|
<td>interface_name</td>
|
|
<td>Name of the network interface, unique to the local host</td>
|
|
</tr>
|
|
<tr>
|
|
<td>interface_macaddr</td>
|
|
<td>MAC address of the network interface, not unique</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a id="object_network">virNetworkPtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
<tr>
|
|
<td>network_name</td>
|
|
<td>Name of the network, unique to the local host</td>
|
|
</tr>
|
|
<tr>
|
|
<td>network_uuid</td>
|
|
<td>UUID of the network, globally unique</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a id="object_node_device">virNodeDevicePtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
<tr>
|
|
<td>node_device_name</td>
|
|
<td>Name of the node device, unique to the local host</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a id="object_nwfilter">virNWFilterPtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
<tr>
|
|
<td>nwfilter_name</td>
|
|
<td>Name of the network filter, unique to the local host</td>
|
|
</tr>
|
|
<tr>
|
|
<td>nwfilter_uuid</td>
|
|
<td>UUID of the network filter, globally unique</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a id="object_secret">virSecretPtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
<tr>
|
|
<td>secret_uuid</td>
|
|
<td>UUID of the secret, globally unique</td>
|
|
</tr>
|
|
<tr>
|
|
<td>secret_usage_volume</td>
|
|
<td>Name of the associated volume, if any</td>
|
|
</tr>
|
|
<tr>
|
|
<td>secret_usage_ceph</td>
|
|
<td>Name of the associated Ceph server, if any</td>
|
|
</tr>
|
|
<tr>
|
|
<td>secret_usage_target</td>
|
|
<td>Name of the associated iSCSI target, if any</td>
|
|
</tr>
|
|
<tr>
|
|
<td>secret_usage_name</td>
|
|
<td>Name of the associated TLS secret, if any</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a id="object_storage_pool">virStoragePoolPtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
<tr>
|
|
<td>pool_name</td>
|
|
<td>Name of the storage pool, unique to the local host</td>
|
|
</tr>
|
|
<tr>
|
|
<td>pool_uuid</td>
|
|
<td>UUID of the storage pool, globally unique</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a id="object_storage_vol">virStorageVolPtr</a></h3>
|
|
<table class="acl">
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>connect_driver</td>
|
|
<td>Name of the libvirt connection driver</td>
|
|
</tr>
|
|
<tr>
|
|
<td>pool_name</td>
|
|
<td>Name of the storage pool, unique to the local host</td>
|
|
</tr>
|
|
<tr>
|
|
<td>pool_uuid</td>
|
|
<td>UUID of the storage pool, globally unique</td>
|
|
</tr>
|
|
<tr>
|
|
<td>vol_name</td>
|
|
<td>Name of the storage volume, unique to the pool</td>
|
|
</tr>
|
|
<tr>
|
|
<td>vol_key</td>
|
|
<td>Key of the storage volume, globally unique</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<h2><a id="user">User identity attributes</a></h2>
|
|
|
|
<p>
|
|
At this point in time, the only attribute provided by
|
|
libvirt to identify the user invoking the operation
|
|
is the PID of the client program. This means that the
|
|
polkit access control driver is only useful if connections
|
|
to libvirt are restricted to its UNIX domain socket. If
|
|
connections are being made to a TCP socket, no identifying
|
|
information is available and access will be denied.
|
|
Also note that if the client is connecting via an SSH
|
|
tunnel, it is the local SSH user that will be identified.
|
|
In future versions, it is expected that more information
|
|
about the client user will be provided, including the
|
|
SASL / Kerberos username and/or x509 distinguished
|
|
name obtained from the authentication provider in use.
|
|
</p>
|
|
|
|
|
|
<h2><a id="checks">Writing access control policies</a></h2>
|
|
|
|
<p>
|
|
If using versions of polkit prior to 0.106 then it is only
|
|
possible to validate (user, permission) pairs via the <code>.pkla</code>
|
|
files. Fully validation of the (user, permission, object) triple
|
|
requires the new JavaScript <code>.rules</code> support that
|
|
was introduced in version 0.106. The latter is what will be
|
|
described here.
|
|
</p>
|
|
|
|
<p>
|
|
Libvirt does not ship any rules files by default. It merely
|
|
provides a definition of the default behaviour for each
|
|
action (permission). As noted earlier, permissions which
|
|
correspond to read-only operations in libvirt will be allowed
|
|
to all users by default; everything else is denied by default.
|
|
Defining custom rules requires creation of a file in the
|
|
<code>/etc/polkit-1/rules.d</code> directory with a name
|
|
chosen by the administrator (<code>100-libvirt-acl.rules</code>
|
|
would be a reasonable choice). See the <code>polkit(8)</code>
|
|
manual page for a description of how to write these files
|
|
in general. The key idea is to create a file containing
|
|
something like
|
|
</p>
|
|
|
|
<pre>
|
|
polkit.addRule(function(action, subject) {
|
|
....logic to check 'action' and 'subject'...
|
|
});
|
|
</pre>
|
|
|
|
<p>
|
|
In this code snippet above, the <code>action</code> object
|
|
instance will represent the libvirt permission being checked
|
|
along with identifying attributes for the object it is being
|
|
applied to. The <code>subject</code> meanwhile will identify
|
|
the libvirt client app (with the caveat above about it only
|
|
dealing with local clients connected via the UNIX socket).
|
|
On the <code>action</code> object, the permission name is
|
|
accessible via the <code>id</code> attribute, while the
|
|
object identifying attributes are exposed via the
|
|
<code>lookup</code> method.
|
|
</p>
|
|
|
|
<p>
|
|
See
|
|
<a href="http://libvirt.org/git/?p=libvirt.git;a=tree;f=examples/polkit;hb=HEAD">source code</a>
|
|
for a more complex example.
|
|
</p>
|
|
|
|
<h3><a id="exconnect">Example: restricting ability to connect to drivers</a></h3>
|
|
|
|
<p>
|
|
Consider a local user <code>berrange</code>
|
|
who has been granted permission to connect to libvirt in
|
|
full read-write mode. The goal is to only allow them to
|
|
use the <code>QEMU</code> driver and not the Xen or LXC
|
|
drivers which are also available in libvirtd.
|
|
To achieve this we need to write a rule which checks
|
|
whether the <code>connect_driver</code> attribute
|
|
is <code>QEMU</code>, and match on an action
|
|
name of <code>org.libvirt.api.connect.getattr</code>. Using
|
|
the javascript rules format, this ends up written as
|
|
</p>
|
|
|
|
<pre>
|
|
polkit.addRule(function(action, subject) {
|
|
if (action.id == "org.libvirt.api.connect.getattr" &&
|
|
subject.user == "berrange") {
|
|
if (action.lookup("connect_driver") == 'QEMU') {
|
|
return polkit.Result.YES;
|
|
} else {
|
|
return polkit.Result.NO;
|
|
}
|
|
}
|
|
});
|
|
</pre>
|
|
|
|
<h3><a id="exdomain">Example: restricting access to a single domain</a></h3>
|
|
|
|
<p>
|
|
Consider a local user <code>berrange</code>
|
|
who has been granted permission to connect to libvirt in
|
|
full read-write mode. The goal is to only allow them to
|
|
see the domain called <code>demo</code> on the LXC driver.
|
|
To achieve this we need to write a rule which checks
|
|
whether the <code>connect_driver</code> attribute
|
|
is <code>LXC</code> and the <code>domain_name</code>
|
|
attribute is <code>demo</code>, and match on a action
|
|
name of <code>org.libvirt.api.domain.getattr</code>. Using
|
|
the javascript rules format, this ends up written as
|
|
</p>
|
|
|
|
<pre>
|
|
polkit.addRule(function(action, subject) {
|
|
if (action.id == "org.libvirt.api.domain.getattr" &&
|
|
subject.user == "berrange") {
|
|
if (action.lookup("connect_driver") == 'LXC' &&
|
|
action.lookup("domain_name") == 'demo') {
|
|
return polkit.Result.YES;
|
|
} else {
|
|
return polkit.Result.NO;
|
|
}
|
|
}
|
|
});
|
|
</pre>
|
|
</body>
|
|
</html>
|