and Kolab Groupware integration
Tomasz Chmielewski, kolab
[at] wpkg [dot] org
You can always find the latest version of this document on
This article explains how
to add Kolab
Groupware functionality to your existing Samba/OpenLDAP setup.
From the Kolab
Kolab is a secure,
scalable and reliable groupware server.
It is formed by a number of well-known and proven components
or the standards tasks such as E-Mail, Directory Service and Web
User and groups can share folders including those that contain emails,
calendar items, tasks and contacts.
Users unfamiliar with Kolab
can think of it as a Free Software Groupware Solution with
features similar to Exchange.
If you have a running Samba
server, with its users, passwords and
groups stored in the OpenLDAP database, you could add more features to
it by integrating Kolab Groupware Solution with your setup - of course,
using the same credentials for both Samba and Kolab.
The article will be also useful if you want to use an existing OpenLDAP
for Kolab, rather than use the one shipped with Kolab.
It assumes the following:
Make a backup of your current installation first (or better, first try
to follow this HOWTO on a separate, testing machine)!
- you have a working Samba PDC/OpenLDAP installation,
- you would like to use your existing Samba user
accounts for Kolab
- your LDAP suffix is "dc=contact,dc=de", your rootdn is
"cn=Manager,dc=contact,dc=de", your kolab server is kolab.contact.de,
and you will use @contact.de email accounts - of course you have your
own, so just change it to whatever suit your own configuration.
If you find any errors in this document, or something is not explained
too clearly, have suggestions, please comment it on this page: http://wpkg.org/Talk:Kolab
- Downloading, compiling and configuring Kolab
Kolab sources first
- Make a
backup of a fresh Kolab installation
- Change configs
to match your existing Samba/OpenLDAP setup
- Bootstrap (configure) Kolab for the first time
- Advanced configuration
- Downloading, installing and configuring useful
- Download, install and configure phpLDAPadmin
install and configure LAM - LDAP Account Manager
Kolab LDAP database
OpenLDAP server used by Samba
Kolab LDAP database into the OpenLDAP used by Samba
your OpenLDAP server to allow LDAPv2 clients to bind
your OpenLDAP server to notify kolabd if new users are
- Adding users
- Verifying setup
- Converting "Samba only" users to Samba/Kolab users
- Removing users
- Additional settings
- Useful links
Download Kolab sources
- Downloading, compiling and configuring Kolab
You will find Kolab mirrors on http://kolab.org/mirrors.html.
Choose a mirror; for Kolab 2.0.1, used in this document, you have to
download the sources lacated in
Compiling Kolab is easy. After you downloaded Kolab, run the
# ./obmtool kolab
The whole process of compiling will take an hour or two, depending on
Kolab will be installed to
Make a backup of a fresh
If you configure Kolab for the first time, it is better to do a backup
of its fresh installation. This means that if you misconfigure
something, you won't have to compile it again:
# cp -v -a /kolab /kolab.orig
to match your existing Samba/OpenLDAP setup
Assuming you have an already working Samba/OpenLDAP setup, you probably
don't want to change their configuration to match Kolab, but rather
configure Kolab so that it uses an existing OpenLDAP server.
After Kolab is compiled, in the file
bind_dn : cn=manager,cn=internal,@@@kolab_basedn@@@
to something like:
bind_dn : cn=Manager,@@@kolab_basedn@@@
(or any other bind_dn you are using - consult your
Kolab for the first time
You will need to stop your existing OpenLDAP server for a while. You
also have to stop other servers running on ports 25, 80, 143 etc.
(SMTP, HTTP, IMAP etc.) - as Kolab needs to run an own instance of
these servers. The bootstrap program will notify you what ports does it
Run the bootsrtap process like that:
# /kolab/etc/kolab/kolab_bootstrap -b
Make sure that the LDAP credentials are the same as in your Samba LDAP
to see example answers.
If you think you misconfigured something, just remove
and restore it from
/kolab.orig (you did the
backup, didn't you?).
Currently, Kolab 2.0.1 supports only one email domain (this will change
in the upcoming Kolab 2.1 release). This means that all your Kolab
users need to have email addresses from the one domain
(email@example.com, firstname.lastname@example.org etc.).
When you set up Kolab with
assumes that your Maildomain will be the same as the base_dn/suffix of
the OpenLDAP server. For example, if you answered that your Maildomain
will be contact.de, Kolab will expect the OpenLDAP suffix to be
So, if your existing OpenLDAP server uses a different suffix (for
example, "dc=example,dc=com"), than the desired email domain (for
example, in our case, @contact.de), additional configuration is needed.
You have to do the following:
- Run the
above) and configure Kolab with Maildomain which will match the
existing LDAP server - example.com, if your OpenLDAP
server's base_dn/suffix is dc=example,dc=com.
- Change all occurances of example.com (our unwanted domain,
matches our OpenLDAP server) into contact.de (our desired domain) in
/kolab/etc directory. You will find it with a following command:
# cd /kolab/etc
# grep -r example.com ./
Kolab have to be stopped when you change it.
- Change the
k=kolab,dc=example,dc=com in the LDAP database) into your desired
name (from example.com to contact.de). Do it with phpLDAPadmin later.
If you have a working Samba with OpenLDAP, you're probably using
phpLDAPadmin and LAM. If you're not using, it's certainly the right
- Downloading and installing useful tools
Download, install and
- Download phpLDAPadmin from http://phpldapadmin.sf.net
- it's needed
to export/import the LDAP contents, but it's also a very useful tool
for managing your OpenLDAP server.
- Uncompress phpLDAPadmin to
- to the directory used by Kolab's Apache server.
- Edit a default phpldapadmin config file
Go to the phpLDAPadmin folder:
# cd /kolab/var/kolab/www/phpldapadminCreate a new config file out of the existing example
# cp config.php.example config.php
Change this line in
$config->custom->session['blowfish'] = '';
to something like (lots of random characters - these below aren't very
Download, install and
configure LAM - LDAP Account Manager
- Download LDAP Account Manager from http://lam.sf.net.
Kolab is supported in LAM 0.5, so any earlier (0.4.x) version won't
just work for us.
- Extract LAM to
- Create config files - just copy sample files:
# cp /kolab/var/kolab/www/lam/config/config.cfg_sample
# cp /kolab/var/kolab/www/lam/config/lam.conf_sample
- Make sure "lam" folder has the right owner (Kolab Apache
# chown -R kolab-n:kolab-n /kolab/var/kolab/www/lam
- Then, login to lam - http://kolab.contact.de/lam - and
Make sure to change all dc=my-domain,dc=com instances to
dc=contact,dc=de, or any prefix you use.
In our case, we also had to change ou=people to ou=Users, ou=groups to
ou=Groups, ou=machines to ou=Computers, ou=domains to ou=Domains, to
match our existing Samba/OpenLDAP entries. See an example here.
- After you change all suffixes, click on "Edit modules" and
"kolabUser" module - it's a LAM module responsible for configuring
Kolab users. Scroll down the module configuration page and click on
"Submit", then on the main configuration page, scroll down again, and
Submit the whole changes.
You should see a page with the changes that were made in the
config file - see an example here.
We have to export Kolab OpenLDAP database, and import it into our
existing OpenLDAP server used by Samba.
Export Kolab LDAP database
We will do it with phpLDAPadmin:
- Go to http://kolab.contact.de/phpldapadmin
- Enter the credentials and login - see an example here
- Click on the suffix (dc=contact,dc=de) and export it - see
an example here:
- Sub (entire subtree)
- Save as file
- Do not select "Include system attributes"!
- Click on "Proceed >>" and save the file -
see an example here
- DO NOT logout of phpldapadmin!
When you exported and saved the ldif file, you can stop Kolab's
# /kolab/bin/openpkg rc openldap stop
As Kolab's OpenLDAP server will be no longer needed, move
file to prevent Kolab's OpenLDAP
from starting - we want to use our own, right?
Backup this file to some location:
mv /kolab/etc/rc.d/rc.openldap /home/manager/backup
Configure OpenLDAP server
used by Samba
Your OpenLDAP server used by Samba must understand how to speak "Kolab".
To do that, add two new schema files to your OpenLDAP server
(used by Samba):
Place it after the last "include" line in your
If you have more OpenLDAP servers (slaves), copy these schema files and
add the above
Make sure that the OpenLDAP starts (not the one from Kolab, but the
one you use for Samba):
# /etc/init.d/ldap start
[ OK ]
If everything works, go to http://kolab.contact.de/phpldapadmin again,
hit "refresh" - you
should see your Samba LDAP entries, not the Kolab ones - as now we use
the OpenLDAP used by Samba, and the one that was compiled with Kolab,
is already stopped and won't be used again.
If you have errors like "invalid credentials", go back and try to
figure out what's wrong.
This is a crucial step, you can't continue if you have errors here
(perhaps the Kolab LDAP credentials are not the same as in your Samba
Import Kolab LDAP
database into the OpenLDAP used by Samba
Edit the ldif file you exported earlier with phpLDAPadmin - comment out
# Entry 1: dc=contact,dc=de
Then save the file.
Import the ldif file using phpLDAPadmin:
- click on Import -> Browse -> find the ldif file you
exported and edited earlier. Then click on "Proceed >>".
If for some reason phpLDAPadmin doesn't want to import your ldif file
("No LDIF file specified. Please try again."), try do it from the
If you want to import the ldif file from the command line, copy the
ldif file to the Kolab server first:
# scp contact.ldif email@example.com:
Then import the ldif file:
kolab# ldapadd -x -D
"cn=Manager,dc=<MY-DOMAIN>,dc=<COM>" -W -f
which in our case, is:
kolab# ldapadd -x -D "cn=Manager,dc=contact,dc=de" -W -f
Enter LDAP Password:
adding new entry "k=kolab,dc=contact,dc=de"
adding new entry "cn=internal,dc=contact,dc=de"
adding new entry "cn=external,dc=contact,dc=de"
adding new entry "cn=groups,dc=contact,dc=de"
adding new entry "cn=resources,dc=contact,dc=de"
adding new entry "cn=admin,cn=internal,dc=contact,dc=de"
adding new entry "cn=Manager,dc=contact,dc=de"
adding new entry "cn=nobody,cn=internal,dc=contact,dc=de"
adding new entry "cn=calendar,cn=internal,dc=contact,dc=de"
adding new entry "cn=maintainer,cn=internal,dc=contact,dc=de"
You should see a similar output with no errors, either if you imported
the ldif file with phpLDAPadmin, or command line ldapadd.
Refresh the view in phpldapadmin to make sure the new entries were
added - it will contain your existing Samba entries, and Kolab ones -
see an example here.
Configure your OpenLDAP
server to allow LDAPv2 clients to bind
/etc/openldap/slapd.conf *before* database
It is needed by Cyrus to communicate with OpenLDAP.
Configure your OpenLDAP server to notify kolabd if new users are
Your OpenLDAP server has to notify kolabd that users were added,
deleted or edited.
Add this into your
If you OpenLDAP server is a master already, you may have to change the
replogfile directives to match your
Restart your OpenLDAP server now.
When everything is configured, you have to start your Kolab server:
# /kolab/bin/openpkg rc all startDon't forget to add it to your startup scripts.
We have to know how to add users, verify if they work both for Kolab and Samba, and how to remove users.
Go back to the LAM login page - http://kolab.contact.de/lam - and
login as LDAP Manager.
We will create our first Kolab/Samba user, called "Test Tester".
- click on "New user" to add a new Kolab/Samba user,
- click on "Personal", make sure to fill the First name (Test), Last
name (Tester), and eMail address (firstname.lastname@example.org) - see an
If you don't fill
it, things are likely not to work,
- click on "Unix", fill the "User name" (ttester) - login used for
Samba, and a password. Fill the other fields (group, homedir etc.) as
you wish - see an example here,
- click on Samba 3. You don't have to change anything here, although
you may change "User must change password" to something more
appropriate for the first test user - see an example here,
- click on "Kolab", fill "Mailbox home server" (kolab.contact.de),
- click on "Shadow", you may change the "Expiration date" to something
more appropriate for the first test user,
- click on "Main" -> "Create account".
You just created your first Kolab/Samba user. Now some tests.
- getent passwd should list you a user you've just created.
# getent passwd
- you should be able to login on a Windows workstation, that is joined
to the domain
- you should have the user Tester, Test listed in Kolab webadmin
If all that works, you can check if Kolab works with Outlook.
- Download the Toltec connector from http://www.toltec.co.za
- Install the connector. If you don't have a licence key, you can
request a 30-day free evaluation one.
- copy the key to
on a Windows machine
- login as Test user we created before,
- start Outlook,
- configure Toltec plugin according to the instructions on
- share some folders, create some other users, check if sharing works
Converting "Samba only" users to Samba/Kolab users
It's important to mention
existing Samba users will not be able to use Kolab, unless you modify
them with LAM and add the appropriate Kolab values, mentioned above.
If you connect to Kolab using Outlook, and it complains that the
password is invalid, changing user password should fix the problem
(ctrl + alt + del in Windows -> change password).
Removing Samba/Kolab users should be handled by Kolab. This is because
a Samba/Kolab user is not only an entry in the OpenLDAP database - it's
also Cyrus mailboxes. If you delete the user normally, using either
smbldaptools, phpLDAPadmin, or a traditional way in LAM, the user will
be only deleted from OpenLDAP database; mailboxes will stay.
To delete everything (OpenLDAP user entry and mailboxes), do the following:
This will set a special flag on the user's LDAP entry.
- Edit the account in LAM (LDAP Account Manager)
- Choose "Kolab" tab -> press "Mark account for deletion"
- Choose "Main" tab -> press "Modify account"
The account will be deleted automatically by Kolabd; note that it will
not happen immediately, and the user will be still on a user list for a
minute or so.
You will have to change some setting using Kolab webadmin, if your
users wish to keep mail on your Kolab server, and send mails through it
- login to http://kolab.server/admin
- choose Settings - and type your network into "Privileged Networks".
Warning - DO NOT use Kolab webadmin for modifying users, if you use LAM!
It will not work and will break things.
You can use Kolab webadmin safely for other things but editing users
(like Services etc.).
For a discussion on ACLs in OpenLDAP, see this link: http://wpkg.org/Talk:Kolab
- Useful links