User:Aeneas jaissle/SDB:Kolab 3

Jump to: navigation, search
openSUSE Support Database
Portal - SDB Categories - How to write an article


Kolab is a secure, scalable and reliable groupware server. It is formed by a number of well-known and proven components and adds intelligent interaction between them.
In case you're an openSUSE community member you can vote to have openSUSE support Kolab. Make sure to vote, if you like Kolab on openSUSE!

What is 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 and Web Service.[1]

Components:

  1. 389 Directory Server as the default LDAP server component
  2. Postfix for delivering mails
  3. Cyrus IMAP as for storage and IMAP connectivity
  4. amavisd-new, SpamAssasin and ClamAV for spam detection and virus scanning
  5. Roundcube Webmail as a web mailer
  6. Kolab services, content filter, definitions and bindings

See Kolab for more information.

Installation Process

In general, the installation process consists of the following:

  1. Add the repositories
  2. Install the wanted components
  3. Modify the config file
  4. Run the kolab setup routine

This section will describe these steps in detail.

Repositories

To install Kolab, you need to add the server:Kolab:UNSTABLE and the server:Kolab:Extras repository. There is also a server:Kolab:STABLE repository, containing stable and tested packages. Currently no stable packages are available, so don't use it.

The following will add the required repositories (UNSTABLE and Extras) on openSUSE 12.3 and refresh the repository cache:

zypper addrepo http://download.opensuse.org/repositories/server:/Kolab:/UNSTABLE/openSUSE_12.3 server:Kolab:UNSTABLE
zypper addrepo http://download.opensuse.org/repositories/server:/Kolab:/Extras/openSUSE_12.3 server:Kolab:Extras
zypper refresh

Here you can find other examples on how to add a repository.

Version: 12.2


Version: 12.3


Version: Factory


Version: SLE 11 SP2


If you require repositories for additional SUSE versions, drop the packagers a note!

Packages

Once the repositories have been configured, Kolab and all its dependent packages can be installed:

zypper install kolab

or - if you only want to install the ldap components for Kolab 3,

zypper install kolab-ldap
Package Summary
kolab Kolab Groupware Server meta package for single server installations
kolab-conf Kolab Groupware Configuration Utility packages meta package
kolab-imap Kolab Groupware IMAP component meta package
kolab-ldap Kolab Groupware LDAP components meta package
kolab-mta Kolab Groupware Mail Transfer Agent meta package
kolab-webadmin Web based admin- and user interface for the Kolab Groupware Server
kolab-webclient Web based mail client for the Kolab Groupware Server

For single server installations, an additional package kolab-scripts is recommended to simplify installation:

zypper install kolab-scripts

Pre-Installation

Instructions for single server installations

Kolab requires a few system adjustments (best before installation) to run; running

kolab-pre-setup

will trigger a script, that is

  1. checking for a fully qualified host name
  2. updating your system to ensure you are using the latest packages and bug fixes,
  3. checking for a present ca and server certificate or creating a certificate authority and a self signed server certificate, if none is present,
  4. giving users cyrus and postfix access to the certificates,
  5. creating a user_deny.db for cyrus-imapd and
  6. updating the ClamAV virus definition database.

You can

cat /usr/sbin/kolab-pre-setup

to see in detail what commands are used for this task.

Installation

Instructions for single server installations

After preparing the system, you can start the setup using:

kolab-setup

Because of the many services involved (and for higher security), the setup script will ask for a lot of password values:

  • LDAP administrator - used to login to the graphical console of 389 Directory Server
  • LDAP Directory Manager (cn=Directory Manager) - the administrator user you will be using to at least initially log in to the Web Administration Panel, and that Kolab uses to perform administrative tasks
  • Cyrus Administrator - used by Kolab to execute administrative tasks in Cyrus IMAP
  • Kolab Service account - used by services such as Postfix and Roundcube to create a bind to the LDAP server
  • MySQL root user - administrative user for the MySQL server. Kolab will only require this for installation and forget about it afterwards. You still need to know this for administrative tasks like backups and such.
  • MySQL 'kolab' user - used by Kolab services, such as Web Administration Panel.
  • MySQL 'roundcube' user - used by the Roundcube Webmail interface.

Post-Installation

Instructions for single server installations

After the setup, you should be able to log into the Kolab Web Administration Panel. The Kolab Web Admin is located at http://''serveraddress''/kolab-webadmin, where serveraddress is your respective server address or host name. For your first login, you have to use "cn=Directory Manager" as the user name, and the password you provided during setup.

Kolab-webadmin login.png

Hints and Tweaks

Add an alias to one of your users, that will accept email from root@domain.tld. In case e.g. cron sends an email notification, the email will arrive at the user that has the alias set for the root.

An even nicer solution is, to have the emails sent to a distribution list e.g. cron@domain.tld. In your cron scripts you should have your emails sent to cron@domain.tld in that case.

Groupware testing

Free/Busy support

  1. Create a calendar entry in one of your users calendars
  2. Run 'kolab-freebusyd --generateall' or wait for cron to run this

This generates and aggregates Free/Busy information for every user. The information is saved at /var/lib/kolab-freebusy/user@domain.tld.ifb

  • Open a browser and point it to:
    • https://@servername@/freebusy/user@domain.tld.ifb
    • https://@servername@/freebusy/user@domain.tld.xfb
    • https://@servername@/freebusy/trigger/user@domain.tld/FOLDER.pfb (replace FOLDER with your Kalendar folder for instance)

All of these urls should show your ical formatted data.

In the urls above user@domain.tld is a user you have created with the kolab web admin interface before.

  • Curl could be used for testing the freebusy components as well (it's ten times faster than doing everything with the preferred browser):
curl -u user@domain.tld:password -k -X GET \
https://@servername@/freebusy/trigger/user@domain.tld/FOLDER.pfb

Use this freebusy test script to test the freebusy functionality. 

#!/bin/bash
# See: http://kolab.org/cgi-bin/viewcvs-kolab.cgi/doc/architecture/freebusy.txt

# The server that runs the kolab server
SERVER=yourserver
# The user and password that logins to the kolab server (user@domain.tld)
LOGIN_USER=youruser
PASSWORD=youruser_password

# The user for whom the Free Busy information is requested
FB_USER=

if [[ -z "$PASSWORD" ]]; then
  echo "error: password is required" >&2
  exit 1
else
 _PASSWORD=:$PASSWORD
fi

_LOGIN_USER=$(echo $LOGIN_USER | sed 's/@/%40/')
[[ -z "$FB_USER" ]] && FB_USER=$_LOGIN_USER

HTTP=yes
if [[ "$HTTP" == "yes" ]]; then
  PROTOCOLS="http https"
else
  PROTOCOLS="https"
fi

for PROT in $PROTOCOLS; do

  echo === $PROT ifb ===
  curl -k $PROT://${_LOGIN_USER}${_PASSWORD}@$SERVER/freebusy/$FB_USER.ifb
  echo

  echo === $PROT xfb ===
  curl -k $PROT://${_LOGIN_USER}${_PASSWORD}@$SERVER/freebusy/$FB_USER.xfb
  echo

  echo === $PROT pfb with trigger ===
  curl -k $PROT://${_LOGIN_USER}${_PASSWORD}@$SERVER/freebusy/trigger/$FB_USER/Calendar.pfb
  echo

  echo === $PROT pfb ===
  curl -k $PROT://${_LOGIN_USER}${_PASSWORD}@$SERVER/freebusy/$FB_USER/Calendar.pfb
  echo

  echo === $PROT pxfb ===
  curl -k $PROT://${_LOGIN_USER}${_PASSWORD}@$SERVER/freebusy/$FB_USER/Calendar.pxfb
  echo
done

Clients

KDE client configuration

The client configuration, based on KDE's Kontact is described in kolab server 2 and kde client configuration. Note, Kolab uses Submission (Port 587) for incoming mails from human beings.

If the groupware functionality works and Kontact is configured correctly, you should see should be able to see the following picture:

Groupware functionality provided by kolab on openSUSE in korganizer


Web client

Kolab 3.x has it's own modified Roundcube Webmail (more precise: uses Roundcube Webmail plus various plugins). To use it, install the kolab-webclient package:

zypper install kolab-webclient

After installation you can access it from http://@servername@/roundcubemail. Note that @servername@ should be the same as given while running kolab-bootstrap.

If you have problems getting the login from webclient, check the error_log of apache.

Don't forget to check your calendar!

Don't forget to check your calendar, as shown in the screenshot on the right. If the calendar is not checked it is not displayed. Although you can schedule events successfully....

Personal Information synchronization

If you want to synchronize e.g. your mobile phone with your information stored in the Kolab server, you can do so by installing the kolab-syncroton package:

zypper install kolab-syncroton

On single server installations, this package is installed by default. After installation, you can check http://servername/Microsoft-Server-ActiveSync and log in with your Kolab user credentials. If everything is working, you should see your User ID and IP address displayed. 

It works!
Your userid is: 14 and your IP address is: 192.168.154.52.

Backups

During kolab_bootstrap many config files are written to disk. Some of these will overwrite your config files. The config files to be created during kolab_bootstrap, can be determined with: 

/etc/kolab/templates # sed -n 's/^.*TARGET=//p' *

For example:
/etc/amavisd.conf
/etc/clamd.conf
/etc/cyrus.conf
/etc/freshclam.conf
/etc/imapd.conf
/etc/kolab/kolab_smtpdpolicy.conf
/etc/openldap/ldap.conf
/etc/postfix/ldapdistlist.cf
/etc/postfix/ldaptransport.cf

The original config files are saved (backed up) to /var/adm/backup/kolab/kolab_backup-orig.tar.bz2 during the first execution of kolab_bootstrap.

Please, let us know if things can be improved. This can be done on the talk page of the wiki page, and on the kolab-devel (at) kolab (dot) org emaillist. In case you use the talk page, inform the packagers with an email to the before mentioned emaillist. Include in the email that it concerns kolab on suse.

Troubleshooting

Useful commands for debugging

Get a list of installed Kolab packages:

rpm -qa "*kolab*"

LDAP Troubleshooting

Check the following for errors (replace HOSTNAME with your 389-ds instance name):

systemctl status dirsrv.target
systemctl status dirsrv@HOSTNAME.service
cat /var/log/kolab/pykolab.log
cat /var/log/messages
cat /var/log/dirsrv/slapd-HOSTNAME/errors
cat /var/log/dirsrv/slapd-HOSTNAME/access

If the setup script did its job and created a 389-ds instance, you can try to start this instance manually:

systemctl restart dirsrv.target
systemctl restart dirsrv@HOSTNAME.service

And if this instance is created but not starting when

systemctl start dirsrv.target

if performed, have a look at /etc/systemd/system/dirsrv.target.wants/ and check if it's empty. A link named dirsrv@HOSTNAME.service should exist inside.

Reset a broken Installation to do a re-install

If you canceled an installation or the setup hung, or if you just want to reinstall a working Kolab server from scratch, you first need to get rid of any created MySQL databases and 389-ds LDAP server instances.

Icon-warning.png
Warning: The following will completely delete the LDAP instances and all MySQL databases. The next steps are only recommended, if you backed up all data or you were doing a fresh install

To remove the LDAP instances:

systemctl stop dirsrv.target
rm -r /etc/dirsrv/slapd-*

To remove the MySQL databases:

systemctl stop mysql.service
rm -r /var/lib/mysql/*

Starting with kolab-scripts version 0.3, there is a script kolab-cleanup-and-start-over, which removes everything Kolab related.

Icon-warning.png
Warning: The following is even more evil!
kolab-cleanup-and-start-over

Change a user's UID via kolab-webadmin

Add the following to /etc/kolab/kolab.conf: 

[kolab-wap]
...
admin_auto_fields_rw = true

See Also

TODO

The following has to be integrated into this (or the development) wiki page:

  • write steps about editing the kolab-pre-setup configuration file (/etc/kolab/kolab-pre-setup.conf) before starting kolab-pre-setup
  • write steps about editing the configuration file (/etc/kolab/kolab.conf) before starting kolab-start-setup
    • Increase verbosity: add "devel-mode = 1" and "debug-mode = trace" to /etc/kolab/kolab.conf's [kolab_wap]
  • add other categiories
  • Details on the Kolab system accounts:
    • kolab (Kolab System Account / management)
    • kolab-n (Kolab System Account (N) / non-privileged)
    • kolab-r (Kolab System Account (R) / restricted)
  • Describe 389-ds debugging
    • dirsrv@*.service not starting -> present in /etc/systemd/system/dirsrv.target.wants/?
  • dirsrv-admin package needs to use systemd instead of init.d (init-scripts are broken)
  • amavisd.conf hostname checks / uname -n does not provide a FQDN
  • The following has to be filled while doing the certificate setup:
    • PEM passphrase, as well as the verification
    • Country Name
    • State or Province Name
    • Locality Name (eg. city)
    • Organization Name
    • Common Name (must match your server fqdn)
  • LDAP Troubleshooting:
    • ldapsearch -x -h localhost -p 389 -b 'cn=kolab,cn=config' -D 'cn=Directory Manager' -w 'password'
    • ldapsearch -x -h localhost -p 389 -b 'dc=ajaissle,dc=de' -D 'cn=Directory Manager' -w 'password'
  • Update kolab-webadmin to latest git snapshot
  • setup_php.py: Timezone has to be Continent/City instead of UTC, CET or alike. Eg. 'Europe/Berlin'
  • Debug sieve
    • gnutls-cli --starttls -p 4190 localhost + STRG-D after getting "STARTTLS" OK
    • telnet localhost sieve -> CAPABILITY -> check for auth mechs after "SASL"
  • Debugging helper: main.cf -> ignore_mx_lookup_error = yes
  • Wallace not starting: Use libkolab/libkolabxml from server:Kolab:UNSTABLE instead of the one shipped with openSUSE: # zypper in --from server:Kolab:UNSTABLE libkolab0 libkolabxml0

Debugging commands: 

rpm -qf /usr/lib64/python2.7/site-packages/_kolabformat.so
nm /usr/lib/debug/usr/lib64/python2.7/site-packages/_kolabformat.so.debug | grep sy.*ERKS0
mailx
kolab:/etc/cron.d # kolab-freebusyd --generateall
systemctl list-units | grep -Ei "kolab|apache|cyrus|postfix|clamd|amavisd|sql|wallace|dirsrv" --colour=never
systemctl status wallace.service
for service in "kolabd kolab-saslauthd dirsrv.target dirsrv@`hostname -s` mysql postfix wallace apache2 amavisd clamd"; do systemctl status $service; done
  • kolab-freebusy: how does it work, where can I find generated files and logs? Example config
  • SQUAT error in /var/log/messages: can be ignored. An index is missing, but will be build everyday at 05:30 in the morning (see /etc/cyrus.conf). If you want to, you can build the index by yourself, running "# /usr/lib/cyrus/bin/squatter -s -i"
  • Using Shared Folders
    • Shared Folders in Kolab 3.1: Management through kolab-webadmin, all included in Kolab
    • Shared Folders in Kolab 3.0:
      • echo "postuser: shared">>/etc/imapd.conf
      • systemctl restart cyrus.service
      • kolab cm "shared/FOLDERNAME@DOMAIN"
      • kolab set-mailbox-metadata "shared/FOLDERNAME@DOMAIN" "/shared/vendor/kolab/folder-type"
      • Metadata value: contact, event (for calendars), task, note, journal, mail (default if not set)
      • kolab list-mailbox-metadata "shared/FOLDERNAME@DOMAIN"
      • Adjust SAM (see https://wiki.kolab.org/IMAP_ACL for permissions). You can use kolab sam <mailbox> <userid> <permissions> instead of cyradm.
      • kolab lam "shared/FOLDERNAME@DOMAIN"
  • Groupware Client: Kontact
    • Kontact/KAddressbook LDAP connection: The following connection params were tested on openSUSE 12.3 with Kontact/KAddressbook 4.10.3 and 4.10.4 and are working.
USER: -
Bind-DN: uid=USERNAME,ou=People,dc=DOMAIN,dc=TLD
Passwort: *******
Server: FQDN or IP
Port: 389
LDAP version: 3
DN: or=people,dc=DOMAIN,dc=TLD
Security: no
Auth: Simple
Attributes: change Formatted Name to "displayName" and email alias to "alias"
  • Trust local, self-generated CA
    • kolab-freebusyd may flood its log with some "CA not trusted" warnings; to solve this, do the following (single-server install on 12.3 assumed):
 # Show cert's hash:
 openssl x509 -hash -noout -in /etc/ssl/cacert.pem
 # We want a link to our cacert.pem name after the hash inside of /ets/ssl/certs:
 ln -s /etc/ssl/cacert.pem /etc/ssl/certs/`openssl x509 -hash -noout -in /etc/ssl/cacert.pem`.0
     - if there is already a link with the same hash but different certificate, we just increment -
 ln -s /etc/ssl/cacert.pem /etc/ssl/certs/`openssl x509 -hash -noout -in /etc/ssl/cacert.pem`.1
 # run update-ca-certificates
 update-ca-certificates -v -f

Retrieved from "https://en.opensuse.org/index.php?title=User:Aeneas_jaissle/SDB:Kolab_3&oldid=66730"