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.

`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

Kolab Freebusy Service Settings Reference¶

Basic Configuration¶

[httpauth]¶

type¶

username¶

password¶

host¶

bind_dn¶

bind_pw¶

filter¶

[trustednetworks]¶

allow¶

[log]¶

driver¶

path¶

name¶

level¶

Directories and Sources¶

type¶

filter¶

host¶

bind_dn¶

bind_pw¶

filter¶

base_dn¶

primary_domain¶

attributes¶

lc_attributes¶

domain_filter¶

domain_base_dn¶

mail_attributes¶

format¶

fbsource¶

file¶

http(s)¶

imap¶

fbdaemon¶

aggregate¶

cacheto¶

expires¶

loglevel¶

Examples¶

Sample Directory for Kolab Users¶

Sample Directory for Resources¶

Sample Directory for Resource Collections¶

`type`¶

`username`¶

`password`¶

`host`¶

`bind_dn`¶

`bind_pw`¶

`filter`¶

`allow`¶

`driver`¶

`path`¶

`name`¶

`level`¶

`type`¶

`filter`¶

`host`¶

`bind_dn`¶

`bind_pw`¶

`filter`¶

`base_dn`¶

`primary_domain`¶

`attributes`¶

`lc_attributes`¶

`domain_filter`¶

`domain_base_dn`¶

`mail_attributes`¶

`format`¶

`fbsource`¶

`file`¶

`http(s)`¶

`imap`¶

`fbdaemon`¶

`aggregate`¶

`cacheto`¶

`expires`¶

`loglevel`¶