Zimbra Releases/8.7.0/Upgrade

Revision as of 01:34, 29 June 2016 by Mmedellin (talk | contribs)

Zimbra Collaboration 8.7.0 GA Upgrade steps

Before you upgrade

The following tasks might need to be performed before you upgrade. After you review the tasks in this section, go to Upgrade Instructions. Be sure to read the release note information before upgrading.

Database Integrity Check

Some customers have had corrupted databases prior to upgrade, and the upgrade has in some of those cases exacerbated the problem. In order to detect any corrupted databases as early as possible, we have added an optional step to check the MariaDB database with zmdbintegrityreport prior to making any system changes. You are prompted to decide if you would like to run the zmdbintegrityreport.

The zmdbintegrityreport can take minutes to an hour to run, depending on your system size and disk bandwidth.

Note: The zmdbintegrityreport is run on a weekly basis from cron on all zimbra-store nodes. Large sites can opt to disable this by setting zmlocalconfig -e zmdbintegrityreport_disabled=TRUE. If you choose to disable this, it is recommended that the integrity reports be run by hand during the your normal maintenance windows and prior to running any ZCS upgrades.

Preparing your operating system

Before you upgrade ZCS, Zimbra recommends that the operating system is updated with the latest patches that have been tested with ZCS.

Ubuntu OS
  • Ubuntu 14.04 LTS Server Edition (64-bit)
  • Ubuntu 12.04.4 LTS Server Edition running the saucy (3.11) or later kernel is required. Note: If the original install was done with Ubuntu 12.04.2 or earlier, manual intervention is required to switch to the saucy (3.11) or later kernel series. See https://wiki.ubuntu.com/Kernel/LTSEnablementStack for further information.

You can find your current kernel version by running:

uname -a

For example:

build@zre-ubuntu12-64:~$ uname -a
Linux zre-ubuntu12-64 3.11.0-17-generic #31~precise1-Ubuntu SMP Tue Feb 4
21:25:43 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux

Red Hat Enterprise Linux/CentOS Linux

Important: If running the RHEL linux distribution, you must have a current valid license from RedHat.

Important: The server must have a valid yum or apt-get configuration so that it can reach the Zimbra package servers.

  • Red Hat® Enterprise Linux® 7, AS/ES (64-bit)
  • CentOS Linux® 7 (64-bit)
  • Red Hat Enterprise Linux 6, AS/ES (64-bit), patch level 4 or later is required
  • CentOS Linux 6 (64-bit), patch level 4 or later is required

License Activation


  • At the beginning of an upgrade installation, the existing license is validated as being current and qualifies for the upgrade. If your license is expired, an error message displays and the upgrade cannot be performed. Contact Zimbra Sales for a license renewal to continue your upgrade.
  • An upgrade installation will not proceed without automatic activation or a manually activated license file. License activations are limited to five activations per license file. If you have previously used all activations prior to upgrading your production system, you must contact Zimbra Sales to enable additional license activations.

All network edition installations require a valid license and license activation. New installs will have a 10 day grace period from the license issue date before requiring activation.

License activation is automatic during the install with systems that have external access to the Zimbra license servers. A means of creating manual activations will be provided for systems that do not have external access to the Zimbra license servers. See the ZCS installation guides for more information.

When upgrading, the way in which ZCO and archiving licensing is enforced might have changed on the server if you are using an older version of Zimbra Collaboration. Older licenses might have MAPIConnectorAccountsLimit set to 0 or ArchivingAccountsLimit missing in the license. Contact Zimbra Sales for an updated license file prior to upgrading if you have licensed either of these features and your current license does not properly reflect the correct number.

Upgrading LDAP Replica Servers or Multi-Master Server from ZCS 8.0.0, 8.0.1, 8.0.2 to ZCS 8.0.4 and later

If you have replica servers or are in multi-master mode, you have to install the Zimbra LDAP schema specific to the release you are upgrading to onto the replica servers or onto the multi-master server before you upgrade to ZCS 8.0.4 and later. (Bug 81048)

1. On the master LDAP server, perform a software installation only of ZCS 8.0.4 and later.

./install.sh -s

2. On each replica or additional master LDAP server in MMR mode, as zimbra user:

a. Stop the server:

ldap stop or zmcontrol stop

b. Move the zimbra schema out of the way

cd /opt/zimbra/data/ldap/config/cn=config/cn=schema
mv cn={4}zimbra.ldif /opt/zimbra/data/ldap/cn={4}zimbra.ldif.dead 

c. Copy the schema from the master LDAP server.

scp root@<master>:/opt/zimbra/openldap/etc/openldap/schema/zimbra.ldif cn={4}zimbra.ldif 

d. Edit cn={4}zimbra.ldif to change the following two lines:

dn: cn=zimbra,cn=schema,cn=config     ------->     dn: cn={4}zimbra
cn: zimbra                                                ------->     cn: {4}zimbra 

e. Start the server:

ldap start or zmcontrol start

3. On the master LDAP server run:


4. On each replica server run:


To continue the upgrade, see Multi-Server Environment Upgrade Steps.

Disable SSLv3 Support

If upgrading to ZCS 8.7.0, you need to completely disable SSLv3 support after the upgrade. Disabling SSLv3 is recommended as a result of the SSLv3 vulnerability described in Security Fixes on page 9.

SSLv3 support has been deprecated by default in 8.6.0, although when upgrading from previous versions of ZCS, some protocols might still be enabled.

  • New keys created in 8.7.0 have SSLv3 disabled by default
  • Pre-existing keys from earlier versions of ZCS will still have SSLv3 enabled.

Follow the steps in the Zimbra wiki article https://wiki.zimbra.com/wiki/How_to_disable_SSLv3 to disable SSLv3 after upgrading to ZCS 8.7.0.

Update Default Proxy SSL Ciphers Attribute

Whenever upgrading, it is recommended that you check the values of the following attributes (zmprov gcf <attr>) and compare them with the current default values (zmprov desc -a <attr>).

If you have not performed any recent hardening of your settings, your config should already match the ZCS default; and no action would be required.


In addition, it is recommended to make the following changes:

1. Remove the following from zimbraReverseProxySSLCiphers:


2. Add the following to zimbraReverseProxySSLCiphers:


See https://wiki.zimbra.com/wiki/Cipher_suites for the most current information on cipher suite configuration.

Customizing ZCO Installations

Administrators who want to customize the ZCO installation MSI should use the unsigned version of the MSI (ZimbraConnectorOLK_n.n.n.nnnn_xnn-unsigned.msi), available in the Zimbra download directory. The modified MSI should then replace the standard signed MSI (ZimbraConnectorOLK_n.n.n.nnnn_xnn.msi) in order to be available to end users from /downloads/index.html and the ZCO auto-upgrade process. (Bug 85067)

Upgrade Instructions

Download the Software

For Network Edition, go to http://www.zimbra.com/downloads/zimbra-collaboration to access the software.


  • Before you begin the upgrade, make sure you have a good backup for all users!
  • Database reloads are performed on 7.x to any 8.x upgrade.

When you run the install script, if ZCS is already installed, you will be asked if you want to upgrade. Follow the instructions in this release note to perform the upgrade. For additional information, refer to the installation guide.

Important: Zimbra recommends that an install or upgrade session be run with a UNIX command such as “screen” to help prevent an install or upgrade session from terminating before it is completed. This is important when the upgrade includes restoring a configuration that has a large number of accounts.

Example command usage:

screen ./install.sh

Single Server Upgrade Steps


1. Log in as root to the Zimbra server and cd to the directory where the ZCS Network Edition archive tar file is saved (cd /var/tmp). Type the following commands:

Upack the file

tar xzvf zcs.tgz

Change to the correct directory

cd [zcsversionfullname]

Begin the upgrade installation


2. The upgrade script checks if proxy and memcached are present. If both are found, only then upgrade continues.

If either or both are missing, the upgrade will abort and alert "From 8.7.0 onwards proxy and memcached is compulsory". Links are provided for installing proxy and memcached. For instructions to install proxy and memcached, check here

Then comes License check Then comes LDAP check

3. The Zimbra software agreement is displayed. Read this software license agreement and type Y.

4. When Use Zimbra's packaging server [Y] is displayed, press enter to continue. Your system will be configured to add the zimbra packaging repository for yum or apt-get as appropriate so it can install the Zimbra 3rd party packages.

If N is selected, shows this message:

Use Zimbra's package repository [Y] n

The Zimbra Collaboration Server appears to already be installed. It can be upgraded with no effect on existing accounts, or the current installation can be completely removed prior to installation for a clean install.

and continues upgrade

e. When Do you wish to upgrade? [Y] is displayed, press Enter to continue. The upgrade packages are unpacked.

f. The packages are listed. The installer also lists packages that are not installed. If you want to install the packages at this time, type Y; otherwise press Enter. The upgrade checks that there is enough space to perform the upgrade. If there is not enough space, the upgrade stops.

g. When The system will be modified. Continue? [N] is displayed, type Y and press

z. After all MTA nodes are upgraded to ZCS 8.7, the following commands must be run to fix the default globalconfig values.

zmprov mcf zimbraMtaCommandDirectory /opt/zimbra/common/sbin
zmprov mcf zimbraMtaDaemonDirectory /opt/zimbra/common/libexec
zmprov mcf zimbraMtaMailqPath /opt/zimbra/common/sbin/mailq
zmprov mcf zimbraMtaManpageDirectory /opt/zimbra/common/share/man
zmprov mcf zimbraMtaNewaliasesPath /opt/zimbra/common/sbin/newaliases
zmprov mcf zimbraMtaSendmailPath /opt/zimbra/common/sbin/sendmail
Multi-Server Environment Upgrade Steps


Upgrade the servers in the following order. Update each server one at a time.

  • LDAP master server. The LDAP master servers must all be upgraded before proceeding, and they must be running as you upgrade the other servers.
  • LDAP replicas
  • MTA servers - see Using LMDB as the Supported Back-end for On-disk Database Maps.
  • Proxy servers
  • Mailstore servers

Important: Certificates. If self-signed certificates are used, after the LDAP master is upgraded, the self-signed certificates must be redeployed on all remaining nodes BEFORE they are upgraded. If you do not do this, the upgrade will fail. Use CLI zmcertmgr to add the certificates. As root, type

sudo /opt/zimbra/bin/zmcertmgr deploycrt self

12. Log in as root to the Zimbra server and cd to the directory where the ZCS upgrade archive tar file is saved (cd /var/tmp). Type the following commands:

tar xzvf zcs.tgz, to unpack the file
cd [zcsversionfullname], to change to the correct directory
./install.sh, to begin the upgrade installation

The upgrade script begins by checking for an existing installation.

13. Three software license agreements are displayed. Read these license agreements and enter Y for each.

14. The installer checks for prerequisites. If any are missing, the upgrade stops.

Mailstore server - The installer checks for a recent backup. If one is not found, Do you wish to continue without a backup? is displayed. The default is N. If you select N, you exit the upgrade. Run a backup and then restart the upgrade.

15. When you upgrade the mailstore server, the installer displays Do you want to verify message store database integrity (Y) is displayed. The default is Yes. This step runs zmdbintegrityreport to verify that the MariaDB database is not corrupt before upgrading to the latest ZCS.

Running zmdbintegrityreport can take minutes to an hour to run, depending on your system size and disk bandwidth. It is preferable that you run zmdbintegrityreport at the time of the ZCS upgrade. If you choose to skip this now, the zmdbintegrityreport will run during a regular scheduled interval after the upgrade is finished.

When the MariaDB software versions are changed during upgrades, the underlying database tables need to be upgraded. The zmdbintegrityreport does this automatically during it’s first run and will report the changes. These are normal and should not cause alarm when upgrading.

16. When Do you wish to upgrade? [Y] n is displayed, type Y and press Enter to continue.

The upgrade packages are unpacked.

17. The packages you want to install on the server should be marked Y. All other packages should be marked N.

The upgrade checks that there is enough space to perform the upgrade. If there is not enough space, the upgrade stops.

18. When The system will be modified. Continue? is displayed, type Y and press Enter. The server is stopped and the older packages are removed. The upgrade process verifies which version of ZCS is being run and proceeds to upgrade the services, restores the existing configuration files, and restarts the system. If you have a configuration with a large number of accounts created, this can take a while.

Note: When upgrading the zimbra mail store, the upgrade checks for the Zimbra license. If the license is found it lists the number of current users and the number of user licenses. If it is not found, press Enter to continue. You can add the license later from the administrator’s console.

19. When Configuration complete – press Enter to exit. The upgrade is complete. Continue the upgrade to each server.

20. It is recommended that you perform a full backup after performing a major upgrade, due to database schema changes.

Important: Restoring a full backup to a newer release can fail due to schema differences. It is highly recommended to perform a full backup after every major upgrade to ensure that you have a restore point on the upgraded version.

Using LMDB as the Supported Back-end for On-disk Database Maps

Starting with ZCS 8.5 and later, Postfix is linked to LMDB, the same back-end ZCS uses with OpenLDAP. Prior to ZCS 8.0, Postfix was linked to Berkeley DB.

ZCS has not officially supported using any Postfix on-disk database maps prior to ZCS 8.5. However, these have been used through custom non-preserved modifications to the postconf configuration. These modifications will be lost on upgrade.

To restore the modifications post-upgrade, the following steps need to be performed: 21. Run postmap against the database input file to generate an LMDB database 22. It will be necessary to iterate through the postconf keys that have hash:/path/to/db values and update them in LDAP to use lmdb:/path/to/db values instead.

Many previously unsupported features that could be used with on-disk database maps are now fully supported by ZCS. Check if your customizations are correctly carried forward when upgrading. (Bug 77586)

After the Upgrade is Complete

After you completed the upgrade, the following might need to be addressed.

  • Review Disable SSLv3 Support
  • Review Update Default Proxy SSL Ciphers Attribute
  • During the upgrade process, zimbra might make a binary backup of existing databases when there are major structural changes occurring to the database format for ease of downgrading. Administrators will want to clean these up once they have confirmed a successful upgrade. For LDAP servers, these backups are in /opt/zimbra/data/ldap, and in the form of <dbname>.prev.$$" where $$ is the process ID of the upgrade script. (Bug 81167)
  • You should run zmldapupgrade -b 66387 after upgrading.

The zimbraAllowFromAddress attribute cannot be set for internal accounts or distribution lists. Running this script will change zimbraAllowFromAddress values to grants.

This step was not included into the installer-driven upgrade due to potentially long delay for sites that set zimbraAllowFromAddress on many accounts.

The migration command reports how many accounts had zimbraAllowFromAddress attribute set and how many of them needed migration. One way to verify all accounts got migrated is to run the command again. The total won't change, and the number migrated should be 0. (Bug 66387)

  • If your self-signed SSL certificates have expired, update them. See Verify Certificates Expiration Date on page 14.
  • If using zmlogger prior to ZCS 8.0.7, see Cleanup Procedure for Logger Host on page 25.
  • If you have configured the following keys, you will need to replace them as described here. The following keys are deprecated:

and are replaced by the following keys:


Updating Your MariaDB Table

If you upgrading from 6.X to ZCS 8.5.x and later, MariaDB table upgrade is required after upgrading. If you do not upgrade MariaDB, regular reports from zmdbintegrityreport are going to flag warnings in your MariaDB table. Customers can avoid these errors in the zmdbintegrityreport output by executing /opt/zimbra/libexec/scripts/migrate20100913-Mysql51.pl.

MariaDB upgrades are not automatically run during the upgrade, because of the time that it takes this process to run. There is no known performance impact when running in production without doing this MariaDB table upgrade.

Applying the Mysql51.pl script requires all Zimbra services except mysql.server to be stopped.

This script should be executed on all the mailstore servers where the mailboxd process is running. For a 4000 mailbox, 250 MB mailbox size, the script could take about 70 minutes to run. Customers should schedule their maintenance window accordingly. To run the script:

1. Switch to zimbra user.

su - zimbra

2. Stop mailboxd services to avoid email communications that might cause an interruption.

zmmailboxdctl stop

3. Execute the perl script to upgrade the database tables.


4. Start the mailboxd service.

zmmailboxdctl start

Remove Current Version and Perform Clean Install of ZCS

If you do not want to upgrade, but prefer to install Zimbra Collaboration Network Edition as a new installation, when you run the Zimbra Collaboration Network Edition install script, enter N (no) when asked Do you wish to upgrade?

A warning displays asking if you want to delete all existing users and mail. If you enter Yes,/code>, all users, mail, and previous files are removed before proceeding with the new installation. Refer to the installation guides for installation instructions.

Status of Your Customization after Upgrade

Upgrading to the newest release does not delete your accounts or change your configuration. Configuration settings stored in LDAP and localconfig are preserved during upgrades. Any files installed by Zimbra Collaboration might be deprecated and/or overwritten during upgrades, removing any customizations. This includes customized themes, logo branding changes, and crontab changes. Only the core Zimlets are enabled after the upgrade. Zimlets that you customized and/or deployed are preserved during the upgrade but will be disabled. As upgrading of customized Zimlets cannot be tested before the release, Zimbra recommends that you verify that your customized Zimlets work correctly before re-enabling them for your end-users after the upgrade.

Note: When upgrading to Zimbra Collaboration 8.5.x and later from a previous major ZCS version, the upgrade step disables Zimlets that are not the core Zimlets for ZCS in all COSs. If you have enabled other Zimlets at the account level, you might need to manually disable these Zimlets. (Bug 77836)

All entries between the designated comments in the Zimbra crontab file are overwritten with new defaults upon upgrade. Customized backup schedules stored in the Zimbra crontab and customizations to the crontab entry outside the designated comments are preserved.

Changes to Customized Themes

In Zimbra Collaboration 8.5.x and later, a new design for default skins was implemented. Custom skins created for Zimbra 7.x might not work as intended with Zimbra Collaboration 8.5.x and later. Depending on what is in the skin, the issues might range from simple things such as colors being used in the wrong places to larger issues like functional components being hidden or placed in inaccessible areas of the screen. The proper fix for this is to take an existing 8.5.x or later skin, duplicate it, and update the skin to meet the same needs as the old skin. (Bug 62523)

Jump to: navigation, search