[UPDATED] Installing Kolab2 on Ubuntu 11.04 Natty Narwhal

Kolab2 is a great groupware server - and it's the only one that is 100% open source and standards based. Unfortunately it's big - really big - and time consuming to install, understand and maintain. Set aside a half-day to a day, brew yourself a pot of coffee and go through the process outlined in this FAQ if you'd like to have your own Kolab groupware server.


Updated June 2012

This document was originally written in 2011. At that time it was a grossly incomplete collection of notes from an installation that I was making. I wrote it mostly for my own reference - and noticed only long after that the article was surprisingly popular.

Why are so many people installing Kolab? These days it's not at all unusual to meet people who simply refuse to use anything that is not fully open sourced and community supported. This is a big change from the way things were in the 90's when most business people preferred Microsoft products and belittled Open Source. My guess is that Kolab is gaining popularity because it remains the only truly open-source groupware solution on the market. It is reliable and efficient. Kolab is well able to handle the heavy workloads that business users will throw at it. You already knew that, though; that's why you are reading this, right?

So anyway I was somewhat embarrassed when I realized how popular the previous version of this document had become as it was so badly written and incomplete. This update is more complete. Please email your comments to me so that I'll be able to consider your needs when writing future articles. Note also that I don't mind updating this one if you let me know what you want me to add.

Why use 11.04 if we have 12.04?

Why bother to install Kolab on Natty Narwhal when Precise Pangolin is out already? The answer is simple: Kolab is huge - really huge. It is intimately intertwined with a vast array of server components. As a result Kolab is heavily impacted by changes in a server. As I write this Kolab 2.2.4 works perfectly with Ubuntu Server 11.04. I can tell you (because I tried,) that changes in the Perl libraries will force us to edit the Kolab Perl code when installing Kolab 2.2.4 in Ubuntu Server 12.04.

Fortunately the Kolab group does most of the hard work for us - they bundle a version of the Cyrus IMAP daemon, for example, with the Kolab distribution. Eventually a future version of Kolab will be released with all the necessary patches to support the most recent versions of other system components. Until then it's relatively easy to get Kolab running on 11.04. It's not so easy to get it running on 12.04.

A couple of warnings

Installing Kolab on Ubuntu Server is not terribly difficult but it's never a trivial exercise either. I've been installing kolab for a while now and I can tell you it's getting easier but I can't say that it's ever been a fast or simple exercise. There are a great many details to remember and some annoying little problems that need work-arounds. By the time you read this the details will have changed, the current problems will be resolved and some new ones might present themselves.

Please be warned: your needs will be different from mine, your setup will most likely be different from mine and, by the time you read this, the software you will be working with will probably be different from the software that I'm using today (May 2012, Kolab 2.2.4, Horde 4.0.6.) The standard YMMV disclaimer certainly applies here: Your Milage May Vary!

One more warning:

Groupware server failures cause lots of business level problems for the people who rely on them. It's important to take the time to think things through. If your server is connected to the outside world you will have to take appropriate measures to protect it. You will also want to consider basic disk space requirements, partitioning and your backup / recovery strategy. Check the various forums and groups for help if you are not sure what to do or how to do it. None of these topics will be covered in this document.

I hope that you find these notes helpful when setting up your kolab-based groupware server. If you have any questions or comments you can email me at sam at azertech dot net. I look forward to hearing from you.

Getting Started

Basic server setup

Start with a clean install of Ubuntu Server. Set it up as you normally do when setting-up a server.

Again: please pay attention to your disk space and network setup. If you try to go too quickly through the basic install process you might miss some important details so please slow down a bit. For example: Did you remember to reserve some space in your LVM partitions to allow for snapshots?

After completing the installation be careful to test your connectivity and DNS before trying to install Kolab. (Strange things happen when the DNS is not working properly.)

$ # assuming a bare install of ubuntu server - this stuff needed by sam:
$ sudo apt-get install openssh-server emacs23-nox etckeeper git chkconfig
$ # don't forget to configure etckeeper to use git and init the local repo 
$ sudo emacs /etc/etckeeper/etckeeper.conf 
$ sudo etckeeper init
Initialized empty Git repository in /etc/.git/
$ sudo etckeeper commit -m "first commit following initial install"
[master (root-commit) a71f8d1] commit following initial install
 1936 files changed, 87957 insertions(+)
 create mode 100755 .etckeeper
 create mode 100644 .gitignore

Installing Kolab-related packages

Now that the basic server setup is complete we can start installing the basic Ubuntu Kolab packages. Later on we'll need a few other packages (Amavis, Clam, SpamAssassin, ...) so let's get them now also. Some of the packages below are listed as suggested packages (especially for Amavisd-New - like zoo which is used by ClamAV.)

$ sudo apt-get install kolabd kolab-webadmin \
  amavisd-new clamav spamassassin \
  lha arj unrar zoo nomarch cpio lzop \
  cabextract dspam p7zip rpm unrar-free  \
  apt-listchanges libnet-ldap-perl \
  libauthen-sasl-perl libdbi-perl libmail-dkim-perl

Other preparations

Before we try to continue here are some details that we will need to manage. Long ago this was a short list; it's getting longer. Here it is:

  1. Kolab installs a link to a virtual host file, /etc/apache2/sites-available/kolab -> /etc/kolab/apache.conf, which references a self-signed certificate and key pair (/etc/kolab/key.pem and /etc/kolab/cert.pem.) These files are not created until the kolab server is configured - so Apache will not start until then. Kolab also generates configuration files for a number of other daemons (copied by /usr/sbin/kolabconf from /etc/kolab/templates/.) The daemons that need an SSL certificate are all told to use the files in /etc/kolab/ but, again, those files will not exist until later.

    If you have a commercial server certificate you can go ahead and put a copy in the Kolab configuration folder now. Make sure to use the names key.pem, cert.pem and kolabserver-ca.crt and put them in the /etc/kolab folder to satisfy the various references in the system.

    If you need self-signed certificates you can wait until you get to the Kolab configuration (the Kolab bootstrap script will generate them for you,) or, if you need to use apache immediately, you can just use one of the existing demo certificates that are sprinkled around any server. (The locate key.pem command, for example, finds a few candidates in the libssl-doc package.)

    Again: Many people can skip this step as it will take care of itself soon enough. Otherwise, to get daemons like Apache to boot correctly before configuring Kolab, copy an SSL certificate and key pair into the /etc/kolab/ folder; for example:

    $ sudo cp -a /usr/share/doc/libssl-dev/demos/sign/cert.pem \
                 /usr/share/doc/libssl-dev/demos/sign/key.pem \

    You don't need the /etc/kolab/kolabserver-ca.crt file to get apache to start but, if you are installing a commercial certificate, you might as well copy it now. Don't forget to rename it kolabserver-ca.crt.

    It should now be possible to start apache without error:

    $ sudo service apache2 restart
     * Restarting web server apache2
     ... waiting               [ OK ]
  2. Later on we'll need to refer to the original session_vars.php script that comes with the web admin package; let's save a copy right away:

    $ sudo cp /etc/kolab/session_vars.php \
  3. The Kolab software will try to get the ldap daemon, slapd, to read a files in the kolab config directory. Apparmor will not allow this - so the installation will fail.

    If your groupware server, like mine, is on a protected local network you might not be too concerned about attacks from the public internet. In this case you can use the quick and easy work-around of putting apparmor into complain mode for the ldap server, like this:

    $ sudo aa-complain /usr/sbin/slapd
    Setting /usr/sbin/slapd to complain mode.

    If your server is on the public internet, though, it makes no sense to disable any of your system protection. In this case it's a good idea to add the offending files to the list of files that App Armor will recognize for the LDAP server.

    To accomplish this simply edit the App Armor profile for the LDAP daemon, like this:

    $ sudo emacs /etc/apparmor.d/usr.sbin.slapd

    Add the /etc/kolab/rootDSE.ldif and certificate/key files with Read permission, like this:

      /etc/gai.conf r,
      /etc/hosts.allow r,
      /etc/hosts.deny r,
      /etc/kolab/rootDSE.ldif r,
      /etc/kolab/cert.pem r,
      /etc/kolab/key.pem r,

    Finally, you will want to restart App Armor to get it to recognize the changes you just made:

    $ sudo service apparmor restart
     * Reloading AppArmor profiles
                   [ OK ]
  4. The Debian/Ubuntu package management software will start each daemon after it is installed. The Kolab setup software will then complain because it wants them all turned off - but then you will need to restart them all later and, again, stop them from time to time. In practice it's useful to save a script to make it easier to start and stop the various daemons. Below is a super simple one that gets the job done. I keep mine at /etc/kolab/kolab.sh:

    # Start/Stop all kolab-related
    # Usage:
    # Start all: /etc/kolab/kolab.sh start
    # Stop all   /etc/kolab/kolab.sh stop
    ps auxwf |\
       grep -i $LOOKFOR |\
       grep -v $DONTSHOW
    /usr/sbin/service clamav-freshclam $1
    /usr/sbin/service clamav-daemon $1
    /usr/sbin/service saslauthd $1
    /usr/sbin/service apache2 $1
    /usr/sbin/service slapd $1
    /usr/sbin/service spamassassin $1
    /usr/sbin/service amavis $1
    /usr/sbin/service postfix $1
    /usr/sbin/service kolab-cyrus $1
    /usr/sbin/service kolabd $1
    ps auxwf |\
       grep -i $LOOKFOR |\
       grep -v $DONTSHOW

    Why display the running processes? Because under Ubuntu Server 12.04 (at the time of this writing in late May, 2012,) the service command was not stopping the Amavis daemon. Displaying the process list before and after the start/stop operation makes it easy to see what's happening. If a process fails to stop it's easy to type a command (for example sudo pkill amavisd) to finish the job.

    Don't forget to sudo chmod 700 /etc/kolab/kolab.sh so that you can execute it directly.

  5. As I write this there is an annoying little ampersand sign in one of the Kolab scripts. It was perfectly legal when the code was first written but changes to the PHP language have resulted in a PHP E_DEPRECATED code warning. At some point I just got into the habit of editing the character out of the script.

    You will probably be wondering if I remembered to edit /etc/kolab/templates/php.ini.template and change the error_reporting line to read:

    error_reporting    = E_ALL & ~E_DEPRECATED & ~E_WARNING

    Yes, I did. I also remembered to run kolabconf and restart all the daemons using /etc/kolab/kolab.sh restart. Unfortunately, the problem remained so I just edited out the offending character from the script...

    You do not need to do this; but if you decide you want to it's not difficult. Edit /usr/share/horde3/lib/Horde/Kolab/Server/Object.php and remove the ampersand sign in front of the new keyword on line 216:

    $ emacs /usr/share/horde3/lib/Horde/Kolab/Server/Object.php

    The resulting script should look like this:

        function &factory($type, $uid, &$storage, $data = null)
            $result = Horde_Kolab_Server_Object::loadClass($type);
            if (is_a($result, 'PEAR_Error')) {
                return $result;
            if (class_exists($type)) {
                $object = new $type($storage, $uid, $data);
            } else {
                $object = PEAR::raiseError('Class definition of ' 
                                          . $type . ' not found.');
            return $object;

Moving along...

Now that the long list of minor details are all resolved we can get started with the Kolab setup. Kolab will complain if it finds any daemons running - so let's start by stopping them all using the kolab.sh script:

$ sudo /etc/kolab/kolab.sh stop

Once the daemons are stopped we can run the Kolab setup script, like this:

$ sudo kolab_bootstrap -b

The bootstrap script will ask a few basic questions:

  • You can use any password you like for the manager account on the web-based Kolab Admin GUI. The bootstrap script will generate a long and complex one for you which you can override when asked.
  • I've never tried using an IP address for a Kolab server before. If you are asked for a host name and you reply with an IP address I can't say if anything will break or not. I do suggest, however, that you get your DNS updated and tested before you try to get Kolab working.
  • The bootstrap script will offer to generate a self-signed certificate and key file pair in case you want it. That's the last step in the process.

When that's done we can start all the daemons:

$ sudo /etc/kolab/kolab.sh start
 * Starting SASL Authentication Daemon saslauthd  [ OK ] 
 * Starting web server apache2                    [ OK ] 
 * Starting OpenLDAP slapd                        [ OK ] 
SpamAssassin Mail Filter Daemon: disabled, 
              see /etc/default/spamassassin
Starting amavisd: amavisd-new.
 * Starting Postfix Mail Transport Agent postfix  [ OK ] 
Starting Cyrus IMAPd: cyrmaster.
 * Starting Kolab server kolabd                   [ OK ] 

Apache and ClamAV are not complicated from an administrative point of view - they pretty much do what we need them to do. Don't worry about Postfix, Amavis and SpamAssassin just yet - we'll take care of that group of daemons in the next few steps.

At this point there is only one user that exists in what will soon be the new Kolab server. This is the manager account which is created automatically by the bootstrap script. We can try the testsaslauthd utility to query the SASL and LDAP daemons to verify that they are working properly. Use the user id manager and the <password> that was displayed by the bootstrap script as it was finishing, like this:

$ sudo testsaslauthd -u manager -p <password>
0: OK "Success."

You can try it again with the wrong information to verify that it is really working:

$ sudo testsaslauthd -u not_manager -p <not_password>
0: NO "authentication failed"

The above generally works fine for me but, again, the complexity of Kolab is such that all the system components really do need to be working well together or there will be problems. If you run into trouble it's a good idea to work your way through the system, step by step, until you find the problem.

As always: Check all the system log files for hints as to what the problem might be. Google any hints you find in case there is somebody else who has run into the same problem and posted a solution somewhere on the web.

For the most part the above test will generally succeed. Next we will get the web-based GUI working and create one or more user accounts.

The web-based Admin GUI

At this point the daemons are running and the software is mostly installed. Before we can run the web administrative pages it is necessary to set the login information in the file /etc/kolab/session-vars.php.

This process can be automated using a simple script from the Kolab wiki. This is not really important but it can be helpful if you tinker with your installation and need to do this a few times. Copy the following script to /etc/kolab/update-session-vars.sh:


# Update the session_vars.php script
# Copied From:
# http://wiki.kolab.org/index.php/Debian_-_Administrators_-_Kolab_Installation

pushd /etc/kolab

cp -a session_vars.php-saved session_vars.php

sed -i -e "s@kolabserver.example.com@`grep '^fqdnhostname : ' \
   /etc/kolab/kolab.conf | gawk '{ print $3 }'`@" /etc/kolab/session_vars.php
sed -i -e "s@dc=example,dc=com@`grep '^base_dn : ' \
   /etc/kolab/kolab.conf | gawk '{ print $3 }'`@" /etc/kolab/session_vars.php
sed -i -e "s@PASSWORD@`grep '^php_pw : ' \
   /etc/kolab/kolab.conf | gawk '{ print $3 }'`@" /etc/kolab/session_vars.php
sed  -i -e "s@cn=nobody,cn=internal,dc=example,dc=com@`grep '^php_dn : ' \
   /etc/kolab/kolab.conf | gawk '{ print $3 }'`@" /etc/kolab/session_vars.php


Note that the above script is rather simple and it can break fairly easily. Basically it is copying information from the /etc/kolab/kolab.conf file to the appropriate places in the session_vars.php script. The script can fail if there are minor changes made to the Kolab configuration file or the session_vars.php file. It might also get messed-up when you copy/paste it off this web page!

Edit the script carefully, make it executable (ie: chmod 700 ...,) run it and check the output to make sure that the session_vars.php script contains the necessary configuration information:

$ sudo chmod 700 /etc/kolab/update-session-vars.sh
$ sudo /etc/kolab/update-session-vars.sh
$ sudo less /etc/kolab/session_vars.php

If there are any problems with the session_vars.php file (ie: the necessary information was not copied from the Kolab configuration file or it wasn't copied to the right placs,) it will be necessary to either fix the update script or update the session_vars.php file manually.

Once that's done the administrative GUI should be working. You can try it by pointing your browser to https://<hostname>/admin/. Don't forget to use the S in https:// as you won't find anything at the non-ssl version of the URL.

Note that the Kolab setup program, kolab_bootstrap, created a self-signed certificate. At this point your browser will be seeing the certificate for the first time and, before you can see the page under it, it will complain that the connection is not trusted. In fact the connection is secured against most packet sniffing so it's okay to use the self-signed certificate. The only real problem is that the browser does not recognize the authority that signed the key (you!)

The simple solution here is to tell the browser to accept the certificate. If you are using Firefox you can click on "I Understand the Risks," followed by "Add Exception." You can then view the certificate and, when ready, click on "Confirm Security Exception."

If your session_vars.php script was properly updated you will see the Kolab Admin login screen. If the settings are wrong you will see, in the middle of the login screen, a little box with the title, "Errors:" and an error message. Correct any errors and, finally, enter your user name and password into the login boxes and press Login.

When you first log into the Kolab admin pages you will see a reminder. The two steps that the reminder is asking you to do are (1) create an administrative user and (2) add the user to each of the mailing lists.

Once the new user is created (and after waiting a few seconds for Kolab to update itself,) you can try the testsaslauthd utility to verify that the account is being recognized:

$ sudo testsaslauthd -u <uid> -p <password>
0: OK "Success."

Once you have done that you will want to browse around the interface. In particular you will want to check the Settings page. The minimum you will need to do is check the settings for Privileged Networks and, if you are using an external mail relay, the SMTP SmartHost / Relayhost setting.

The first test email

Finally, it's time to test if you can submit an email into the system. Don't copy and paste the command below. Create an account for yourself on your server using the Admin GUI and send yourself an email. Then check the mail log like this:

$ echo "testing" | sendmail <uid>
$ sudo less /var/log/mail.log

It's not fun to read the mail log but you really need to force yourself to do it and learn to pay attention to all the little details.

Most likely your email did not pass cleanly into your test account. You might see, for example, some PHP warnings and some postfix database out-of-sync errors (ie: warning: database /etc/postfix/canonical.db is older than source file /etc/postfix/canonical.)

We'll get back to the PHP warnings a bit later. You can update a Postfix database files using the postmap command, like this:

$ sudo su --login
# cd /etc/postfix
# postmap canonical
# exit

Execute the postmap command once for each database that is out of date.

At some point you will might be interested to see the file in the mail spool, like this:

$ sudo find /var/spool/cyrus/mail

(The list of cache directories for Cyrus is actually quite long - I've only shown a few of them.) The email that we're looking for is #1 in the manager folder. You might want to have a look at it to see the mail headers:

$ sudo less /var/spool/cyrus/mail/domain/k/<server>/m/user/manager/1.

It should look good except that there's no spam or virus report in the header.

Amavis, SpamAssassin & ClamAV

At this point we can start configuring the AntiSpam and AntiVirus components of the system. As you can imagine these components represent a whole world of work that needs to be done. The AntiVirus work is mostly handled by volunteers through projects like ClamAV but the AntiSpam setup involves much more than just setting-up Amavis and SpamAssassin. Here are some reference pages you can use as starting points for your study of this field:

Kolab Configuration Templates

The main thing you need to know when working with Kolab is that Kolab keeps a set of configuration file templates in /etc/kolab/templates. These files are read by a utility called /usr/sbin/kolabconf, updated to include information from the Kolab configuration and written to the various files that are used by the various daemons.

In practice this means that you will lose your configuration edits if you try to edit the daemon configuration files directly.

This is really easy to forget while browsing various articles on the web. In fact sometimes you may be tempted to initially make changes to the configuration files that are being used by a given daemon. You will want to try to get things working and then update the Kolab template files. In practice, though, Kolab might need to update itself and, in the process, might overwrite any changes you have not posted to the template files.

Take a peek at the template files so that you can see what I'm talking about:

$ sudo su --login
# cd /etc/kolab/templates/
# ls
ldap.conf.template    php.ini.template    slapd.conf.template                     
amavisd.conf.template imapd.conf.template smtpd.conf.template
cyrus.conf.template   main.cf.template    saslauthd.conf.template

There are thirty files in that folder as I write this and they cover a wide range of services within the server. I can't stress this point enough: it is really important to try to remember to check the templates folder before making configuration changes on your Kolab server. Then, to process your changes and update the copies that the daemons are reading, you need to run the Kolab Configuration script and restart the relevant service.

To keep track of your configuration changes I suggest you try etckeeper if you haven't tried it yet. It scans the entire /etc/ folder and uses git to keep a history of any changes you take the time to commit, like this:

$ sudo etckeeper commit -m "checking-in prior to making changes"
$ sudo emacs /etc/kolab/templates/<service template>
$ sudo etckeeper commit -m "checking-in the latest changes"
$ sudo /usr/sbin/kolabconf
$ sudo /etc/kolab/kolab.sh restart #(often unnecessary after kolabconf)

Using etckeeper you can use git to find out what changed from one point in time (when things were working fine,) and another (when something went wrong.) Git can also be used to restore previous versions of files in the /etc/ directory.

Note that kolabconf tries to be smart about restarting services. At some point I got into the habit of restarting them all but this is often not necessary.


Amavis (or, as the authors prefer, AMaViS,) is A Mail Virus Scanner for Unix systems. We will now follow the instructions (from the Ubuntu Postfix / Amavis page,) to get Amavis to perform the desired scanning:

Start by editing the /etc/amavis/conf.d/15-content_filter_mode file (there is no corresponding file in /etc/kolab/templates/ so it's okay to edit this file directly:)

$ sudo emacs /etc/amavis/conf.d/15-content_filter_mode

Uncomment the appropriate lines as per the instructions in that file. Your results should look something like this:

# Default antivirus checking mode
# Please note, that anti-virus checking is DISABLED by
# default.
# If You wish to enable it, please uncomment the following lines:

@bypass_virus_checks_maps = (
   \%bypass_virus_checks, \@bypass_virus_checks_acl, 

# Default SPAM checking mode
# Please note, that anti-spam checking is DISABLED by
# default.
# If You wish to enable it, please uncomment the following lines:

@bypass_spam_checks_maps = (
   \%bypass_spam_checks, \@bypass_spam_checks_acl, 

Now enable SpamAssassin by editing /etc/default/spamassassin. Your results should look like this:

# Change to one to enable spamd

# Options
# See man spamd for possible options. The -d option is automatically added.

# SpamAssassin uses a preforking model, so be careful! You need to
# make sure --max-children is not set to anything higher than 5,
# unless you know what you're doing.

OPTIONS="--create-prefs --max-children 5 --helper-home-dir --syslog mail"

# Pid file
# Where should spamd write its PID to file? If you use the -u or
# --username option above, this needs to be writable by that user.
# Otherwise, the init script will not be able to shut spamd down.

# Set nice level of spamd
#NICE="--nicelevel 15"

# Cronjob
# Set to anything but 0 to enable the cron job to automatically update
# spamassassin's rules on a nightly basis

It is necessary to set Enabled and Cron to true. Redirecting the log output to the syslog is a generally good idea but it's optional.

Next we need to add Amavis to the ClamAV group and vice-versa:

$ sudo adduser amavis clamav
$ sudo adduser clamav amavis

Note that the instructions in the Ubuntu Server documentation tell us to configure Postfix to filter content through Amavis. If we grep the main.cf file we discover that Kolab is already filtering the content:

$ sudo grep filter /etc/kolab/templates/main.cf.template 
content_filter = kolabfilter

The same is true of the changes that would be made in the master.cf file: The Kolab people have already made the necessary changes in their configuration template.

PHP Errors

You may be seeing some PHP-related errors in the log files related to changes in the PHP language that took place after the Kolab code was written. In theory these can be stopped by changing the error_reporting setting in /etc/kolab/templates/php.ini.template. In practice that's not enough - but it's probably worth doing. Set it to E_ALL & ~E_DEPRECATED & ~E_WARNING to disable the deprecated code and other code-related warnings, like this:

error_reporting    = E_ALL & ~E_DEPRECATED & ~E_WARNING

Don't forget to update the system:

$ sudo kolabconf
$ sudo /etc/kolab/kolab.sh restart

Again, I've done this but I still get warnings in my log files <sigh>. Please drop me a note if you know why?

Spam Detection & Handling

Let me repeat that Spam and Virus scanning is an area where you will want to do plenty of research. You will want to figure out what you need and how much effort you want to make to get the best possible results for your user community. Once you've figured out what you want to do you can customize your system settings.

For now, though, you probably just want to enable additional logging so that you can verify that everything is working as desired and/or figure out where to look if things are not working as desired.

To get (too much) log information from Amavis add $log_level = 5; to the /etc/amavis/conf.d/50-user file. After you get things working you will want to remove this line or perhaps just reduce the log level - 5 really does generate too much information.

There are a number of issues that might prevent SpamAssassin from adding the X-Spam-Status header to your emails. Try setting $sa_tag_level_deflt = -99; in /etc/amavis/conf.d/50-user so that the reports will be enabled even if the spam score is very low (such as when your test emails are coming from the local server.)

Check the 20-debian_defaults file in the same directory (/etc/amavis/conf.d/) for some settings that are often customized such as the spam scores/levels that trigger reports and other actions. You can copy them into the 50-user file and edit them to reflect the settings that are appropriate for your needs.

Another common change, this one in /etc/spamassassin/local.cf, forces SpamAssassin to emit the X-Spam-Report and other headers for all emails. To accomplish this you want to clear the default headers and restore them, like this:

#   Save spam messages as a message/rfc822 MIME attachment instead of
#   modifying the original message (0: off, 2: use text/plain instead)
report_safe 0

add_header all Flag _YESNOCAPS_
# Keep the following text together on one line:
add_header all Status _YESNO_, score=_SCORE_ 
  required=_REQD_ tests=_TESTS_ autolearn=_AUTOLEARN_ 
add_header all Level _STARS(*)_
add_header all Checker-Version SpamAssassin _VERSION_ (_SUBVERSION_) on _HOSTNAME_
add_header all Report _REPORT_

NOTE: Please don't copy and paste the above text too quickly. Each add_header line above must be all together on one line.

Setting report_safe to zero prevents SpamAssassin from trying to convert spam emails into attachments. The keyword all in the add_header lines ensures that the header lines appear in all emails.

Finally we want to run kolabconf to update the configuration scripts, then restart all the daemons so that we can send another test email:

$ sudo kolabconf
$ sudo /etc/kolab/kolab.sh restart
$ echo "this is a test" | /usr/sbin/sendmail <uid>

Check /var/log/mail.log to see if everything went as expected. If you run into any trouble it's a good idea to review the steps above and check every part of the server, step by step, to find the problem.

Next Steps

At this point you have a working Kolab server but there is still more work to do:

  • If your server is connected to the public internet you will need to setup your firewall before you do anything else.
  • Create a test account and get a mail client such as Thunderbird to talk to your Kolab server.
  • If you have a mail spool from a previous Cyrus installation you will want to create your user accounts and reconstruct your mail indexes. Remember that Kolab bundles a customized version of Cyrus and Ubuntu customizes the Kolab packages. As such the documentation that you find on the web will refer to utilities that exist in your server but have different names and are in different folders. You will need to poke around to get things done.

    Note that the mailstore reconstruct command in the Kolab packages compiled for Ubuntu Server is run like this:

    $ sudo -u cyrus /usr/sbin/cyrreconstruct -f -r user/<uid>

    Reconstruction is, as they say in the documentation, very slow. To make matters worse the -m option is apparently broken so you need to manually reconstruct each user account separately.

  • Setting up an automated nightly backup is probably the biggest remaining priority. As Kolab is a groupware server you know in advance that even the smallest little problem will turn into a nightmare for your company. In that sense the nightly backup is probably more critical than we want to admit.


One last time I must repeat that Kolab touches every aspect of a server. As such it's really important to be methodical in your approach to problem solving.

Check your log files if you are having any trouble as they often contain clues as to where you need to look to solve a problem. Enable logging of debug information in all the daemons, send an email to a test account and follow the progress of the email through the system.

  • Did you verify your DNS settings? Lots of strange things happen when there are DNS problems on your network. Does your hostname work properly? Does the name map to your server IP and vice-versa? Make sure you are using the host name that you used when you ran the kolab bootstrap script. (You can run the bootstrap script again, if necessary, but it will wipe out your user accounts and passwords.)
  • Did you properly create a user in the web-based GUI? Is the new user configured to receive the system mail? Did you enable the services that you are trying to use?

Remember that most of the problems that you might run into have already been experienced by other administrators. Be persistent in your searches for information. Sometimes the answer you need is buried deep in the search results but keep reading and you will find it.

Please take a moment to let me know if you find this article helpful? Is there is anything you feel I should add or change? Let me know. You can email me at sam at azertech dot net. I look forward to hearing from you. Thanks!