- 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. -

- 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 as a real access - control driver. To learn how to use the polkit access - driver consult the configuration - docs. -

- 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: -

- 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 - documentation for the API in question. -

- - - diff --git a/docs/acl.rst b/docs/acl.rst new file mode 100644 index 0000000000..06c248333f --- /dev/null +++ b/docs/acl.rst @@ -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 `__ as a real access +control driver. To learn how to use the polkit access driver consult `the +configuration docs `__. + +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 `__ documentation for the API in question. + +.. raw:: html + +

diff --git a/docs/aclpolkit.rst b/docs/aclpolkit.rst index 09e5d9ea27..07f4735001 100644 --- a/docs/aclpolkit.rst +++ b/docs/aclpolkit.rst @@ -26,7 +26,7 @@ the operations a user may perform on an object. Permission names ---------------- -The libvirt `object names and permission names `__ are +The libvirt `object names and permission names `__ are mapped onto polkit action names using the simple pattern: :: diff --git a/docs/meson.build b/docs/meson.build index 68359be0b4..8edb93333a 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -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, }