Samba and Kolab Groupware integration

Tomasz Chmielewski, kolab [at] wpkg [dot] org

Last updated: 24.11.2005


You can always find the latest version of this document on http://wpkg.org/kolab.

This article explains how to add Kolab Groupware functionality to your existing Samba/OpenLDAP setup.



From the Kolab website:

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 Service.
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 server 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)!

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



Contents:

  1. Downloading, compiling and configuring Kolab
  2. Downloading, installing and configuring useful tools
  3. Configuration
  4. Testing
  5. Useful links



  1. Downloading, compiling and configuring Kolab
Download Kolab sources first
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 server/release/kolab-server-2.0.1/sources/.

Compile Kolab

Compiling Kolab is easy. After you downloaded Kolab, run the obmtool script:

# ./obmtool kolab

The whole process of compiling will take an hour or two, depending on your hardware.
Kolab will be installed to /kolab.


Make a backup of a fresh Kolab installation

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


Change configs 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 /kolab/etc/kolab/templates/kolab.conf.template, change:
   
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 /etc/openldap/slapd.conf file).


Bootstrap (configure) 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 need.
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 server.
Click here to see example answers.

If you think you misconfigured something, just remove /kolab, and restore it from /kolab.orig (you did the backup, didn't you?).


Advanced configuration

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 (joe@example.com, mary@example.com etc.).

When you set up Kolab with kolab_bootstrap command, it 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 dc=contact,dc=de.

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:

  1. Downloading and installing useful tools
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 time.


Download, install and configure phpLDAPadmin




Download, install and configure LAM - LDAP Account Manager






  1. Configuration

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:


Stop Kolab's OpenLDAP server

When you exported and saved the ldif file, you can stop Kolab's OpenLDAP server:

# /kolab/bin/openpkg rc openldap stop


As Kolab's OpenLDAP server will be no longer needed, move /kolab/etc/rc.d/rc.openldap 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):

include /kolab/etc/openldap/schema/rfc2739.schema
include /kolab/etc/openldap/schema/kolab2.schema

Place it after the last "include" line in your slapd.conf file.

If you have more OpenLDAP servers (slaves), copy these schema files and add the above include directives.

Make sure that the OpenLDAP starts (not the one from Kolab, but the one you use for Samba):

# /etc/init.d/ldap start
Starting slapd (ldap):                                          [  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 LDAP server?).


Import Kolab LDAP database into the OpenLDAP used by Samba

Edit the ldif file you exported earlier with phpLDAPadmin - comment out the first entry:

# Entry 1: dc=contact,dc=de
#dn: dc=contact,dc=de
#dc: contact
#objectClass: top
#objectClass: domain

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

If you want to import the ldif file from the command line, copy the ldif file to the Kolab server first:

# scp contact.ldif manager@kolab.contact.de:

Then import the ldif file:

kolab# ldapadd -x -D "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>" -W -f <LDIF-FILE>

which in our case, is:

kolab# ldapadd -x -D "cn=Manager,dc=contact,dc=de" -W -f /home/manager/contact.ldif
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

Add:

allow bind_v2

to /etc/openldap/slapd.conf *before* database definitions.

It is needed by Cyrus to communicate with OpenLDAP.


Configure your OpenLDAP server to notify kolabd if new users are added

Your OpenLDAP server has to notify kolabd that users were added, deleted or edited.
Add this into your slapd.conf file:

lastmod on

replica uri=ldap://127.0.0.1:9999
    binddn="cn=replicator"
    bindmethod=simple
    credentials=secret

replogfile /var/lib/ldap/replog

If you OpenLDAP server is a master already, you may have to change the lastmod and replogfile directives to match your config.

Restart your OpenLDAP server now.


Start Kolab

When everything is configured, you have to start your Kolab server:

# /kolab/bin/openpkg rc all start

Don't forget to add it to your startup scripts.

  1. Testing

We have to know how to add users, verify if they work both for Kolab and Samba, and how to remove users.


Adding 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 (test@contact.de) - see an example here. 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.


Verifying setup

- getent passwd should list you a user you've just created.

# getent passwd
(...)
ttester:x:10000:513:Test Tester:/home/ttester:/bin/false

- 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 C:\Program Files\Toltec\toltec.key on a Windows machine
- login as Test user we created before,
- start Outlook,
- configure Toltec plugin according to the instructions on http://www.toltec.co.za
- share some folders, create some other users, check if sharing works etc.


Converting "Samba only" users to Samba/Kolab users

It's important to mention that 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 users

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

Additional settings

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 (through Postfix)

- 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


  1. Useful links
http://kolab.org The Kolab Groupware Project
http://samba.org Samba home page
http://openldap.org OpenLDAP home page
http://lam.sf.net LDAP Account Manager (LAM) is a webfrontend for managing accounts stored in an OpenLDAP server
http://phpldapadmin.sf.net Web-based LDAP browser to manage your LDAP server
http://wpkg.org
 WPKG - software deployment and upgrade tool (deploy software to Windows workstations with Samba)