|
 |
43fe83 |
From bdb62336234cc454d7c5b1e539ad764984c946e2 Mon Sep 17 00:00:00 2001
|
|
|
43fe83 |
Message-Id: <bdb62336234cc454d7c5b1e539ad764984c946e2.1377873638.git.jdenemar@redhat.com>
|
|
|
43fe83 |
From: "Daniel P. Berrange" <berrange@redhat.com>
|
|
|
43fe83 |
Date: Tue, 13 Aug 2013 11:38:28 +0100
|
|
|
43fe83 |
Subject: [PATCH] Add documentation for access control system
|
|
|
43fe83 |
|
|
|
43fe83 |
For https://bugzilla.redhat.com/show_bug.cgi?id=700443
|
|
|
43fe83 |
|
|
|
43fe83 |
This adds two new pages to the website, acl.html describing
|
|
|
43fe83 |
the general access control framework and permissions models,
|
|
|
43fe83 |
and aclpolkit.html describing the use of polkit as an
|
|
|
43fe83 |
access control driver.
|
|
|
43fe83 |
|
|
|
43fe83 |
page.xsl is modified to support a new syntax
|
|
|
43fe83 |
|
|
|
43fe83 |
|
|
|
43fe83 |
|
|
|
43fe83 |
which will cause the XSL transform to replace that
|
|
|
43fe83 |
with the contents of 'somefile.htmlinc'. We use this in
|
|
|
43fe83 |
the acl.html.in file, to pull the table of permissions
|
|
|
43fe83 |
for each libvirt object. This table is autogenerated
|
|
|
43fe83 |
from the enums in src/access/viraccessperms.h by the
|
|
|
43fe83 |
genaclperms.pl script.
|
|
|
43fe83 |
|
|
|
43fe83 |
newapi.xsl is modified so that the list of permissions
|
|
|
43fe83 |
checks shown against each API will link to the description
|
|
|
43fe83 |
of the permissions in acl.html
|
|
|
43fe83 |
|
|
|
43fe83 |
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
|
|
|
43fe83 |
(cherry picked from commit da13f2c70c06c38c4f8feba1a5725652d2f1efc7)
|
|
|
43fe83 |
---
|
|
|
43fe83 |
.gitignore | 1 +
|
|
|
43fe83 |
docs/Makefile.am | 12 +-
|
|
|
43fe83 |
docs/acl.html.in | 100 ++++++++++++
|
|
|
43fe83 |
docs/aclpolkit.html.in | 410 +++++++++++++++++++++++++++++++++++++++++++++++++
|
|
|
43fe83 |
docs/auth.html.in | 6 +-
|
|
|
43fe83 |
docs/genaclperms.pl | 124 +++++++++++++++
|
|
|
43fe83 |
docs/newapi.xsl | 4 +-
|
|
|
43fe83 |
docs/page.xsl | 11 ++
|
|
|
43fe83 |
docs/sitemap.html.in | 10 ++
|
|
|
43fe83 |
src/Makefile.am | 2 +-
|
|
|
43fe83 |
10 files changed, 674 insertions(+), 6 deletions(-)
|
|
|
43fe83 |
create mode 100644 docs/acl.html.in
|
|
|
43fe83 |
create mode 100644 docs/aclpolkit.html.in
|
|
|
43fe83 |
create mode 100755 docs/genaclperms.pl
|
|
|
43fe83 |
|
|
|
43fe83 |
diff --git a/docs/Makefile.am b/docs/Makefile.am
|
|
|
43fe83 |
index aabee44..0b0d2d4 100644
|
|
|
43fe83 |
--- a/docs/Makefile.am
|
|
|
43fe83 |
+++ b/docs/Makefile.am
|
|
|
43fe83 |
@@ -128,7 +128,7 @@ fig = \
|
|
|
43fe83 |
migration-unmanaged-direct.fig
|
|
|
43fe83 |
|
|
|
43fe83 |
EXTRA_DIST= \
|
|
|
43fe83 |
- apibuild.py \
|
|
|
43fe83 |
+ apibuild.py genaclperms.pl \
|
|
|
43fe83 |
site.xsl newapi.xsl news.xsl page.xsl \
|
|
|
43fe83 |
hacking1.xsl hacking2.xsl wrapstring.xsl \
|
|
|
43fe83 |
$(dot_html) $(dot_html_in) $(gif) $(apihtml) $(apipng) \
|
|
|
43fe83 |
@@ -139,6 +139,16 @@ EXTRA_DIST= \
|
|
|
43fe83 |
sitemap.html.in \
|
|
|
43fe83 |
todo.pl hvsupport.pl todo.cfg-example
|
|
|
43fe83 |
|
|
|
43fe83 |
+BUILT_SOURCES += aclperms.htmlinc
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+CLEANFILES = $(srcdir)/aclperms.htmlinc
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+acl.html:: $(srcdir)/aclperms.htmlinc
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+$(srcdir)/aclperms.htmlinc: $(top_srcdir)/src/access/viraccessperm.h \
|
|
|
43fe83 |
+ $(srcdir)/genaclperms.pl Makefile.am
|
|
|
43fe83 |
+ $(PERL) $(srcdir)/genaclperms.pl $< > $@
|
|
|
43fe83 |
+
|
|
|
43fe83 |
MAINTAINERCLEANFILES = \
|
|
|
43fe83 |
$(addprefix $(srcdir)/,$(dot_html)) \
|
|
|
43fe83 |
$(addprefix $(srcdir)/,$(apihtml)) \
|
|
|
43fe83 |
diff --git a/docs/acl.html.in b/docs/acl.html.in
|
|
|
43fe83 |
new file mode 100644
|
|
|
43fe83 |
index 0000000..2d228e2
|
|
|
43fe83 |
--- /dev/null
|
|
|
43fe83 |
+++ b/docs/acl.html.in
|
|
|
43fe83 |
@@ -0,0 +1,100 @@
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
43fe83 |
+ <body>
|
|
|
43fe83 |
+ Client access control
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Libvirt's client access control framework allows administrators
|
|
|
43fe83 |
+ to setup fine grained permission rules across client users,
|
|
|
43fe83 |
+ managed objects and API operations. This allows client connections
|
|
|
43fe83 |
+ to be locked down to a minimal set of privileges.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ In a default configuration, the libvirtd daemon has three levels
|
|
|
43fe83 |
+ of access control. All connections start off in an unauthenticated
|
|
|
43fe83 |
+ state, where the only API operations allowed are those required
|
|
|
43fe83 |
+ to complete authentication. After successful authentication, a
|
|
|
43fe83 |
+ connection either has full, unrestricted access to all libvirt
|
|
|
43fe83 |
+ API calls, or is locked down to only "read only" operations,
|
|
|
43fe83 |
+ according to what socket a client connection originated on.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The access control framework allows authenticated connections to
|
|
|
43fe83 |
+ have fine grained permission rules to be defined by the administrator.
|
|
|
43fe83 |
+ Every API call in libvirt has a set of permissions that will
|
|
|
43fe83 |
+ be validated against the object being used. For example, the
|
|
|
43fe83 |
+ virDomainSetSchedulerParametersFlags method will
|
|
|
43fe83 |
+ check whether the client user has the write
|
|
|
43fe83 |
+ permission on the domain object instance passed
|
|
|
43fe83 |
+ in as a parameter. Further permissions will also be checked
|
|
|
43fe83 |
+ if certain flags are set in the API call. In addition to
|
|
|
43fe83 |
+ checks on the object passed in to an API call, some methods
|
|
|
43fe83 |
+ will filter their results. For example the virConnectListAllDomains
|
|
|
43fe83 |
+ method will check the search_domains on the connect
|
|
|
43fe83 |
+ object, but will also filter the returned domain
|
|
|
43fe83 |
+ objects to only those on which the client user has the
|
|
|
43fe83 |
+ getattr permission.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The access control framework is designed as a pluggable
|
|
|
43fe83 |
+ system to enable future integration with arbitrary access
|
|
|
43fe83 |
+ control technologies. By default, the none
|
|
|
43fe83 |
+ driver is used, which does no access control checks at
|
|
|
43fe83 |
+ all. At this time, libvirt ships with support for using
|
|
|
43fe83 |
+ polkit as a real access
|
|
|
43fe83 |
+ control driver. To learn how to use the polkit access
|
|
|
43fe83 |
+ driver consult the configuration
|
|
|
43fe83 |
+ docs.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The access driver is configured in the libvirtd.conf
|
|
|
43fe83 |
+ configuration file, using the access_drivers
|
|
|
43fe83 |
+ parameter. This parameter accepts an array of access control
|
|
|
43fe83 |
+ driver names. If more than one access driver is requested,
|
|
|
43fe83 |
+ then all must succeed in order for access to be granted.
|
|
|
43fe83 |
+ To enable 'polkit' as the driver:
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+# augtool -s set '/files/etc/libvirt/libvirtd.conf/access_drivers[1]' polkit
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ And to reset back to the default (no-op) driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+# augtool -s rm /files/etc/libvirt/libvirtd.conf/access_drivers
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Note: changes to libvirtd.conf require that
|
|
|
43fe83 |
+ the libvirtd daemon be restarted.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Libvirt applies access control to all the main object
|
|
|
43fe83 |
+ types in its API. Each object type, in turn, has a set
|
|
|
43fe83 |
+ of permissions defined. To determine what permissions
|
|
|
43fe83 |
+ are checked for specific API call, consult the
|
|
|
43fe83 |
+ API reference manual
|
|
|
43fe83 |
+ documentation for the API in question.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ </body>
|
|
|
43fe83 |
+</html>
|
|
|
43fe83 |
diff --git a/docs/aclpolkit.html.in b/docs/aclpolkit.html.in
|
|
|
43fe83 |
new file mode 100644
|
|
|
43fe83 |
index 0000000..3b0d81a
|
|
|
43fe83 |
--- /dev/null
|
|
|
43fe83 |
+++ b/docs/aclpolkit.html.in
|
|
|
43fe83 |
@@ -0,0 +1,410 @@
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
43fe83 |
+ <body>
|
|
|
43fe83 |
+ Polkit access control
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Libvirt's client access control framework allows
|
|
|
43fe83 |
+ administrators to setup fine grained permission rules across client users,
|
|
|
43fe83 |
+ managed objects and API operations. This allows client connections
|
|
|
43fe83 |
+ to be locked down to a minimal set of privileges. The polkit driver
|
|
|
43fe83 |
+ provides a simple implementation of the access control framework.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ A default install of libvirt will typically use
|
|
|
43fe83 |
+ polkit
|
|
|
43fe83 |
+ to authenticate the initial user connection to libvirtd. This is a
|
|
|
43fe83 |
+ very coarse grained check though, either allowing full read-write
|
|
|
43fe83 |
+ access to all APIs, or just read-only access. The polkit access
|
|
|
43fe83 |
+ control driver in libvirt builds on this capability to allow for
|
|
|
43fe83 |
+ fine grained control over the operations a user may perform on an
|
|
|
43fe83 |
+ object.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The libvirt object names and permission names
|
|
|
43fe83 |
+ are mapped onto polkit action names using the simple pattern:
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ org.libvirt.api.$object.$permission
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The only caveat is that any underscore characters in the
|
|
|
43fe83 |
+ object or permission names are converted to hyphens. So,
|
|
|
43fe83 |
+ for example, the search_storage_vols permission
|
|
|
43fe83 |
+ on the storage_pool object maps to the polkit
|
|
|
43fe83 |
+ action:
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ org.libvirt.api.storage-pool.search-storage-vols
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ The default policy for any permission which corresponds to
|
|
|
43fe83 |
+ a "read only" operation, is to allow access. All other
|
|
|
43fe83 |
+ permissions default to deny access.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ To allow polkit authorization rules to be written to match
|
|
|
43fe83 |
+ against individual object instances, libvirt provides a number
|
|
|
43fe83 |
+ of authorization detail attributes when performing a permission
|
|
|
43fe83 |
+ check. The set of attributes varies according to the type
|
|
|
43fe83 |
+ of object being checked
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ domain_name
|
|
|
43fe83 |
+ Name of the domain, unique to the local host
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ domain_uuid
|
|
|
43fe83 |
+ UUID of the domain, globally unique
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ interface_name
|
|
|
43fe83 |
+ Name of the network interface, unique to the local host
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ interface_mac
|
|
|
43fe83 |
+ MAC address of the network interface, not unique
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ network_name
|
|
|
43fe83 |
+ Name of the network, unique to the local host
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ network_uuid
|
|
|
43fe83 |
+ UUID of the network, globally unique
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ node_device_name
|
|
|
43fe83 |
+ Name of the node device, unique to the local host
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ nwfilter_name
|
|
|
43fe83 |
+ Name of the network filter, unique to the local host
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ nwfilter_uuid
|
|
|
43fe83 |
+ UUID of the network filter, globally unique
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ secret_uuid
|
|
|
43fe83 |
+ UUID of the secret, globally unique
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ secret_usage_volume
|
|
|
43fe83 |
+ Name of the associated volume, if any
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ secret_usage_ceph
|
|
|
43fe83 |
+ Name of the associated Ceph server, if any
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ secret_usage_target
|
|
|
43fe83 |
+ Name of the associated iSCSI target, if any
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ pool_name
|
|
|
43fe83 |
+ Name of the storage pool, unique to the local host
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ pool_uuid
|
|
|
43fe83 |
+ UUID of the storage pool, globally unique
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Attribute
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ connect_driver
|
|
|
43fe83 |
+ Name of the libvirt connection driver
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ pool_name
|
|
|
43fe83 |
+ Name of the storage pool, unique to the local host
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ pool_uuid
|
|
|
43fe83 |
+ UUID of the storage pool, globally unique
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ vol_name
|
|
|
43fe83 |
+ Name of the storage volume, unique to the pool
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ vol_key
|
|
|
43fe83 |
+ Key of the storage volume, globally unique
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ At this point in time, the only attribute provided by
|
|
|
43fe83 |
+ libvirt to identify the user invoking the operation
|
|
|
43fe83 |
+ is the PID of the client program. This means that the
|
|
|
43fe83 |
+ polkit access control driver is only useful if connections
|
|
|
43fe83 |
+ to libvirt are restricted to its UNIX domain socket. If
|
|
|
43fe83 |
+ connections are being made to a TCP socket, no identifying
|
|
|
43fe83 |
+ information is available and access will be denied.
|
|
|
43fe83 |
+ Also note that if the client is connecting via an SSH
|
|
|
43fe83 |
+ tunnel, it is the local SSH user that will be identified.
|
|
|
43fe83 |
+ In future versions, it is expected that more information
|
|
|
43fe83 |
+ about the client user will be provided, including the
|
|
|
43fe83 |
+ SASL / Kerberos username and/or x509 distinguished
|
|
|
43fe83 |
+ name obtained from the authentication provider in use.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ If using versions of polkit prior to 0.106 then it is only
|
|
|
43fe83 |
+ possible to validate (user, permission) pairs via the .pkla
|
|
|
43fe83 |
+ files. Fully validation of the (user, permission, object) triple
|
|
|
43fe83 |
+ requires the new JavaScript .rules support that
|
|
|
43fe83 |
+ was introduced in version 0.106. The latter is what will be
|
|
|
43fe83 |
+ described here.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Libvirt does not ship any rules files by default. It merely
|
|
|
43fe83 |
+ provides a definition of the default behaviour for each
|
|
|
43fe83 |
+ action (permission). As noted earlier, permissions which
|
|
|
43fe83 |
+ correspond to read-only operations in libvirt will be allowed
|
|
|
43fe83 |
+ to all users by default; everything else is denied by default.
|
|
|
43fe83 |
+ Defining custom rules requires creation of a file in the
|
|
|
43fe83 |
+ /etc/polkit-1/rules.d directory with a name
|
|
|
43fe83 |
+ chosen by the administrator (100-libvirt-acl.rules
|
|
|
43fe83 |
+ would be a reasonable choice). See the polkit(8)
|
|
|
43fe83 |
+ manual page for a description of how to write these files
|
|
|
43fe83 |
+ in general. The key idea is to create a file containing
|
|
|
43fe83 |
+ something like
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ polkit.addRule(function(action, subject) {
|
|
|
43fe83 |
+ ....logic to check 'action' and 'subject'...
|
|
|
43fe83 |
+ });
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ In this code snippet above, the action object
|
|
|
43fe83 |
+ instance will represent the libvirt permission being checked
|
|
|
43fe83 |
+ along with identifying attributes for the object it is being
|
|
|
43fe83 |
+ applied to. The subject meanwhile will identify
|
|
|
43fe83 |
+ the libvirt client app (with the caveat above about it only
|
|
|
43fe83 |
+ dealing with local clients connected via the UNIX socket).
|
|
|
43fe83 |
+ On the action object, the permission name is
|
|
|
43fe83 |
+ accessible via the id attribute, while the
|
|
|
43fe83 |
+ object identifying attributes are exposed via a set of
|
|
|
43fe83 |
+ attributes with the naming convention _detail_[attrname].
|
|
|
43fe83 |
+ For example, the 'domain_name' attribute would be exposed via
|
|
|
43fe83 |
+ a property _detail_domain_name.
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Consider a local user berrange
|
|
|
43fe83 |
+ who has been granted permission to connect to libvirt in
|
|
|
43fe83 |
+ full read-write mode. The goal is to only allow them to
|
|
|
43fe83 |
+ use the QEMU driver and not the Xen or LXC
|
|
|
43fe83 |
+ drivers which are also available in libvirtd.
|
|
|
43fe83 |
+ To achieve this we need to write a rule which checks
|
|
|
43fe83 |
+ whether the _detail_connect_driver attribute
|
|
|
43fe83 |
+ is QEMU, and match on an action
|
|
|
43fe83 |
+ name of org.libvirt.api.connect.getattr. Using
|
|
|
43fe83 |
+ the javascript rules format, this ends up written as
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+polkit.addRule(function(action, subject) {
|
|
|
43fe83 |
+ if (action.id == "org.libvirt.api.connect.getattr" &&
|
|
|
43fe83 |
+ subject.user == "berrange") {
|
|
|
43fe83 |
+ if (action._detail_connect_driver == 'QEMU') {
|
|
|
43fe83 |
+ return polkit.Result.YES;
|
|
|
43fe83 |
+ } else {
|
|
|
43fe83 |
+ return polkit.Result.NO;
|
|
|
43fe83 |
+ }
|
|
|
43fe83 |
+ }
|
|
|
43fe83 |
+});
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Consider a local user berrange
|
|
|
43fe83 |
+ who has been granted permission to connect to libvirt in
|
|
|
43fe83 |
+ full read-write mode. The goal is to only allow them to
|
|
|
43fe83 |
+ see the domain called demo on the LXC driver.
|
|
|
43fe83 |
+ To achieve this we need to write a rule which checks
|
|
|
43fe83 |
+ whether the _detail_connect_driver attribute
|
|
|
43fe83 |
+ is LXC and the _detail_domain_name
|
|
|
43fe83 |
+ attribute is demo, and match on a action
|
|
|
43fe83 |
+ name of org.libvirt.api.domain.getattr. Using
|
|
|
43fe83 |
+ the javascript rules format, this ends up written as
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+polkit.addRule(function(action, subject) {
|
|
|
43fe83 |
+ if (action.id == "org.libvirt.api.domain.getattr" &&
|
|
|
43fe83 |
+ subject.user == "berrange") {
|
|
|
43fe83 |
+ if (action._detail_connect_driver == 'LXC' &&
|
|
|
43fe83 |
+ action._detail_domain_name == 'busy') {
|
|
|
43fe83 |
+ return polkit.Result.YES;
|
|
|
43fe83 |
+ } else {
|
|
|
43fe83 |
+ return polkit.Result.NO;
|
|
|
43fe83 |
+ }
|
|
|
43fe83 |
+ }
|
|
|
43fe83 |
+});
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ </body>
|
|
|
43fe83 |
+</html>
|
|
|
43fe83 |
diff --git a/docs/auth.html.in b/docs/auth.html.in
|
|
|
43fe83 |
index e5703c7..37f2978 100644
|
|
|
43fe83 |
--- a/docs/auth.html.in
|
|
|
43fe83 |
+++ b/docs/auth.html.in
|
|
|
43fe83 |
@@ -2,12 +2,14 @@
|
|
|
43fe83 |
|
|
|
43fe83 |
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
43fe83 |
<body>
|
|
|
43fe83 |
- Authentication & access control
|
|
|
43fe83 |
+ Connection authentication
|
|
|
43fe83 |
|
|
|
43fe83 |
When connecting to libvirt, some connections may require client
|
|
|
43fe83 |
authentication before allowing use of the APIs. The set of possible
|
|
|
43fe83 |
authentication mechanisms is administrator controlled, independent
|
|
|
43fe83 |
- of applications using libvirt.
|
|
|
43fe83 |
+ of applications using libvirt. Once authenticated, libvirt can apply
|
|
|
43fe83 |
+ fine grained access control to the operations
|
|
|
43fe83 |
+ performed by a client.
|
|
|
43fe83 |
|
|
|
43fe83 |
|
|
|
43fe83 |
|
|
|
43fe83 |
diff --git a/docs/genaclperms.pl b/docs/genaclperms.pl
|
|
|
43fe83 |
new file mode 100755
|
|
|
43fe83 |
index 0000000..244a68e
|
|
|
43fe83 |
--- /dev/null
|
|
|
43fe83 |
+++ b/docs/genaclperms.pl
|
|
|
43fe83 |
@@ -0,0 +1,124 @@
|
|
|
43fe83 |
+#!/usr/bin/perl
|
|
|
43fe83 |
+#
|
|
|
43fe83 |
+# Copyright (C) 2013 Red Hat, Inc.
|
|
|
43fe83 |
+#
|
|
|
43fe83 |
+# This library is free software; you can redistribute it and/or
|
|
|
43fe83 |
+# modify it under the terms of the GNU Lesser General Public
|
|
|
43fe83 |
+# License as published by the Free Software Foundation; either
|
|
|
43fe83 |
+# version 2.1 of the License, or (at your option) any later version.
|
|
|
43fe83 |
+#
|
|
|
43fe83 |
+# This library is distributed in the hope that it will be useful,
|
|
|
43fe83 |
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
43fe83 |
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
43fe83 |
+# Lesser General Public License for more details.
|
|
|
43fe83 |
+#
|
|
|
43fe83 |
+# You should have received a copy of the GNU Lesser General Public
|
|
|
43fe83 |
+# License along with this library. If not, see
|
|
|
43fe83 |
+# <http://www.gnu.org/licenses/>.
|
|
|
43fe83 |
+#
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+use strict;
|
|
|
43fe83 |
+use warnings;
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+my @objects = (
|
|
|
43fe83 |
+ "CONNECT", "DOMAIN", "INTERFACE",
|
|
|
43fe83 |
+ "NETWORK","NODE_DEVICE", "NWFILTER",
|
|
|
43fe83 |
+ "SECRET", "STORAGE_POOL", "STORAGE_VOL",
|
|
|
43fe83 |
+ );
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+my %class;
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+foreach my $object (@objects) {
|
|
|
43fe83 |
+ my $class = lc $object;
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ $class =~ s/(^\w|_\w)/uc $1/eg;
|
|
|
43fe83 |
+ $class =~ s/_//g;
|
|
|
43fe83 |
+ $class =~ s/Nwfilter/NWFilter/;
|
|
|
43fe83 |
+ $class = "vir" . $class . "Ptr";
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ $class{$object} = $class;
|
|
|
43fe83 |
+}
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+my $objects = join ("|", @objects);
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+my %opts;
|
|
|
43fe83 |
+my $in_opts = 0;
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+my %perms;
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+while (<>) {
|
|
|
43fe83 |
+ if ($in_opts) {
|
|
|
43fe83 |
+ if (m,\*/,) {
|
|
|
43fe83 |
+ $in_opts = 0;
|
|
|
43fe83 |
+ } elsif (/\*\s*\@(\w+):\s*(.*?)\s*$/) {
|
|
|
43fe83 |
+ $opts{$1} = $2;
|
|
|
43fe83 |
+ }
|
|
|
43fe83 |
+ } elsif (m,/\*\*,) {
|
|
|
43fe83 |
+ $in_opts = 1;
|
|
|
43fe83 |
+ } elsif (/VIR_ACCESS_PERM_($objects)_((?:\w|_)+),/) {
|
|
|
43fe83 |
+ my $object = $1;
|
|
|
43fe83 |
+ my $perm = lc $2;
|
|
|
43fe83 |
+ next if $perm eq "last";
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ $perm =~ s/_/-/g;
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ $perms{$object} = {} unless exists $perms{$object};
|
|
|
43fe83 |
+ $perms{$object}->{$perm} = {
|
|
|
43fe83 |
+ desc => $opts{desc},
|
|
|
43fe83 |
+ message => $opts{message},
|
|
|
43fe83 |
+ anonymous => $opts{anonymous}
|
|
|
43fe83 |
+ };
|
|
|
43fe83 |
+ %opts = ();
|
|
|
43fe83 |
+ }
|
|
|
43fe83 |
+}
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+print <
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
43fe83 |
+ <body>
|
|
|
43fe83 |
+EOF
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+foreach my $object (sort { $a cmp $b } keys %perms) {
|
|
|
43fe83 |
+ my $class = $class{$object};
|
|
|
43fe83 |
+ my $olink = lc "object_" . $object;
|
|
|
43fe83 |
+ print <
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Permission
|
|
|
43fe83 |
+ Description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+EOF
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ foreach my $perm (sort { $a cmp $b } keys %{$perms{$object}}) {
|
|
|
43fe83 |
+ my $description = $perms{$object}->{$perm}->{desc};
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ die "missing description for $object.$perm" unless
|
|
|
43fe83 |
+ defined $description;
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ my $plink = lc "perm_" . $object . "_" . $perm;
|
|
|
43fe83 |
+ $plink =~ s/-/_/g;
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ print <
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ $perm
|
|
|
43fe83 |
+ $description
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+EOF
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ }
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ print <
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+EOF
|
|
|
43fe83 |
+}
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+print <
|
|
|
43fe83 |
+ </body>
|
|
|
43fe83 |
+</html>
|
|
|
43fe83 |
+EOF
|
|
|
43fe83 |
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
|
|
|
43fe83 |
index 58f12eb..606d244 100644
|
|
|
43fe83 |
--- a/docs/newapi.xsl
|
|
|
43fe83 |
+++ b/docs/newapi.xsl
|
|
|
43fe83 |
@@ -71,8 +71,8 @@
|
|
|
43fe83 |
|
|
|
43fe83 |
<xsl:template match="check" mode="acl">
|
|
|
43fe83 |
|
|
|
43fe83 |
- <xsl:value-of select="@object"/>
|
|
|
43fe83 |
- <xsl:value-of select="@perm"/>
|
|
|
43fe83 |
+ <xsl:value-of select="@object"/>
|
|
|
43fe83 |
+ <xsl:value-of select="@perm"/>
|
|
|
43fe83 |
<xsl:choose>
|
|
|
43fe83 |
<xsl:when test="@flags">
|
|
|
43fe83 |
<xsl:value-of select="@flags"/>
|
|
|
43fe83 |
diff --git a/docs/page.xsl b/docs/page.xsl
|
|
|
43fe83 |
index 7da34ff..a2da854 100644
|
|
|
43fe83 |
--- a/docs/page.xsl
|
|
|
43fe83 |
+++ b/docs/page.xsl
|
|
|
43fe83 |
@@ -26,6 +26,10 @@
|
|
|
43fe83 |
<xsl:call-template name="toc"/>
|
|
|
43fe83 |
</xsl:template>
|
|
|
43fe83 |
|
|
|
43fe83 |
+ <xsl:template match="html:div[@id='include']" mode="content">
|
|
|
43fe83 |
+ <xsl:call-template name="include"/>
|
|
|
43fe83 |
+ </xsl:template>
|
|
|
43fe83 |
+
|
|
|
43fe83 |
|
|
|
43fe83 |
navigation menu for the current page -->
|
|
|
43fe83 |
<xsl:template match="html:ul" mode="menu">
|
|
|
43fe83 |
@@ -174,4 +178,11 @@
|
|
|
43fe83 |
</html>
|
|
|
43fe83 |
</xsl:template>
|
|
|
43fe83 |
|
|
|
43fe83 |
+ <xsl:template name="include">
|
|
|
43fe83 |
+ <xsl:variable name="inchtml">
|
|
|
43fe83 |
+ <xsl:copy-of select="document(@filename)"/>
|
|
|
43fe83 |
+ </xsl:variable>
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ <xsl:apply-templates select="exsl:node-set($inchtml)/html:html/html:body/*" mode="content"/>
|
|
|
43fe83 |
+ </xsl:template>
|
|
|
43fe83 |
</xsl:stylesheet>
|
|
|
43fe83 |
diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in
|
|
|
43fe83 |
index fd10caf..a8d2177 100644
|
|
|
43fe83 |
--- a/docs/sitemap.html.in
|
|
|
43fe83 |
+++ b/docs/sitemap.html.in
|
|
|
43fe83 |
@@ -69,6 +69,16 @@
|
|
|
43fe83 |
Configure authentication for the libvirt daemon
|
|
|
43fe83 |
|
|
|
43fe83 |
|
|
|
43fe83 |
+ Access control
|
|
|
43fe83 |
+ Configure access control libvirt APIs
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+ Polkit access control
|
|
|
43fe83 |
+ Using polkit for API access control
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
+
|
|
|
43fe83 |
Migration
|
|
|
43fe83 |
Migrating guests between machines
|
|
|
43fe83 |
|
|
|
43fe83 |
diff --git a/src/Makefile.am b/src/Makefile.am
|
|
|
43fe83 |
index 8c6f068..b049895 100644
|
|
|
43fe83 |
--- a/src/Makefile.am
|
|
|
43fe83 |
+++ b/src/Makefile.am
|
|
|
43fe83 |
@@ -1654,7 +1654,7 @@ test_libvirt_lockd.aug: locking/test_libvirt_lockd.aug.in \
|
|
|
43fe83 |
|
|
|
43fe83 |
test_virtlockd.aug: locking/test_virtlockd.aug.in \
|
|
|
43fe83 |
locking/virtlockd.conf $(AUG_GENTEST)
|
|
|
43fe83 |
- $(AM_V_GEN)$(AUG_GENTEST) locking/virtlockd.conf $< $@
|
|
|
43fe83 |
+ $(AM_V_GEN)$(AUG_GENTEST) $(srcdir)/locking/virtlockd.conf $< $@
|
|
|
43fe83 |
|
|
|
43fe83 |
check-augeas-lockd: test_libvirt_lockd.aug
|
|
|
43fe83 |
$(AM_V_GEN)if test -x '$(AUGPARSE)'; then \
|
|
|
43fe83 |
--
|
|
|
43fe83 |
1.8.3.2
|
|
|
43fe83 |
|