Jul 13

Today I’m providing information on my efforts to get a running installation of Zimbra Collaborative Suite using its Open Source Edition. It’s being installed onto a server running an up-to-date 2008.0 installation of Gentoo Linux. It’s a vServer and I tried to install from source first. But then I found a very useful tutorial putting a binary distribution of Zimbra CS into a Debian-like context running in chroot.

  1. the original tutorial on installing ZCS under Gentoo
  2. more on Zimbra
  3. more on Gentoo
  4. more on Debian

Prerequisites

Think about your sort of installation

Zimbra is being installed into a chroot environment providing Debian-like context with increased security for your existing Gentoo installation. This is still very different from having some kind of virtual machine with a natively installed Debian distribution in it. The chroot environment is providing library files, external tools and configuration files as expected by a binary designed to work on a Debian computer. Aside from providing special separate binaries, files and folders it’s sharing resources of your Gentoo like NICs, used ports on them, basic network configuration such as hostname etc. Most of it is managed by the fully shared kernel.

This, for example, leads to Zimbra choosing your Gentoo hostname by default even if you decide to have a second IP with different name registered in DNS. You could try to fix some of the files used by name resolvers to hide your Gentoo host’s original name. But most things require to be fixed manually.

Another related side effect is Zimbra seeing all your (virtual) NICs used to bind all associated IPs. Due to current network routing Zimbra might be using either of them for sending out data. If it’s sending data from one IP to the other it requires both to be known and trusted by Zimbra implying additional post-install configuration. Even though one of them is used to bind servers, only, client may be bound to each of them.

My second IP address

While that tutorial instructs how to install on a server having single IP I decided to order a second one for my server. Doing so I considered myself to be able to use native HTTP/HTTPS ports for web client keeping things convenient for customers less familiar with URLs, ports etc.

Next I registered separate hostname for that new IP. I included a proper MX record as Zimbra is testing this on installation prior to accepting new host/domain name without any hassle. Finally I prepared to have a proper reverse DNS record. I don’t know if this is required by Zimbra, but it’s definitely required on using integrated MTA for sending mails to remote MTAs. The latter ones are used to reject your outgoing mails on missing valid reverse DNS record.

For the sake of simplicity I’ll call my 2. IP and its related domain name

a.b.c.d

and

my.zimbra.de

whenever required below.

Limit Apache and Postfix in Gentoo

Of course, I had to limit existing Apache and Postfix to bind on first IP or localhost, only. In /etc/apache2/vhosts.d/00_default_vhost.conf I replaced existing Listen directive by

Listen a.b.c.d:80

The same is required in /etc/apache2/vhosts.d/00_default_ssl_vhost.conf replacing existing directive by

Listen a.b.c.d:443

Next I bound SMTP daemon of Postfix – used for outgoing mails of Apache-based websites, only – to localhost, making it somewhat safer at the same time. In /etc/postfix/master.cf there is a line starting with smtp (without any preceeding #!) and I replaced that occurrence of smtp by

127.0.0.1:smtp

After restarting Apache and Postfix everything has been prepared to install Zimbra CS in a Debian context next.

Installation

Creating Debian like environment

The procedure described in tutorial linked above works nearly straightforward. I created a Debian-like chroot environment using debootstrap. Due to lacking proper binary distribution file of Zimbra you shouldn’t decide to install Debian Lenny instead of Debian Etch as done in tutorial.

As a note to that tutorial apt-setup isn’t available with current releases of Debian Etch and so you either keep things with pre-selected apt-get repository or switch to your preferred mirror manually. As a Germany-based provider I decided to use German mirror and thus had to insert “de.” in original address found in /zimbra/etc/apt/sources.list. A list of mirrors is available on Debian site.

If you prefer convenient file management you might want to install midnight commander inside chroot, too.

# apt-get install mc

Current releases include syntax highlighting making file editing much easier and supports detecting XML fragments commented-out below.

Updating host information

As instructed in tutorial you need to edit /etc/hosts and /etc/hostname while in chroot. While the latter might have little impact on hostname the former is quite important for resolving names properly. In addition it serves to redirect requests of installed Zimbra software for your Gentoo’s hostname to the 2nd IP making it equivalent to the hostame actually associated with that. Make /etc/hosts reading similar to this:

127.0.0.1 localhost
a.b.c.d my.zimbra.de my there.gentoo.de there

It’s common to include a host’s FQDN as well as its hostname without domain. That’s why there are four names after IP in second line.

Replacing syslog

Instead of using sysklogd I decided to use syslog-ng. It’s not binding to any UDP port by default. I currently don’t know whether or not it’s interfering with my Gentoo syslog facility (running metalog there). syslog-ng is providing socket in /dev/log maybe replacing an existing socket of metalog.

Running Zimbra CS installer

I’ve downloaded Zimbra CS Open Source version 5.0.18, untarred it and started installer. During installation I decided to install any available package (including proxy). Next I changed domain on demand providing my prepared domain my.zimbra.de. Installer reads MX records then, checking if there is at least one pointing to current host prior to proceeding with installation.

After detecting port conflicts on 80, 443 and 25 used by Apache/Postfix on my Gentoo server (I was basically ignoring here) installer presented me a set of options available for tweaking prior to actual installation:

  1. I changed hostname in Common Configuration to my.zimbra.de. By default Zimbra is using my Gentoo server’s name and thus would probably tend to associate itself with my first IP.
  2. In Zimbra Store I provided the mandatory password for admin user and I switch protocol mode from http to mixed. I didn’t change ports of Mail and MailSSL, but kept them on 80 and 443.
  3. Ensure configuration on Remote Management Console using your 2nd IP address or related hostname.
  4. Finally I disabled automatic start of server after successful installation prior to applying configuration.

Fixing Zimbra configuration

Next I had to fix things so Zimbra is binding to 2nd IP, only. This isn’t required on every service, actually. I tried to fix configuration just to circumvent port conflicts on ports 22, 80, 443 and 25 at least. This procedure is inspired by several posts found in Zimbra forum, e.g. this one. Nevertheless none of them succeeded out of the box.

The following instructions are assuming you to be in chroot environment.

Binding OpenSSH

SSH is used to manage installation using web-based Zimbra Administration Console. You need to bind the OpenSSH to your second IP as well. Open file /etc/ssh/sshd_config and right after the early line containing Port directive insert a line reading

Listen a.b.c.d

Binding Postfix

Zimbra’s Postfix is required to bind to 2nd IP, only. Otherwise it isn’t started causing errors on trying to send or receive any mail. In addition log files in chroot are flooded with messages on missing queue.
Edit file /opt/zimbra/postfix/conf/master.cf.in and look for the first line starting with  smtp, again without any preceeding #. Replace that occurrence of smtp by

a.b.c.d:smtp

Below that there is another line starting with 465 you should modify accordingly, thus reading then

a.b.c.d:465

This second service on port 465 is obviously not conflicting with Gentoo’s installation of postfix. Nevertheless it probably won’t harm your setup to explicitly bind it to 2nd IP, as well.

Selecting trusted networks

All your NICs should be registered as origin of sending trustworthy mail data. Doing so in Postfix configuration would be dropped on restarting Zimbra. And so it’s done using tool zmprov available to user zimbra while in chroot. Here the IP e.f.g.h is to be replaced by your 1st IP.

# su - zimbra
$ zmprov ms my.zimbra.de zimbraMtaMyNetworks "127.0.0.0/8 a.b.c.d/32 e.f.g.h/32"

Note! According to your server’s actual setup you might need to have different netmasks to be indicated here on the addresses #2 and #3.

Binding Jetty/mailbox

Ports 80 and 443 are managed by Jetty and thus require modifications of three files found in folder /opt/zimbra/jetty/etc.

/opt/zimbra/jetty/etc/jetty.xml.in

Look for block of lines following XML comment

<!-- HTTPBEGIN -->

There is a line reading (ellipsis isn’t found there!)

<Set name="confidentialPort">...</Set>

Insert another line right after that one reading

<Set name="Host">a.b.c.d</Set>

Don’t forget to use your actual IP, here. Next I had to repeat this for the https connector. It’s found right after that block modified before, just look for

<!-- HTTPSBEGIN -->

After that line there is a block of lines similar to the one found before. I decided to include exactly the same line as above after a line reading

<Set name="Port">...</Set>

Note! This second block might be commented out, obviously due to configuration still set to http mode instead of mixed mode. If this is the case you probably need to switch mode manually prior to inserting that line.

# su - zimbra
# zmtlsctl mixed

This step is missing in forum thread linked above. Omitting it lead to zimbra starting without Jetty making quite little sense, only.

/opt/zimbra/jetty/etc/zimbra.web.xml.in
/opt/zimbra/jetty/etc/zimbraAdmin.web.xml.in

These files require equivalent modification and thus are handled together here. Edit them to uncomment the block reading

<context-param>
  <param-name>zimbra.soap.url</param-name>
  <param-value>http://localhost:7070/service/soap</param-value>
</context-param>

After that replace the URL to use your 2nd IP, so the whole block is reading afterwards

<context-param>
  <param-name>zimbra.soap.url</param-name>
  <param-value>http://a.b.c.d/service/soap</param-value>
</context-param>

Starting up Zimbra

Now it’s time to start your zimbra installation. Don’t miss to start ssh in chroot. Here starting zimbra took a while to succeed. After that try tools like

# netstat -tulpen

to check wether all services are running and bound to IPs properly. The rightmost column in list should include a lot of occurrences reading “java” on success. If those are missing, something’s wrong with your configuration of Jetty as fixed above.

Finally it’s time to open Zimbra’s administration console and web client to test its operation. Administration console is available at

http://my.zimbra.de:7070

The web client is available at

http://my.zimbra.de

and this URL is finally reading fine for end-users little or not familiar with IT.

Having proper start-stop script

Using the start-stop script provided in tutorial above it sometimes failed to cleanly stop all processes of zimbra without providing any useful output. Try the following set of commands while in chroot if you’re interested in restarting your Zimbra services manually:

# su - zimbra
$ zmcontrol stop
$ zmcontrol start

Conclusion

The intended constellation of having Debian binary running in a chroot under Gentoo fascinated me. It neither requires building Zimbra from source nor do I have to order another server.

However it includes some hassle. I maybe missed to include some essential information above. Some expected features probabyl don’t work properly even after successfully and carefully following my instructions. I’ll be testing my installation now looking for some problems requiring extra fix …

One Response to “Installing Zimbra CS OpenSource on Gentoo”

  1. Thomas Urban says:

    The Zimbra service is running for a while now and it’s in use for evaluation. Though I haven’t had any crash or similar within the last few months I’d like to promote another opportunity here one might be trying and I’m somewhat interested in as well: Instead of putting Zimbra in a chroot it might be running in context of User Mode Linux providing even better process and network socket separation over chroot. Gentoo is basically including support for UML and though it might be hosting a Debian installation in UML for instantly installing Zimbra binary releases. I’ll give it a try one day …

preload preload preload