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:

allow = 127.0.0.1,
  192.168.0.0/16,
  10.10.*,
   ::1

[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

Directories and Sources

Directories are defined as named sections like

[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

  • lc_attributes (optional)

  • domain_filter (optional)

  • domain_base_dn (optional)

filter

Optional. String denoting a regular expression matched against the user name.

See PHP PCRE Manual 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 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.

format

The format for the Free/Busy information source, if applicable. Valid options include only exchange2010.

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

fbsource = file:/var/lib/kolab-freebusy/%mail.ifb

%mail is a placeholder for the mail attribute from LDAP.

http(s)

fbsource = https://<user>:<password>@externalhost.com/free-busy/%s.ics

%s is replaced with the user name from the request.

imap

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

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

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

See also

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 [log] for possible values.

Examples

The config.ini.sample file provides a full overview of possible configuration options.

Sample Directory for Kolab Users

[directory "kolab-users"]
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=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

[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

[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