Zimbra FreeBSD Patch Release Notes
Doug White
Introduction
============
This tarball contains patches and files to adapt the Zimbra Collaborative Suite public source to compile packages and operate on FreeBSD. At this time, these patches are a work in progress and may not support all functionality present on other Zimbra platforms.
These instructions will walk through checking out the source tree, applying the patch, performing the package build, and installing the binary packages.
Installation Instructions
=========================
*WARNING*WARNING*WARNING* It is **CRITICAL** that these instructions be followed _to_the_letter_, or else the patch and build process WILL fail. Failure to follow these instructions EXACTLY will result in NO response to support inquries.
A. Recognize Installation Assumptions and Caveats
=================================================
These instructions assume that:
1. Zimbra is being installed to a freshly installed system dedicated to the purpose of running ZCS. It is NOT RECOMMENDED to run Zimbra on a server functioning in any other capacity as it makes invasive changes to the system configuration and can easily conflict with other packages. In addition, upgrades and deinstallation are not well supported and as such may leave a system in an inconsistent state when uninstalled or upgraded.
2. Zimbra will be built and installed on separate systems. The Zimbra build process places files in directories that will conflict with the binary package installation. The build process itself is minimally invasive, however, and can (generally) be run on an installed machine performing other functions, although it is good practice to avoid disturbing critical infrastructure.
3. It is OK to spam any Perl CPAN configuration in ~/.cpan/CPAN. One part of the build uses CPAN to
download dependant Perl modules. If your MyConfig.pm is precious then back it up before running the ThirdParty build.
4. The build and target systems are i386. This build has not been developed or tested for other platforms. The architecture is hardcoded in various places in the build so it will certainly not work without some hackery.
5. The user's shell is /bin/sh. Substitute csh environment commands as appropriate.
B. Install Installation Prerequisites
=====================================
1. On the build system and using the FreeBSD ports/packaging system, install the following packages and their dependencies:
Latest diablo-jdk-1.5.0 from http://www.freebsdfoundation.org/downloads/java.shtml
(Note that the JDK requires x11/xorg-libraries and java/javavmwrapper as dependencies.)
shells/bash2
lang/perl5.8
devel/apache-ant
devel/gmake
devel/gnu-automake
devel/libtool
devel/pcre
devel/popt
devel/subversion
graphics/gd
ftp/curl
textproc/libxml2
Install security/amavisd-new from a port to pick up the dependencies. pkg_add -r does not
download all of the dependencies.
2. Create /opt/zimbra to house build products. This directory needs a large amount of space, so
create /opt on another partition and symlink if necessary.
# mkdir /opt/zimbra
or
# mkdir /usr/opt && ln -s /usr/opt /opt && mkdir /opt/zimbra
3. Execute the following commands as root:
# ln -s /usr/local/bin/bash /bin/bash
# ln -s /usr/local/diablo-jdk* /usr/local/java
# pkg_delete amavisd-new\* p5-Net-Server\* p5-Mail-SpamAssassin\*
# cp /usr/local/share/aclocal/* /usr/local/gnu-autotools/share/aclocal-1.9
# pw useradd zimbra -s /usr/local/bin/bash -c "Zimbra User" -d /opt/zimbra
# pw groupadd postdrop
# pw useradd postfix -G postdrop,mail -c "Postfix User" -d /opt/zimbra/postfix
C. Checkout Zimbra Subversion Sources
=====================================
1. Execute the following command. It is **CRITICAL** to request revision 261 as the patch is derived against that revision ONLY -- it will NOT apply to other revisions:
$ svn co -r 261 https://svn.sourceforge.net/svnroot/zimbra/trunk/branches/EDISON zimbra
D. Apply Patch
==============
1. Extract the patch tarball over the tree you just checked out:
$ cd zimbra
$ tar -xzf /path/to/zimbra.freebsd.YYYYMMDD.tar.gz
2. Apply the deltas:
$ patch < zimbra.patch.freebsd.YYYYMMDD
E. Fetch & Construct ThirdParty Source Tarballs
===============================================
1. Locate and download the following source packages. Place the downloaded files in the ThirdParty directories noted.
Source Package Destination Directory
============== =====================
amavisd-new-2.3.3.tar.gz amavisd
httpd-2.0.54.tar.gz apache-httpd
aspell-0.60.3.tar.gz aspell
aspell6-en-6.0-0.tar.bz2 aspell
clamav-0.88.5.tar.gz clamav
dspam-3.6.2.tar.gz dspam
apache-tomcat-5.5.15-src.tar.gz jakarta-tomcat
mrtg-2.10.15.tar.gz mrtg
mysql-4.1.20.tar.gz mysql/src
openldap-2.3.21.tgz openldap
perdition-1.17.tar.gz perdition
vanessa_adt-0.0.7.tar.gz perdition
vanessa_logger-0.0.7.tar.gz perdition
vanessa_socket-0.0.7.tar.gz perdition
swatch-3.1.1.tar.gz Perl
php-5.0.5.tar.gz php
rrdtool-1.0.49.tar.gz rrdtool
db-4.2.52.tar.gz sleepycat (see #2)
net-snmp-5.1.2.tar.gz snmp
2. Patch and rebuild the BerkeleyDB tarball (the semi-lazy way):
# cd /usr/ports/databases/db42
# make fetch
# cd /path/to/zimbra/ThirdParty/sleepycat
# mkdir t; cd t
# tar xzf /usr/ports/distfiles/bdb/db-4.2.52.tar.gz
# cd db-4.2.52
# patch < /usr/ports/distfiles/bdb/patch.4.2.52.1
# patch < /usr/ports/distfiles/bdb/patch.4.2.52.2
# patch < /usr/ports/distfiles/bdb/patch.4.2.52.3
# patch < /usr/ports/distfiles/bdb/patch.4.2.52.4
# cd ..
# mv db-4.2.52 db-4.2.52.4
# tar czf ../db-4.2.52.4.tar.gz db-4.2.52.4
# cd ..
# rm -rf t
F. Build ThirdParty Dependencies
================================
1. Execute the build script. You will need to do this as root to allow the builds to set file ownerships:
# cd ThirdParty
# sh build-freebsd-thirdparty.sh
G. Build Zimbra
===============
1. Execute the actual Zimbra build:
# cd /path/to/zimbra/ZimbraBuild
# gmake allclean && gmake
When this completes, packages will be ready in /path/to/zimbra/ZimbraBuild/i386.
2. Copy /path/to/zimbra/ZimbraBuild/i386/zcs.tgz to the install system.
H. Install Dependencies
=======================
1. On the install system, install the following dependencies using the FreeBSD package system:
lang/perl5.8
shells/bash2
security/sudo
mail/fetchmail
textproc/libxml2
ftp/curl
devel/pcre
Install security/amavisd-new from a port to pick up the dependencies. pkg_add -r does not
download all of the dependencies.
Latest diablo-jdk-1.5.0 from http://www.freebsdfoundation.org/downloads/java.shtml
Execute the following commands:
# pkg_delete amavisd-new\* p5-Net-Server\* p5-Mail-SpamAssassin\*
# ln -s /usr/local/bin/bash /bin/bash
I. Install Zimbra
=================
1. Set the JAVA_HOME environment variable to point to the diablo-jdk installation.
For sh-deriviative users:
# JAVA_HOME=/usr/local/diablo-jdk1.5.0
# export JAVA_HOME
or for csh-deriviative users:
# setenv JAVA_HOME /usr/local/diablo-jdk1.5.0
2. Create /opt on a filesystem with large amounts of space available. Use a symlink if necessary.
# mkdir /opt
or
# mkdir /usr/opt && ln -s /usr/opt /opt
3. Execute the following command:
# ln -s /usr/local/bin/bash /bin/bash
4. Extract the ZCS package tarball:
# tar xzf zcs.tgz
# cd zcs
5. Execute the install script:
# bash install.sh
6. Follow through the installation, opting to install all packages, and set the admin password when the configuration dialog appears. Note what the admin email address gets created as -- this is the admin user's login account.
J. Perform Zimbra Configuration
===============================
1. Install syslog entries to enable monitoring. Add these lines to /etc/syslog.conf above the ! lines near the bottom:
local0.* /var/log/zimbra.log
Touch /var/log/zimbra.log and killall -HUP syslogd.
2. If all went well, the admin interface will be accessible at:
https://machinename:7071/zimbraAdmin
Login with the full admin email address from the install tool (admin@machinename.example.com) and the password configured in that step. At this point you can create users and otherwise manage the system according to the Zimbra OS Admin Guide.
The user's web client is accessible at:
http://machinename/zimbra
Uninstallation
==============
While uninstallation is not well automated, the following steps seem to work well for cleaning out the majority of the Zimbra bits. This is useful if you really screw up the installation and just want to start over.
1. su to to the zimbra user and stop processes:
# su - zimbra
$ zmcontrol stop
2. Ensure all zimbra processes are stopped:
# ps auxwww | grep zimbra
# ps axwww | grep zimbra
3. Delete the FreeBSD packages:
# pkg_delete zimbra\*
4. Delete the remnants of the /opt/zimbra directory:
# rm -rf /opt/zimbra
5. Delete the zimbra user's crontab:
# crontab -r -u zimbra
6. Remove sudoers entries for zimbra:
# visudo
7. Remove the zimbra user (and postfix users if postfix is not installed on your system):
# pw userdel zimbra
# pw userdel postfix
# pw groupdel postdrop
7. Remove /etc/syslog.conf entry for /var/log/zimbra.log and killall -HUP syslogd.
Build System Cleanup
====================
Once the package build is installed and working, the /opt/zimbra directory and the auxiliary users are no longer needed and can be erased.
Running ZCS In A Jail
=====================
The system silently changes references to localhost and 127.0.0.1 into the jail's IP address. This breaks the privilege table setup in the MySQL databases and potentially reveals internal interfaces to the outside world. After the ZCS install completes, your databases will be open to the world with an unset root password! You will need to make the following changes:
* Duplicate the grants given to 'zimbra'@'%' to 'zimbra'@'jail-hostname.example.com'
* Copy the password on 'root'@'localhost' to 'root'@'jail-hostname.example.com'
- To make changes to the MySQL permission setup:
1. Connect to the storage database using the open root account:
$ /opt/zimbra/mysql/bin/mysql -h jail-hostname -u root -P 7306
2. Extract the current grants:
mysql> show grants for 'zimbra'@'%';
3. Replace 'localhost' with the jail hostname and reissue the commands:
mysql> show grants for 'zimbra'@'%';
+----------------------------------------------------------------------------------------------------------------------------------+
| Grants for zimbra@% |
+----------------------------------------------------------------------------------------------------------------------------------+
| GRANT ALL PRIVILEGES ON *.* TO 'zimbra'@'%' IDENTIFIED BY PASSWORD '*CED23DD2B2B22827FDCB1EA1733AB5302C3EE9D6' WITH GRANT OPTION |
| GRANT ALL PRIVILEGES ON `zimbra`.* TO 'zimbra'@'%' |
+----------------------------------------------------------------------------------------------------------------------------------+
mysql> GRANT ALL PRIVILEGES ON *.* TO 'zimbra'@'jail-hostname.example.com' IDENTIFIED BY PASSWORD '*CED23DD2B2B22827FDCB1EA1733AB5302C3EE9D6' WITH GRANT OPTION;
mysql> GRANT ALL PRIVILEGES ON `zimbra`.* TO 'zimbra'@'jail-hostname.example.com';
Query OK, 0 rows affected (0.00 sec)
mysql> flush privileges;
Query OK, 0 rows affected (0.00 sec)
5. Copy the root password to the network-accessible account:
mysql> show grants for 'root'@'localhost'\G
*************************** 1. row ***************************
Grants for root@localhost: GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' IDENTIFIED BY PASSWORD '*04DA3180C61ECF871F89D305E6D354A9F846507D' WITH GRANT OPTION
1 row in set (0.00 sec)
mysql> GRANT ALL PRIVILEGES ON *.* TO 'root'@'jail-hostname.example.com' IDENTIFIED BY PASSWORD '*04DA3180C61ECF871F89D305E6D354A9F846507D' WITH GRANT OPTION;
Query OK, 0 rows affected (0.01 sec)
6. Do the same for the logger database:
$ /opt/zimbra/mysql/bin/mysql -h jail-hostname -u root -P 7307
mysql> show grants for 'zimbra'@'%'\G
*************************** 1. row ***************************
Grants for zimbra@%: GRANT USAGE ON *.* TO 'zimbra'@'%' IDENTIFIED BY PASSWORD '*B1EDFEDB5DFC7291A262ED4BFAC45D616222EF34'
*************************** 2. row ***************************
Grants for zimbra@%: GRANT ALL PRIVILEGES ON `zimbra_logger`.* TO 'zimbra'@'%'
2 rows in set (0.01 sec)
mysql> GRANT USAGE ON *.* TO 'zimbra'@'jail-hostname.example.com' IDENTIFIED BY PASSWORD '*B1EDFEDB5DFC7291A262ED4BFAC45D616222EF34';
Query OK, 0 rows affected (0.00 sec)
mysql> GRANT ALL PRIVILEGES ON `zimbra_logger`.* TO 'zimbra'@'jail-hostname.example.com';
Query OK, 0 rows affected (0.00 sec)
mysql> show grants for 'root'@'localhost'\G
*************************** 1. row ***************************
Grants for root@localhost: GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' IDENTIFIED BY PASSWORD '*04DA3180C61ECF871F89D305E6D354A9F846507D' WITH GRANT OPTION
1 row in set (0.00 sec)
mysql> GRANT ALL PRIVILEGES ON *.* TO 'root'@'jail-hostname.example.com' IDENTIFIED BY PASSWORD '*04DA3180C61ECF871F89D305E6D354A9F846507D' WITH GRANT OPTION;
Query OK, 0 rows affected (0.01 sec)
- After the grant changes are complete you should be unable to re-connect using the prior mysql
commands.
- You may want to set up a packet filter on the jail IP to restrict access from the outside world to ports used by various internal services, such as dspam.
Also be sure to stop and disable any private sendmail instances in the jail; they will conflict with ZCS's postfix instance.
Patch Release Notes
===================
Known Issues
============
- zmsyslogsetup has been disabled as the default FreeBSD syslogd.conf is not amendable to appending lines. Rather than rewriting the script to handle this the script was disabled and modifications were put in the install instructions. This needs to be fixed.
- The crontab generated for the zimbra user assumes modern cron variable-setting extensions that are not true for Solaris. As a result the method for setting up the environment, specifically PATH, for cronjobs needs to be investigated further.
- MYSQL_VERSION is hardcoded in several places, instead of pulling it from the platform definitions file. This is a general problem in ThirdParty that needs to be addressed.
- The path to the file(1) utility that amavisd-new uses is hard-coded to /usr/bin/file. This may not be true for all platforms. Depending on PATH being set right is less than optimal.
- IMAP/POP proxying via perdition is completely untested in this patch. It builds and installs but has not actually been enabled or executed. Perdidion has some funky library build dependencies that may not be working properly at runtime.