Around the time of Zimbra 4.0.5 in 2006, Zimbra had a short installation “Cheat Sheet” that simplified performing a Zimbra installation.
All the data (now updated) in that old Cheat Sheet is available in the current Zimbra Documentation and detailed Installation guides, but for someone who just needs to prototype a Zimbra install, or get a Zimbra server up and running fast, the current detailed guides are not efficient. Further, the Zimbra Forums are starting to see a lot more of these installation-related “Zimbra’s not working…” questions, so it’s clear the current super-detailed Installation Guides would benefit from a companion Quick Start Installation Guide, so I’ll try to provide that here in this post.
Get Ready – Operating System Installation and Firewalling
In my more than a dozen years of dealing with customers’ Zimbra installations, the most creatively borked Zimbra systems were the ones maintained by the most experienced Linux System Admins. Why? Because they recognized all those familiar open-source components within Zimbra, had lots of experience tweaking those components “their way”, and also knew how to have a single Linux box perform lots of different tasks and support multiple applications. So the first step in getting ready for a Zimbra installation is to think of a Zimbra server as a black-box appliance where you get to choose the operating system from a short list of approved operating systems, but also where you shouldn’t plan on tweaking anything, let alone having the Zimbra server host another application.
The second step is to plan your disk partitioning. If you are doing just a quick lab installation to get some experience with Zimbra, one big partition at least twice as large as your mailstore size will be fine for a proof-of-concept. But as Zimbra is very I/O intensive (all mail servers are), it’s best to consider separate partitions for different Zimbra elements. Check out my AWS Disk Reference architecture post for some partitioning suggestions.
The third step is to install your (Zimbra-approved) operating system as bare-bones as possible, with only an SSH server. If you are using Ubuntu, after the installation is completed you can install a few more prerequisite packages, but the Zimbra installer itself will prompt you about any missing prerequisites as well, so if you miss something, it’s not a big deal and won’t “break” your Zimbra installation. Use only the distros for which Zimbra provides ready-made binaries.
Lastly, note that Zimbra recommends NOT running a software firewall on a Zimbra server, but you should have a firewall in front of Zimbra, exposing only the allowed External Access ports needed for your installation. For example, if you don’t allow POP3, don’t open the POP3 and POP3S ports.
After you get the operating system installed and firewalled, presuming Ubuntu 16.04 and a subsequent Network Edition installation, you should run:
apt-get update; apt-get dist-upgrade Note: A reboot may now be required if a new kernel has been installed. After the reboot, optionally run: apt-get install git sqlite3 libreoffice libreoffice-l10n-* fonts-vlgothic dnsmasq
The package “git” will be used to install a LetsEncrypt SSL certificate; “sqlite3” is used for Zimbra’s optional Policy Daemon, the LibreOffice packages are for Network Edition’s High-Fidelity attachment/document previews, and “dnsmasq” is my preferred DNS server for most Zimbra systems. If you don’t need any of those extra packages, don’t install them.
Get Set – Operating System and DNS Configuration
There are three tasks here, the first two of which are DNS-related. It’s here where most newbies in their rush to install Zimbra skip over some required steps only to find Zimbra doesn’t work post-install.
The most important thing to keep in mind in this phase is that Zimbra is very DNS-dependent, so if your DNS setup isn’t totally spot on, you will have problems. Zimbra may install, it may actually start, but even if it does it won’t work entirely properly.
First, you need to configure the files /etc/hosts /etc/resolv.conf and /etc/hostname correctly. For these three files and the tests below, let’s presume we are going to build a single server called “webmail.mynewtestdomain.ca” on a private network 172.16.1.0/24 and give the Zimbra server an IP address of 172.16.1.32. Note that the actual configuration of these files is beyond the scope of this article and is highly dependent on your operating system and whether you are using DHCP or static IP address assignments, so that part’s on you! Be sure the files as edited survive a reboot without change!
# /etc/hosts Contents: 127.0.0.1 localhost.localdomain localhost 172.16.1.32 webmail.mynewtestdomain.ca webmail # /etc/resolv.conf Contents: nameserver 127.0.0.1 search mynewtestdomain.ca # /etc/hostname Contents: webmail
The second task is to configure DNS lookups appropriately. One of the things you will notice above is that I’ve set localhost as the DNS server for this server. That means that you need either to install BIND or (my favorite) dnsmasq. Alternatively, you can specify your existing in-house DNS servers, provided however that they will resolve the A, PTR and MX records for your Zimbra server and its domain correctly (see the tests below). If you want to use dnsmasq, I have a blog post which discusses how to set up dnsmasq correctly for Zimbra. Regardless of what you use, your operating system will need to pass all four of the following tests, all performed from the commandline of your Zimbra server, and before you attempt to install Zimbra!
DNS Test 1: Forward Lookups ubuntu@webmail:~$ host webmail.mynewtestdomain.ca webmail.mynewtestdomain.ca has address 172.16.1.32 ubuntu@webmail:~$ host webmail webmail.mynewtestdomain.ca has address 172.16.1.32 ubuntu@webmail:~$ DNS Test 2: Reverse Lookup: ubuntu@webmail:~$ host 172.16.1.32 18.104.22.168.in-addr.arpa domain name pointer webmail.mynewtestdomain.ca ubuntu@webmail:~$ DNS Test 3: Outside Lookup: ubuntu@webmail:~$ host www.yahoo.com www.yahoo.com is an alias for atsv2-fp.wg1.b.yahoo.com. atsv2-fp.wg1.b.yahoo.com has address 22.214.171.124 atsv2-fp.wg1.b.yahoo.com has address 126.96.36.199 atsv2-fp.wg1.b.yahoo.com has address 188.8.131.52 atsv2-fp.wg1.b.yahoo.com has address 184.108.40.206 atsv2-fp.wg1.b.yahoo.com has IPv6 address 2001:4998:58:1836::10 atsv2-fp.wg1.b.yahoo.com has IPv6 address 2001:4998:44:41d::4 atsv2-fp.wg1.b.yahoo.com has IPv6 address 2001:4998:58:1836::11 atsv2-fp.wg1.b.yahoo.com has IPv6 address 2001:4998:44:41d::3 ubuntu@webmail:~$ DNS Test 4: MX Lookup: ubuntu@webmail:~$ dig mynewtestdomain.ca mx <snip> ;; QUESTION SECTION: ;mynewtestdomain.ca. IN MX ;; ANSWER SECTION: mynewtestdomain.ca. 0 IN MX 5 webmail.mynewtestdomain.ca. ;; ADDITIONAL SECTION: webmail.mynewtestdomain.ca. 0 IN A 172.16.1.32 ;; Query time: 0 msec ;; SERVER: 127.0.0.1#53(127.0.0.1) <snip>
If you get results like the ones above, you are almost ready to run the Zimbra Installer! If not, you need to fix your DNS configuration before you try to go any further.
The third task is actually a pair of operating system tweaks: First, remove/disable Ubuntu’s AppArmor or RHEL/CentOS’s SELinux and second, add the following lines to /etc/sysctl.conf:
# Turn off IPv6 (because in this example we are running Zimbra on an IPv4 network!) net.ipv6.conf.all.disable_ipv6 = 1 net.ipv6.conf.default.disable_ipv6 = 1 net.ipv6.conf.lo.disable_ipv6 = 1 # Reduce Swappiness to Zimbra's recommended setting vm.swappiness = 1
Some Linux distros require turning off IPv6 in the grub boot manger options file.
Give the server one final reboot, rerun the DNS tests above, check that /etc/hosts, etc/resolv.conf and /etc/hostname did not get modified by any system configuration daemon and if all is good, you are now, finally, ready to run the Zimbra installer. Ready, Set, and…
Go! – Run The Zimbra Installer
First you need to download the Network Edition or Open Source binary that matches your operating system. The installer is run as root, so I like to create a /zcs directory off the root directory in which to download the installer package and unpack it there. If you are installing Network Edition, /zcs is a good place to put your ZCSLicense.xml file as well (the installer will ask for it).
Generally speaking, you can accept most of the defaults the installer proposes. The most important exceptions IMHO are as follows:
- The installer will propose the default domain as the FQDN of the Zimbra server (webmail.mynewtestdomain.ca). Change it to “mynewtestdomain.ca”.
- Under Common Configuration, change the Time Zone to your local time zone or to UTC; whatever makes sense for you.
- Change the Admin User account from “firstname.lastname@example.org” to something else. The bad guys know Zimbra sets this default and will endeavor to log in to this account, lock it out, and then you’ll wonder why you can’t log in to the Admin Console. You need to change this email address in several places in the installation menus.
- Under Proxy Configuration, change the Proxy Server Mode to “redirect”, so that when a user browses to “webmail.mynewtestdomain.ca”, Zimbra’s Proxy will redirect them from http to https — and stay https after login.
If you installed Network Edition, you can Activate your Zimbra license from the Admin Console after the installation completes.
Post-installation, there are pages of tweaks we make to Zimbra to more fully conform Zimbra to Zimbra’s and our Best Practices. Here are some links to our anti-spam best practices and using DoSFilter and a failed lockout policy in unison.
Hope that helps,
L. Mark Stone
Mission Critical Email
20 May 2018
The information provided in this blog is intended for informational and educational purposes only. The views expressed herein are those of Mr. Stone personally. The contents of this site are not intended as advice for any purpose and are subject to change without notice. Mission Critical Email makes no warranties of any kind regarding the accuracy or completeness of any information on this site, and we make no representations regarding whether such information is up-to-date or applicable to any particular situation. All copyrights are reserved by Mr. Stone. Any portion of the material on this site may be used for personal or educational purposes provided appropriate attribution is given to Mr. Stone and this blog.