Title: Author(s): BBKing
Date: 02 Oct 2011
Version(s): 2.0, 2.2
Zentyal profiles: Zarafa

The reason for creating this howto is to share my experiences with others (many of the topics covered here come up very often in then forum) and to document the changes I made to finally have a working sync groupware I've been dreaming of the last 5 years...;)

Enabling Zarafa is pretty straight forward. People, who used to access their mails through Roundcube, might be confused when it comes to enabling Zarafa. I recommend to disable the Webmail interface in "Module Status" and assign IMAP + IMAPS services to Zarafa under the "Groupware" menue.

The reason for this is as follows: to my understanding DoveCot serves you your mails over IMAP/IMAPS when you access them through RoundCube. The path to the mailboxes is /var/vmail/<domain>/<username> Zarafa stores the emails in MySQL, and because of a config dependency RoundCube relies on either IMAP or IMAPS and I haven't managed to configure it to access Zarafa.

Important: I just have found out, that the domain you specifiy under Groupware/Virtual domain must be the first email address entry on the User properties page! Otherwise the mails will be still delivered to dovecot and not through Zarafa! So e.g. your virtual domain in Zarafa is snakeoil.com, your user MUST have its first email-address like myuser@snakeoil.com !

Moving mails to Zarafa

So having activated IMAP+IMAPS for Zarafa, you can copy your old mails from your old server over to Zarafa (I recommend not to switch off the existing server until the new one is running perfectly!). Copying mails is covered well in Documentation/Community/HowTo/MigrateMailToZarafa , just don't forget that your old mailserver needs the user@… username format, while Zarafa is happy with the username only. If you have problems with imapsync, you can try  http://www.yippiemove.com/, they offer a mail migration service - it's not free and I haven't tried the service yet.

Migrating BlackBerry data over Outlook, moving Outlook .pst files to Zarafa

I had to backup my contacts from my BlackBerry to outlook and then export it from there to Zarafa. To do so, install the Zarafa client and the Zarafa Migration Tool on Windows, which used to reside in  http://download.zarafa.com/community/beta/6.40/6.40.13beta2-30778/windows/ You can also move your existing Outlook content (mails, contacts, calendars, notes) to Zarafa with the help of the migration tool. The only issues I discovered were, that from a German Outlook the calendar entries were imported to a folder called "Kalender" instead of "Calendar". Same for the contacts here. By using drag&drop you can pretty easily move the entries to the right folder.

To allow connection from the migration tool and Outlook, you have to change in the file /usr/share/ebox/stubs/zarafa/server.cfg.mas the line

server_bind = <% $server_bind %>

to

server_bind = 0.0.0.0

Save the file and install the Zarafa-licensed service by

sudo apt-get install zarafa-licensed

to enable access with Outlook and the migration tool. Afterwards do a

sudo /etc/init.d/ebox zarafa restart

and optionally a

sudo /etc/init.d/zarafa-licensed start

In the "Firewall" menue, you have to open up the port for Zarafa access, the standard port is 236, which we will change later on. Create a new service "Zarafa" under the menue "Services" and edit it. Enter these values: Protocol: TCP/UDP Protocol Source port: ANY Destionation port: 236

and save them. Now head over to the "Firewall" + "Packet filter" menue and under "Filtering rules from external networks to Zentyal" choose "Add new" and enter these values: Decision: Accept Source: ANY (or pre-define an object to grant access only to limited persons) Service: Zarafa

Save the changes and ebox will restart the firewall module. Now you should be able to connect to Zarafa (you can check this by using nmap to discover open ports). If you get the message "Cannot contact license server" in the migration tool or Outlook, you have to restart thezarafa-licensed service!

The migration is covered in the Zarafa docs in  http://www.zarafa.com/wiki/index.php/Zarafa_pst_migration,the only problem I discovered was the difference with an german Outlook and an english Zarafa profile. The contacts were imported to "Kontakte" so I had to manually drag&drop them to the "Contacts" folder. I haven't had too much appointments so I haven't taken care of the calendar yet - probably same problem here, too.

When the migration has worked you are all set to connect with Outlook to Zarafa - just create a new "Zarafa 6" account in Outlook (make sure it's the topmost account in the list if you have other accounts there - otherwise you won't see the content of your folders!!).

Outlook sync is finished with that.

Thunderbird + Lightning access

Coming to Thunderbird, I'll start with the calendar, that was the easiest way for me. I went straight with SSL, so just change in /usr/share/ebox/stubs/zarafa/ical.cfg.mas the port to 8444 (or whatever unused port number you like) insert this port under "Services" in the "Zarafa" entry we created above, save the changes and restart Zarafa+zarafa-ical if you changes the port number.

Install the Lightning extention with the help of your favourite package manager and open the calendar part in Thunderbird. Create a new network calendar, use CalDav as protocol and enter this link:  https://<your_ip_here>:<your_ical_ssl_port_here>/caldav/<your_username_here>/

In my case it's:  https://192.168.10.88:8444/caldav/bbking/

If everything went well, you shouldn't see the error symbol in the left frame in Lightning and optionally you should be able to enter a new appointment in the calendar, which is supposed to show up in Outlook and the Webaccess GUI of Zarafa under  http://<your_ip_here>/webaccess . Lately I experienced high IO loads (600-900k/s) when a Lightning client connected. MySQL was causing the high IO-Load - no solution on this issue yet.

Turning over to IMAP/IMAPS access: As we allowed IMAP+IMAPS services from Zarafa, it is possible to connect to Zarafa with Thunderbird. At first I had some trouble, because I changed the port number of the Zarafa-server and the Gateway could not connect. When I entered my username/password combo I kept getting "Login to server 192.168.10.88 failed" and can't log in. So pay attention to the line

server_socket =  http://localhost:236/zarafa

and change the port number accordingly.

Sending mails with Thunderbird:
Configure Thunderbird as follows:

Pay attention that for the IMAP account the username is only the username without the domain, while the smtp setup requires the username with the domain!!!

Z-Push

Setting up z-push access with Android and iPhone4 was pretty straight forward, and it seems to be working. Enter the username, password and only the hostname for the exchange server (NOT  http://hostname/Microsoft-Server-ActiveSync !!)

Here is a step-by-step screenshot-diashow for android 2.3 on a Samsung ACE:

Z-Sync

I ordered a licence for Z-Sync, created a file called z-sync in /etc/apache2/sites-available/ with this content:

Alias /z-sync /usr/share/z-sync

<Directory /usr/share/z-sync/>

DirectoryIndex index.php
Options -Indexes +FollowSymLinks
AllowOverride Options

Order allow,deny
Allow from all

</Directory>

Then copied the files from the .zip archieve to /usr/share/z-sync Did a

ln -s /etc/apache2/sites-available/z-sync /etc/apache2/sites-enabled/z-sync
/etc/init.d/ebox apache restart

and installed the .xpi file in Thunderbird. Unfortunatelly, after configuring the add-on, it did not work and exited with an error alert: "Server not found at: " So far, the reaction on the z-sync dev side was, that I should double check the install-howto - just what I did, before contacting them. Keep you posted on this.

CardDAV Support

OK, first of all, this gives you only read-only support at the moment, but it's more than nothing.

You'll need the SoGo AddOn for Thunderbird, download and install it from here:  http://www.sogo.nu/fr/downloads/frontends.html . Pay attention which version you need! I'm still using Thunderbird 3.1, so please let me know if this is accurate for newer versions as well[[BR]] You'll need the LevelBossMike Zarafa Plugin from  https://community.zarafa.com/pg/plugins/project/397/developer/rvjr/contact-access-via-webdav-and-carddav[[BR]] Additional info can be found here:  http://www.zarafa.com/wiki/index.php/CardDAV_Interface and I am quoting from that page parts of this howto:

sudo apt-get install php-pear

since the next two commands from the wiki give me an error, I use the next two commands below:

sudo pear install channel://pear.php.net/File_IMC-0.4.3
sudo pear install channel://pear.php.net/HTTP_WebDAV_Server-1.0.0RC7

Change to your download locations with LevelBossMike?,

unzip LevelbossMike-Zarafa_Carddav-!a140752.zip
cd LevelbossMike-Zarafa_Carddav-!a140752
sudo cp zarafa_carddav.php /usr/share/zarafa-webaccess/community_carddav.php
sudo vi /etc/apache2/sites-available/zarafa-webaccess

and add this line to the config:

Alias /carddav /usr/share/zarafa-webaccess/community_carddav.php

afterwards reload the config:

sudo /etc/init.d/apache2 reload

Now, check your contacts under (login with your Zarafa-users' credentials)

 http://z1.snakeoil.com/carddav/

When I opened the page all Umlauts and accented characters where messed up and I started debugging. I pretty soon had the web listing right, but the contacts in Thunderbird where still showing strange letters, so I went on with debugging.
Analysing the code showed me, that the plugin always converts to UTF-8 and doesn't check the string for the encoding format and converts it to UTF-8 anyway.

So I made a patch for this and it works for me in Thunderbird. You can skip the patch and try getting the contancts in Thunderbird first to see if they are messed up or not.

cd LevelbossMike-Zarafa_Carddav-!a140752/
wget -O utf8.patch  http://pastebin.com/raw.php?i=Q2J7tDwt
patch -u zarafa_carddav.php utf8.patch
sudo cp zarafa_carddav.php /usr/share/zarafa-webaccess/community_carddav.php

Installing officially signed SSL-certificates

I went to  http://www.startssl.com and got my own, officially signed certificates for my Zentyal-Box. Here is a great howto ( http://forum.zentyal.org/index.php/topic,616.msg2340.html#msg2340), regarding the installation of the signed certificates.

I will use Javier's howto here and append my remarks to it:

At first, you have to understand, that there are 2 different Apache instances running. One is doing the normal webpages, the other one is serving the web admin pages. These instances have 2 different config files.

Securing webpages (Zarafa's webaccess, Roundcube, etc.):
1) put the certificate in the file /etc/apache2/ssl/ssl.cert
2) put the certficate key file in the file /etc/apache2/ssl/ssl.key
3) create the pem file concatening the two previous files, like this:

cat /etc/apache2/ssl/ssl.cert /etc/apache2/ssl/ssl.key > /etc/apache2/ssl/ssl.pem
chmod 0400 /var/lib/ebox/conf/ssl.pem/ebox.pem

here I went over to the /usr/share/<ebox/zentyal>/stubs/webserver and added the following line to default-ssl.mas :

SSLCertificateChainFile "/etc/apache2/ssl/sub.class1.server.ca.pem"

the sub.class1.server.ca.pem is issued by StartSSL, this will tell the browser who is the CA.

Do a

/etc/init.d/zentyal webserver restart

and your official certificates should be working.

Securing the admin interface:
1) put the certificate in the file /var/lib/ebox|zentyal/conf/ssl/ssl.cert
2) put the certficate key file in the file /var/lib/ebox|zentyal/conf/ssl/ssl.key
3) create the pem file concatening the two previous files, like this:

cat /var/lib/ebox|zentyal/conf/ssl/ssl.cert /var/lib/ebox|zentyal/conf/ssl/ssl.key > /var/lib/ebox|zentyal/conf/ssl/ssl.pem
chmod 0400 /var/lib/ebox/conf/ssl.pem/ebox.pem

TODO: verify inserting official CA

/etc/init.d/zentyal apache restart

will restart you admin interface, which will have the official certificates as well.

Securing IMAP with an official certificate:

After my initial tests still did not satisfy Thunderbird, I've found a great tutorial on  http://www.howtoforge.com/securing-your-ispconfig-3-installation-with-a-free-class1-ssl-certificate-from-startssl

1) if you have a StarSSL certificate, get their CA files and give them speaking names:

cd /home/youruser/
wget https://www.startssl.com/certs/ca.pem
wget https://www.startssl.com/certs/sub.class1.server.ca.pem
mv ca.pem startssl.ca.crt
mv sub.class1.server.ca.pem startssl.sub.class1.server.ca.crt

2) create the chain file

cat startssl.sub.class1.server.ca.crt startssl.ca.crt > startssl.chain.class1.server.crt

At this point you have different options. Either you go with the official supported way and use the hooks for Zentyal, see  http://trac.zentyal.org/wiki/Documentation/Community/HowTo/CustomizeConfigFiles

or, if you want to do a quick hack, you can do it this way (keep in mind, after an update, these changes might be gone!!!):

cd /usr/share/zentyal|ebox/stubs/mail
cp main.cf.mas main.cf.mas<date>
vi main.cf.mas

look for the lines with the entries

my $certFile = '/etc/postfix/sasl/postfix.pem';
my $keyFile = '/etc/postfix/sasl/postfix.pem';

and change them to:

my $certFile = '/etc/postfix/sasl/smtpd.crt';
my $keyFile = '/etc/postfix/sasl/smtpd.key';
my $CAfile = '/etc/postfix/sasl/startssl.chain.class1.server.crt';

scroll down and look for the TLS/SSL stuff and add this line:

smtpd_tls_CAfile = <% $CAfile %>

save the file.

Depending where you keep your official certificate and the key, please change the locations accordingly.

cd /etc/postfix/sasl
ln -s /home/youruser/www.snakeoil.com.crt smtpd.cert
ln -s /home/youruser/www.snakeoil.com.key smtpd.key
ln -s /home/youruser/startssl.chain.class1.server.crt startssl.chain.class1.server.crt

3) restart the mail system with:

/etc/init.d/zentyal mail restart

TODO: check whether the certificates are in place after a reboot. Explain the use of hooks.