Page MenuHomePhorge
Files F16569543

No OneTemporary
Actions

View Options

diff --git a/source/administrator-guide/kolab-freebusy-reference.rst b/source/administrator-guide/kolab-freebusy-reference.rst
index 53f944f1..270b2a33 100644
--- a/source/administrator-guide/kolab-freebusy-reference.rst
+++ b/source/administrator-guide/kolab-freebusy-reference.rst
@@ -1,358 +1,454 @@
.. _admin_kolab-freebusy-settings:
=========================================
Kolab Freebusy Service Settings Reference
=========================================
The web service is configured using a single settings file in .ini format
located in ``/etc/kolab-freebusy/config.ini``.
The configuration is divided into the following static sections and a list
**directory** sections defining the list of directories used to search
for freebusy for the requested user or resource. The directories are iterated
from to to bottom in the order as they appear in the config file. The iteration
stops once a directory can provide valid freebusy data.
Basic Configuration
===================
[httpauth]
----------
Access to the web service can be protected with basic HTTP authentication.
This section controls the authentication with the following options:
``type``
^^^^^^^^
Either one of 'static' or 'ldap'.
'static' provides a simple authentication with a static username/password pair.
'ldap' will perform an LDAP login with the provided username and password.
Only users who can authenticate on LDAP will be granted access to the service.
``username``
^^^^^^^^^^^^
Static username used with type 'static'.
``password``
^^^^^^^^^^^^
Static password used with type 'static'.
``host``
^^^^^^^^
Fully qualified URI to the LDAP server, including protocol and port.
Example: ``ldap://localhost:389``
``bind_dn``
^^^^^^^^^^^
DN for binding to the LDAP service. Should be an unprivileged
user with read-only access.
Example: ``uid=kolab-service,ou=Special Users,dc=example,dc=org``
``bind_pw``
^^^^^^^^^^^
Password for binding to the LDAP service.
``filter``
^^^^^^^^^^
Optional. Filter used to first resolve the username against LDAP.
``%s`` is replaced by the username.
Example: ``(&(|(mail=%s)(alias=%s)(uid=%s))(objectclass=inetorgperson))``
[trustednetworks]
-----------------
Allow privileged access from these IPs and skip HTTP authentication
in case httpauth is configured.
Privileged access means that instead of a dummy freebusy data block,
a 404 error is returned if a user or resource could not be resolved.
``allow``
^^^^^^^^^
A list of IPs, subnets or patterns which are considered trusted.
Examples:
.. parsed-literal::
allow = 127.0.0.1,
192.168.0.0/16,
10.10.*,
::1
.. _admin_kolab-freebusy-settings-log:
[log]
-----
Logging configuration.
``driver``
^^^^^^^^^^
Supported drivers are 'file' and 'syslog'
``path``
^^^^^^^^
Local filesystem path to a directory where log files will be created.
``name``
^^^^^^^^
Filename or syslog identifier.
``level``
^^^^^^^^^
The general log level. Possible values are:
* 100 = Debug
* 200 = Info
* 300 = Warn
* 400 = Error
* 500 = Critical
+.. _admin_kolab-freebusy-settings-directories:
Directories and Sources
=======================
Directories are defined as named sections like
.. code-block:: ini
[directory "local"]
and use the following options depending on the specified type:
``type``
--------
Either one of 'static' or 'ldap'.
'static' denotes a simple directory with an optional ``filter``
option providing a regular expression to matching the requested user name.
'ldap' directories perform an LDAP query to validate the requested user name
and to provide additional attributes used for retrieving freebusy data from
the linked source. This type uses the following configuration options:
* host
* bind_dn
* bind_pw
* base_dn
* filter
+* primary_domain
* attributes
* attributes_lc (optional)
+* domain_filter (optional)
+* domain_base_dn (optional)
``filter``
----------
Optional. String denoting a regular expression matched against the user name.
See `PHP PCRE Manual <http://php.net/manual/en/reference.pcre.pattern.syntax.php>`_
for the allowed regex syntax.
``host``
--------
Fully qualified URI to the LDAP server, including protocol and port.
Example: ``ldap://localhost:389``
+
``bind_dn``
-----------
DN for binding to the LDAP service. Should be an unprivileged
user with read-only access.
Example: ``uid=kolab-service,ou=Special Users,dc=example,dc=org``
+
``bind_pw``
-----------
Password for binding to the LDAP service.
+
``filter``
----------
-Filter used to find the given user in LDAP. ``%s`` is replaced by the user name.
-Example: ``"(&(objectClass=kolabInetOrgPerson)(|(uid=%s)(mail=%s)(alias=%s)))"``
+Filter used to find the given user in LDAP. ``%s`` is replaced by the full user name,
+``%u`` by the local part of the user name.
+
+Example: ``"(&(objectClass=kolabInetOrgPerson)(|(uid=%u)(mail=%s)(alias=%s)))"``
+
+
+``base_dn``
+----------
+
+Base DN used for the user query to LDAP. ``%dc`` is replaced by the DN matching
+the user name domain.
+
+Example: ``"ou=People,%dc"``
+
+
+``primary_domain``
+------------------
+
+Fall-back domain name used for queries without fully qualified email addresses.
+
``attributes``
--------------
List of attributes which should be fetched from the matching LDAP entry.
These will then replace placeholders in the ``fbsource`` URI.
Example: ``mail, sn``
+
``lc_attributes``
-----------------
List of entry attributes which are read form LDAP and are converted into lower-case
characters.
+``domain_filter``
+-----------------
+
+Filter used to resolve the root DN (``%dc``) for the the given user name domain.
+``%s`` is replaced by the domain part of the user name.
+
+Example: ``"(&(objectclass=domainrelatedobject)(associateddomain=%s))"``
+
+
+``domain_base_dn``
+------------------
+
+Base DN used for resolving the domain root DN with LDAP
+
+Example: ``"cn=kolab,cn=config"``
+
+
``mail_attributes``
-------------------
List of entry attributes which denote the user's email address(es).
Only used in conjunction with an 'imap' source.
These attributes are used to determine whether events from shared calendars
affect the user's availability. Email addresses from all these attributes
are matched against the list of event attendees.
``fbsource``
------------
This option defines the **Source** where freebusy data for the matching user
is fetched from. The value is a fully qualified URI with the protocol identifier
denoting the type of the source.
Example: ``file:/var/lib/kolab-freebusy/%mail.ifb``
The follwing source types are supported:
``file``
^^^^^^^^
.. code-block:: ini
fbsource = file:/var/lib/kolab-freebusy/%mail.ifb
``%mail`` is a placeholder for the ``mail`` attribute from LDAP.
``http(s)``
^^^^^^^^^^^
.. code-block:: ini
fbsource = https://<user>:<password>@externalhost.com/free-busy/%s.ics
``%s`` is replaced with the user name from the request.
``imap``
^^^^^^^^
.. code-block:: ini
;; read data from a users calendars (all) using IMAP proxy authentication
fbsource = "imap://%mail:<admin-pass>@localhost/?proxy_auth=cyrus-admin"
;; read data from a shared IMAP folder with cyrus-admin privileges
fbsource = "imap://cyrus-admin:<admin-pass>@localhost/%kolabtargetfolder?acl=lrs"
``%mail`` and ``%kolabtargetfolder`` are placeholders for attributes from LDAP.
The ``proxy_auth`` URL parameter performs a proxy authentication using the given
admin username (parameter value) and the admin password.
The ``acl`` URL parameter will set the defined ACLs to the target IMAP folder
in order to let the admin user read its contents.
``fbdaemon``
^^^^^^^^^^^^
.. code-block:: ini
;; trigger kolab-freebusyd daemon to aggregate data from a user's calendars
fbsource = "fbdaemon://localhost:<port>?user=%mail"
;; trigger kolab-freebusyd to fetch data from a shared folder (i.e. for resources)
fbsource = "fbdaemon://localhost:<port>?folder=%kolabtargetfolder"
``%mail`` and ``%kolabtargetfolder`` are placeholders for attributes from LDAP.
The ``user`` URL parameter specifies the command for accessing IMAP on behalf of
this user (proxy authentication) and to collect data from all the calendar folders
this user has access to.
The ``folder`` parameter instructs the daemon to collect event data from the given
IMAP mailbox.
+
+``aggregate``
+^^^^^^^^^^^^^
+
+In Kolab, resource collections are basically a group of recources without having calendar data
+assigned to the group directly. But we nevertheless want to show the availability for a collection
+and this is where the aggregate source type is used.
+
+.. code-block:: ini
+
+ ;; LDAP filter to find a group record to aggregate data for all its members
+ filter = "(&(objectClass=kolabgroupofuniquenames)(mail=%s))"
+ attributes = uniquemember, mail
+ resolve_dn = uniquemember
+ resolve_attribute = mail
+
+ ;; the 'aggregate' source takes one parameter denoting the attribute holding all member email addresses
+ fbsource = "aggregate://%uniquemember"
+
+ ;; consider these directories for getting the member's free/busy data
+ directories = kolab-resources
+
+``resolve_dn`` specifies the attribute of the group record that holds DNs for members
+that need to be resolved into valid user names/email addresses to then aggregate data for.
+``resolve_attribute`` denotes the attribute of the member records that should replace the DN value.
+
+Once the members of a collection are resolved, freebusy data for each of them is fetched from the
+sources specified in ``directories`` and finally aggregated.
+
+
.. seealso::
* Architecture & Design, Kolab Freebusy Service, :ref:`and_kolab-freebusy-directory-types`
``cacheto``
-----------
An absolute path to the local file system where freebusy data collected from the configured
fbsource is cached for future requests. Can contain placeholders for LDAP attributes or
``%s`` for the requested user name.
``expires``
-----------
Defines the cache expiration time. Can contain numeric values with a unit indicator such as
``h``, ``m``, or ``s``.
Example: ``10m`` for 10 minutes
``loglevel``
------------
Log level for this directory. See :ref:`admin_kolab-freebusy-settings-log`
for possible values.
+.. _admin_kolab-freebusy-settings-examples:
Examples
========
The `config.ini.sample <http://git.kolab.org/kolab-freebusy/tree/config/config.ini.sample>`_
file provides a full overview of possible configuration options.
Sample Directory for Kolab Users
--------------------------------
.. code-block:: ini
[directory "kolab-users"]
type = ldap
host = ldap://localhost:389
- bind_dn = "uid=kolab-service,ou=Special Users,dc=example,dc=org"
+ bind_dn = "uid=kolab-service,ou=Special Users,dc=yourdomain,dc=com"
bind_pw = "<service-bind-pw>"
- base_dn = "ou=People,dc=example,dc=org"
- filter = "(&(objectClass=kolabInetOrgPerson)(|(uid=%s)(mail=%s)(alias=%s)))"
+ base_dn = "ou=People,dc=yourdomain,dc=com"
+ filter = "(&(objectClass=kolabInetOrgPerson)(|(uid=%u)(mail=%s)(alias=%s)))"
attributes = mail
lc_attributes = mail
fbsource = file:/var/lib/kolab-freebusy/%mail.ifb
Sample Directory for Resources
------------------------------
.. code-block:: ini
[directory "kolab-resources"]
type = ldap
host = ldap://localhost:389
bind_dn = "uid=kolab-service,ou=Special Users,dc=yourdomain,dc=com"
bind_pw = "<service-bind-pw>"
base_dn = "ou=Resources,dc=yourdomain,dc=com"
filter = "(&(objectClass=kolabsharedfolder)(mail=%s))"
attributes = mail, kolabtargetfolder
fbsource = "fbdaemon://localhost:<port>?folder=%kolabtargetfolder"
timeout = 10 ; abort after 10 seconds
cacheto = /var/cache/kolab-freebusy/%mail.ifb
expires = 10m
loglevel = 100 ; Debug
+
+Sample Directory for Resource Collections
+-----------------------------------------
+
+.. code-block:: ini
+
+ [directory "kolab-resource-collections"]
+ type = ldap
+ host = ldap://localhost:389
+ bind_dn = "uid=kolab-service,ou=Special Users,dc=yourdomain,dc=com"
+ bind_pw = "<service-bind-pw>"
+ base_dn = "ou=Resources,dc=yourdomain,dc=com"
+ filter = "(&(objectClass=kolabgroupofuniquenames)(mail=%s))"
+ attributes = uniquemember
+ resolve_dn = uniquemember
+ resolve_attribute = mail
+ fbsource = "aggregate://%uniquemember"
+ directories = kolab-resources
+ timeout = 10 ; abort after 10 seconds
+ cacheto = /var/cache/kolab-freebusy/%mail.ifb
+ expires = 10m
+ loglevel = 100 ; Debug
diff --git a/source/architecture-and-design/kolab-freebusy.rst b/source/architecture-and-design/kolab-freebusy.rst
index 63841213..7d3a6e2c 100644
--- a/source/architecture-and-design/kolab-freebusy.rst
+++ b/source/architecture-and-design/kolab-freebusy.rst
@@ -1,136 +1,142 @@
.. _and_kolab-freebusyd:
=====================
Kolab Freebusy Daemon
=====================
The Kolab Freebusy Daemon **kolab-freebusyd** is the component that generates
Freebusy data for users and resources.
**MORE DOCUMENTATION TO BE ADDED HERE**
Running kolab-freebusyd as cron job
===================================
Undocumented.
Running kolab-freebusyd as daemon
=================================
Undocumented.
.. _and_kolab-freebusy:
======================
Kolab Freebusy Service
======================
The Kolab Freebusy Service is a REST web service serving Freebusy data through HTTP(s)
at ``/freebusy/``.
Queries for freebusy information for a particular user or resource can sent as
GET requests in the following form: ``/freebusy/<user-or-resource-email-address>.ifb``
Example URL:
.. parsed-literal::
http://example.org/freebusy/john.doe@example.org.ifb
The Kolab Freebusy Service can be configured in various ways to collect freebusy data
from different subsystems or services and cache and deliver them to the public.
.. _and_kolab-freebusy-directories-sources:
Directories and Sources
=======================
The service provides different modules to first look up and validate the user or
resource freebusy data is being requested and then fetching the actual data from
a specific source and optionally convert it.
A set of **Directories** is iterated with the current request until one
can resolve the user and delivers freebusy data from the linked **Source**.
Directories are defined as ``[directory "<dirname>"]`` blocks in the config.ini
file of the web service and link to a specific source using an URI set for
``fbsource``. See :ref:`and_kolab-freebusy-configuration` for details.
.. _and_kolab-freebusy-directory-types:
Directory Types
---------------
``static``
^^^^^^^^^^
A simple directory implementation which just checks the given email address
with a substring filter and either accepts or rejects the query.
``ldap``
^^^^^^^^
The LDAP directory resolves the given email address with a configurable query
to an LDAP service and provides additional attributes for the matching entry which
then can be passed to the linked **Service** to find the right data.
Service Types
-------------
``file``
^^^^^^^^
Provides a path for pre-generated freebusy data stored on the local filesystem.
These files are usually generated by the :ref:`and_kolab-freebusyd` running as cron job.
``http``
^^^^^^^^
Can fetch freebusy data from another service via HTTP(s).
``imap``
^^^^^^^^
Allows to directly read a user's calendar in IMAP and aggregate the stored
event data into an anonymized freebusy block.
.. NOTE::
This is note recommended to be used in a productive environment because
the web service directly accesses the IMAP backend with admin privileges
(proxy authentication) which should be avoided in a publicly accessible
web service.
``fbdaemon``
^^^^^^^^^^^^
With :ref:`and_kolab-freebusyd` running in daemon mode, this source connects
to the freebusyd and starts a job to aggregate and deliver freebusy data for a
user or a resource.
+``aggregate``
+^^^^^^^^^^^^^
+
+Aggregates Freebusy data from all members of a group into one data block that
+only shows slots as busy if they're unavailable for all members.
+
Formatters
==========
When fetching data from a specific source, format conversions can be applied
before delivering the data to the requesting client. For example the Kolab Freebusy
Service can convert data from an Exchange 2010 service into the iCal Freebusy format.
.. _and_kolab-freebusy-configuration:
Configuration Options
=====================
The `config.ini.sample <http://git.kolab.org/kolab-freebusy/tree/config/config.ini.sample>`_
-file provides a full overview of possible configuration options with several examples.
+file provides an overview of possible configuration options with several examples.
-The full documentation of the Kolab Freebusy Service configuration will be added to the
-:ref:`admin`.
+The full documentation of the Kolab Freebusy Service configuration can be found in the
+:ref:`admin_kolab-freebusy-settings`.

File Metadata

Mime Type
text/x-diff
Expires
Fri, Nov 1, 8:33 AM (1 d, 8 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
10074360
Default Alt Text
(17 KB)

Event Timeline