INSTALL.txt

Most of the official Zimbra docs still apply with this build, and the
administration scripts (zmcontrol and so on) work as described in:

        http://www.zimbra.com/community/documentation.html

Whenever the Zimbra guide refers to /opt/zimbra, we will use the 'zbuild/home' directory
that is created by running buildout.

The following scripts do not work because it is not possible or does not make sense to run them as non-root:

 - libexec/zmfixperms
 - libexec/zmsyslogsetup

The following optional packages will be created by the build, but cannot be
installed because they have not been completely modified and tested for buildout:

 - zimbra-apache
 - zimbra-logger
 - zimbra-memcached
 - zimbra-proxy
 - zimbra-snmp
 - zimbra-spell





=====================
How to install Zimbra
=====================

 *) Install Ubuntu 12.04.x 64 bit server with at least 2GB RAM / 15 GB HD

    For instance, you can download it from
    http://releases.ubuntu.com/precise/ubuntu-12.04.2-server-amd64.iso
    and just 'dd' the image to an USB key, then boot with it.


 *) Install additional packages

        # for slapos components
        sudo apt-get install python gcc g++ make uml-utilities bridge-utils linux-headers-$(uname -r) patch wget \
                python-dev libxml2-dev libxslt-dev 

        # for zimbra third party components
        sudo apt-get install libcloog-ppl0 libncurses5-dev gcc-multilib

        # misc
        sudo apt-get install git libcap2-bin sysstat netcat


 *) The /etc/hosts file must be configured as required by Zimbra - something like

        127.0.0.1       localhost
        #127.0.1.1      myserver
        192.168.0.118   myserver.mydomain.com myserver

    Note that we commented/removed the line with 127.0.1.1. This file is actually checked by the zmsetup.pl script
    to retrieve the host and domain names.


 *) DNS must be set up according to Zimbra documentation (myhost.mydomain.com has both A and MX records)


 *) The global limits for 'number of open files' must be increased from the default of 1024.
    Many maintenance scripts call 'ulimit -n 32768' - therefore the following must be added
    to /etc/security/limits.conf

        ----- cut here --------------------------------
        *                hard    nofile          32768
        *                soft    nofile          32768
        ----- cut here --------------------------------

    After this change, reboot the system to make it effective.


 *) System logging must be configured in order to have server monitoring from the admin interface

    The following must be uncommented in /etc/rsyslog.conf:

        ----- cut here ----------------
        # provides UDP syslog reception
        $ModLoad imudp
        $UDPServerRun 514
        
        # provides TCP syslog reception
        $ModLoad imtcp
        $InputTCPServerRun 514
        ----- cut here ----------------


 *) Set up authbind

        $ wget http://git.erp5.org/gitweb/slapos.git/blob_plain/refs/heads/zimbra:/software/zimbra/authbind_2.1.1_amd64.deb
        $ sudo dpkg -i authbind_2.1.1_amd64.deb
        $ sudo touch /etc/authbind/byport/{80,110,143,443,\!993,\!995}
        $ sudo chown `id -u`.`id -g` /etc/authbind/byport/{80,110,143,443,\!993,\!995}
        $ sudo chmod 755 /etc/authbind/byport/{80,110,143,443,\!993,\!995}

    Note that `id -u` and `id -g` are the user and group that will run Zimbra.


 *) Create the directory to contain zimbra build and clone the slapos repository.

        $ mkdir zbuild; cd zbuild
        $ git clone http://git.erp5.org/repos/slapos.git -b zimbra slapos

    You can use a different name for the directory 'zbuild'.
    From this point, we will refer to it as '/home/user/zbuild'
    NB: the user that runs the build MUST be the same that will run Zimbra.


 *) Create buildout.cfg

        $ echo -e "[buildout]\nextends = slapos/software/zimbra/buildout.cfg\ndevelop = slapos\n" >buildout.cfg

    In case of repeated builds (i.e. when debugging) you can improve performance by using a local
    repository for zimbra:

        $ git clone http://git.erp5.org/repos/zimbra.git -b authbind zimbra
        $ echo -e "[zimbra-sources]\nrepository = /home/user/zbuild/zimbra\n" >>buildout.cfg


 *) Build SlapOS and Java components

    Bootstrap and run buildout a first time without arguments:

        $ wget https://raw.github.com/buildout/buildout/1/bootstrap/bootstrap.py
        $ python bootstrap.py
        $ ./bin/buildout

    After some time, you should read:

        BUILD SUCCESSFUL
        [...]
        mkdir -p /home/user/zbuild/parts/zimbra-sources/ThirdPartyBuilds/x86_64/java/junixsocket
        cd /home/user/zbuild/parts/zimbra-sources/ThirdPartyBuilds/x86_64/java/junixsocket
        tar --extract --bzip2 --file /home/user/zbuild/parts/junixsocket/junixsocket-1.3-bin.tar.bz2 --wildcards '*.so' --strip-components=2'
        Unused options for junixsocket-sources: 'update-command'.

    You might see instead:

        BUILD FAILED
        /home/user/zbuild/parts/junixsocket__compile__/junixsocket-1.3/build.xml:411: Test org.newsclub.net.unix.SoTimeoutTest failed

        Total time: 24 seconds
        junixsocket: Command failed with exit code 1: /home/user/zbuild/parts/ant/bin/ant 
        junixsocket: Compilation error. The package is left as is at /home/user/zbuild/parts/junixsocket__compile__/junixsocket-1.3 where you can inspect what went wrong
        While:
          Installing junixsocket.
        Error: System error

    This happens sometimes, and is an unpredictable timing issue.
    Running buildout again fixes the problem.


 *) Build Zimbra components

    This is provided as a separate step to allow building and deploying on different machines.

        $ source environment.sh
        $ ./bin/buildout install zimbra-build

    Some Java warnings are expected.

    Third party libraries build with the messages:

        *** Building in openssl SUCCEEDED.
        ...
        *** Building in zeromq SUCCEEDED.

    If any of them shows FAILED, check the dependencies, then read the section "Partial third-party build"

    When buildout has finished, you should find the following files:

        $ ls parts/zimbra-sources/ZimbraBuild/amd64/*deb
        zimbra-apache_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-core_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-ldap_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-logger_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-memcached_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-mta_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-proxy_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-snmp_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-spell_8.0.4.GA.5682.UBUNTU12.64_amd64.deb
        zimbra-store_8.0.4.GA.5682.UBUNTU12.64_amd64.deb

    You may backup the .deb files to be sure you don't lose them by mistake (i.e. if you run
    this buildout step again, they will be deleted).
    If you want to install zimbra on another or multiple servers, you can skip this step
    by reusing the .deb files - but only if the username and path of the build directory are the same.


 *) Run the deployment section to install the .deb files

        $ ./bin/buildout install zimbra-deploy-all

    The files will not be really installed by dpkg, but uncompressed under the 'zbuild/home' directory.
    If setcap is required at this point (for ldap and postfix) a root password might be asked.


 *) Configure zimbra

    Be sure to have sourced the environment variables for SlapOS components

        $ source /home/user/zbuild/environment.sh

    and the ones that refer to Zimbra components:

        $ source /home/user/zbuild/home/.bashrc

    Now run the actual configuration script.

        $ cd /home/user/zbuild/home/; ZIMBRA_INSTALLED_PKGS="zimbra-core zimbra-ldap zimbra-mta zimbra-store" ./libexec/zmsetup.pl

    The last two lines are printed after running "buildout install zimbra-deploy-all".


 *) Fill the required options in the configuration menu.

    Usually, only an admin password is required: menu 3 and then 4.
    Other mandatory options (as in case of zimbra-deploy-store) are be marked by an asterisk.

    Refer to the official Zimbra documentation for this part of the setup.
    Here you can also change things like IPv4/IPv6, etc.

    After typing (a)pply, many configuration files, certificates, and databases are created.
    A verbose log will show up on the screen.

    At the end of this process, the log is copied in home/log/zmsetup.*.txt
    and the zimbra services are run.


 *) Check that zimbra is running:

        $ cd /home/user/zimbra-target/home/bin
        $ ./zmcontrol status
        antispam                Running
        [...]
        zmconfigd               Running

 *) You should now be able to connect to https://myserver.mydomain.com
    and send/receive emails, and log in to the administration interface
    (drop-down menu, top right).


 *) Before running any of the maintenance commands in bin/ or libexec/,
    the following files must be sourced by the shell:

        $ source /home/user/zbuild/environment.sh
        $ source /home/user/zbuild/home/.bashrc


To install a multi-server system, use the deploy-zimbra-ldap, deploy-zimbra-mta
and deploy-zimbra-store parts. Only the "configuration menu" part is different
and should be completed as described by the official documentation.



=========================
Partial third-party build
=========================

If you need to build a single component in ThirdParty, maybe because it has failed
and want to investigate the reason, remember to load the environment.sh script first,
then run the proper makefile.

        $ source environment.sh
        $ cd parts/zimbra-sources/ThirdParty/mysql/
        $ make

Unfortunately, the scripts provide no generic way to interrupt and restart
a third party build without rebuilding everything. So, after fixing the problem,
you will have to rebuild all of the components.



===========================
Further links and resources
===========================

http://www.zimbra.com/forums/installation/
http://wiki.zimbra.com/wiki/Main_Page
http://pm.zimbra.com/
http://www.zimbrafr.org/forum/topic/483-les-commandes-zimbra-qui-depannent/
http://wiki.zimbra.com/wiki/Logger_(ZCS_6.0.x_and_later)
http://wiki.zimbra.com/wiki/Zmprov_Examples
http://wiki.zimbra.com/wiki/Bulk_Provisioning



===============
Useful commands
===============

 - list all the admins:

        $ zmprov gaaa


 - reset the admin (or any other) password:

        $ zmprov sp <admin email address> <new password>


 - password recovery:

        $ zmlocalconfig -s | grep ldap_amavis_password
        $ zmlocalconfig -s | grep ldap_nginx_password
        $ zmlocalconfig -s | grep ldap_postfix_password
        $ zmlocalconfig -s | grep ldap_replication_password
        $ zmlocalconfig -s | grep ldap_root_password
        $ zmlocalconfig -s | grep zimbra_ldap_password


 - remove a mail store (i.e. when it has been added for testing)

        $ zmprov ds "myhost.mydomain.com"

   (must be run on the ldap server)


 - add ipv6 to an existing ipv4 install:

        $ zmprov ms zimbra1.cutedomain.co.uk zimbraIPMode both
        $ libexec/zmiptool
        $ zmcontrol restart