Before you upgrade

Please review the following information to decide if Zimbra Daffodil (v10) is suitable for you.

  • In-place upgrade of Multi-Node and Single-Node setup with NG Modules is not supported. But the migration of the Multi-Node setup with NG Modules is supported. Please refer to Multi-Server NG Modules Migration Guide for more details.

  • For customers using NG modules on a Single-Node setup, currently we do not support migration. We are working on steps to migrate such a setup. We will update you soon.

  • Zimbra Touch Client, Zimbra Mobile Client, and Zimbra HTML (Standard) Client are no longer a part of Zimbra starting from Version 9.0.0.

  • A Zimbra Network Edition license is required to use Zimbra Daffodil (v10).

  • The customizations implemented for SAML and SPNEGO will be overridden during updrade. It is recommended to backup these configurations before upgrade.

  • In case of rolling upgrades, if some mailstore nodes are upgraded to Zimbra 10 and some mailstore nodes are on Zimbra 9.0.x or Zimbra 8.8.15 then, zimbraReverseProxyUpstreamLoginServers should only contain list of Zimbra 10 mailboxes. If this is not followed then in some cases, users on Zimbra 10 mailstore nodes will not be able to see Modern Web App after login.

  • Zimbra 10.0.0 continues to support two versions of Zimbra Web Client — Modern and Classic.

    • To know more about highlights of the Modern Web App, please refer to Introducing the Modern Web Application

    • The Classic Web App offers the same functionality as the Advanced Web Client in Zimbra version 8.8.15.

    • Existing customized themes, logo branding changes, and crontab changes are incompatible with, and hence do not reflect in the Modern Web App. Branding needs to be re-configured to work with the Modern Web App. The Modern Web App does not currently support themes. Please refer to the Customizing Modern Web App section of Admin Guide for more information related to configuration.

    • Zimlets are supported on both the Web Clients.

    • Zimlets that work with the Classic Web App are incompatible with the Modern Web App. And due to technology changes, there is no way to migrate the Zimlets from the Classic Web App to the Modern Web App or vice-versa.

  • If you are using a RHEL based server (RHEL, Oracle Linux, Rocky Linux, Centos) then, please install pax/spax package on MTA node.

    • CentOS 7 and derivatives

      yum install pax

    • CentOS 8 and derivatives

      dnf install spax

  • Recommendations when using zmmboxmove

    • Always take full backup after doing zmmailboxmove

    • zimbraMailboxMoveSkipBlobs and zimbraMailboxMoveSkipHsmBlobs attributes should be FALSE when doing mailboxmove

    • Always recommended to run HSM and move blobs to current primary / secondary volumes in case of multiple primary / secondary volumes present in system before doing mailboxmove

    • If you want to add new current secondary volume then customer need to use blobmover cli to move blobs from previous secondary volume to new volume

    • zmmailboxmove command should be run from Zimbra 10 mailbox

Be sure to read the release notes information before upgrading.

Supported Upgrade Paths

With this release the following upgrade paths are currently supported. Other upgrade paths will be supported in upcoming releases of Zimbra 10.

Setup Support

Single Node, without NG modules, in-place upgrade

Supported

Single Node, with NG modules, in-place upgrade

Not Supported

Multi-Node, without NG modules, in-place upgrade

Supported

Multi-Node, with NG modules, in-place upgrade

Not Supported

Rolling upgrade, without NG modules

Supported

Rolling upgrade, with NG modules

Not Supported

Database Integrity Checking

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.

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

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 your normal maintenance windows and prior to running any Zimbra 10 upgrades.

Preparing your operating system

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

Ubuntu OS

  • Ubuntu 20.04 LTS Server Edition (64-bit)

  • Ubuntu 18.04 LTS Server Edition (64-bit)

Red Hat Enterprise Linux/CentOS Linux/Rocky Linux

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

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

  • RedHat® Enterprise Linux® 7 and 8 AS/ES (64-bit)

  • CentOS Linux® 7 (64-bit)

  • Oracle Linux® 7 and 8 (64-bit)

  • Rocky Linux® 8 (64-bit)

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 Zimbra Daffodil (v10) 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 Zimbra Daffodil Administration Guide 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.

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>).

zimbraReverseProxySSLCiphers
zimbraReverseProxySSLProtocols
zimbraSSLExcludeCipherSuites
zimbraMailboxdSSLProtocols
If you have not performed any recent hardening of your settings, your config should already match the Zimbra 10 default; and no action would be required.

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

  1. Remove the following from zimbraReverseProxySSLCiphers:

    ECDHE-RSA-RC4-SHA
ECDHE-ECDSA-RC4-SHA
RC4-SHA

  2. Add the following to zimbraReverseProxySSLCiphers:

    !RC4
    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

Go to http://www.zimbra.com/downloads/zimbra-collaboration to access the downloads section.

  • Before you begin the upgrade, make sure you have a good backup for all users!

When you run the install script and Zimbra 10 is already installed, a prompt appears asking if you want to upgrade. Follow the instructions in this release note to perform the upgrade. For additional information, refer to the installation guide.

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

You do not need to stop the services before upgrading. The upgrade process automatically stops and starts the services as required for the upgrade.

Zimbra Daffodil (v10) does not support upgrade and migration from previous versions with NG modules installed. These upgrade paths will be introduced in upcoming releases of Zimbra Daffodil (v10).

Following error message is displayed if we try to upgrade when NG modules are installed.

NG Modules detected on this system. If you continue with this upgrade, NG module packages and the associated data will be deleted.
If you want to preserve NG data, consider migrating or a rolling upgrade strategy for upgrading your system. For more information, please contact Zimbra Support.
If you still want to continue, start upgrade using --skip-ng-check.

Process

  1. Log in as root to the Zimbra 10 server and cd to the directory where the Zimbra Daffodil (v10) archive tar file is saved. For example, cd /var/tmp. Then type the following commands:

    Unpack the file

    tar xzvf zcs.tgz

    Change to the correct directory.

    cd <expanded-directory>

    Begin the upgrade installation.

    ./install.sh

  2. The upgrade script checks if proxy and memcached are present. If both are found, the upgrade will proceed. If either are missing then the upgrade will abort and alert.

  3. The Zimbra 10 software agreement appears in 2 parts. Read this software license agreement and type Y when prompted.

  4. When Use Zimbra’s package repository [Y] appears, press Enter to continue. Your system will be configured to add the Zimbra packaging repository for yum or apt-get so it can install the Zimbra third party packages.

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

  6. 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.

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

  8. If you have not set the time zone, you will be asked to set it. This sets the time zone in the default COS. The time zone that should be entered is the time zone that the majority of users in the COS will be located in.

  9. When the Configuration completes, press Enter.

  10. Once all the MTA nodes are upgraded to Zimbra Daffodil (v10), the following commands may be run to fix the default globalconfig values, if necessary.

    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

  11. DSPAM is no longer shipped starting Zimbra Collaboration 8.7. Please enter the following commands to disable it.

    zmprov ms `zmhostname` zimbraAmavisDSPAMEnabled FALSE
zmlocalconfig -e amavis_dspam_enabled=false
zmamavisdctl restart

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

  13. For the next steps after the upgrade, refer to the section After the Upgrade is Complete.

Multi-Server Environment Upgrade Steps

Upgrade the servers in the following order. Update each server one at a time, following the instructions under Process below.

  1. LDAP master server. The LDAP master servers must all be upgraded before proceeding, and they must be running as you upgrade the other servers.

  2. LDAP replicas

  3. MTA servers - see Using LMDB as the Supported Back-end for On-disk Database Maps.

  4. Proxy servers

  5. Setup new OnlyOffice server

  6. Mailstore servers

Process

  1. Log in as root to the Zimbra 10 server and cd to the directory where the Zimbra Daffodil (v10) archive tar file is saved. For example, cd /var/tmp. Then type the following commands:

    Unpack the file

    tar xzvf zcs.tgz

    Change to the correct directory.

    cd <expanded-directory>

    Begin the upgrade installation.

    ./install.sh

  2. The upgrade script checks if proxy and memcached are present. If both are found, the upgrade will proceed. If either are missing then the upgrade will abort and alert.

  3. The Zimbra 10 software agreement appears in 2 parts. Read this software license agreement and type Y when prompted.

  4. When Use Zimbra’s package repository [Y] appears, press Enter to continue. Your system will be configured to add the Zimbra packaging repository for yum or apt-get so it can install the Zimbra third party packages.

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

  6. 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.

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

  8. If you have not set the time zone, you will be asked to set it. This sets the time zone in the default COS. The time zone that should be entered is the time zone that the majority of users in the COS will be located in.

  9. When the Configuration completes, press Enter.

  10. Once all the MTA nodes are upgraded to Zimbra Daffodil (v10), the following commands may be run to fix the default globalconfig values, if necessary.

    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

  11. DSPAM is no longer shipped starting Zimbra Collaboration 8.7. Please enter the following commands to disable it.

    zmprov ms `zmhostname` zimbraAmavisDSPAMEnabled FALSE
zmlocalconfig -e amavis_dspam_enabled=false
zmamavisdctl restart

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

  13. For the next steps after the upgrade, refer to the section After the Upgrade is Complete.

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

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

Zimbra 10 has not officially supported using any Postfix on-disk database maps prior to Zimbra Collaboration 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:

  1. Run postmap against the database input file to generate an LMDB database.

  2. 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 Zimbra 10. Check if your customizations are correctly carried forward when upgrading. See Bug 77586.

After the Upgrade is Complete

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

  • If you have configured the following keys, you will need to replace them as described here.

The following keys are deprecated:

httpclient_client_connection_timeout
httpclient_connmgr_connection_timeout
httpclient_connmgr_idle_reaper_connection_timeout
httpclient_connmgr_idle_reaper_sleep_interval
httpclient_connmgr_keepalive_connections
httpclient_connmgr_max_host_connections
httpclient_connmgr_max_total_connections
httpclient_connmgr_so_timeout
httpclient_connmgr_tcp_nodelay

They are replaced by the following keys:

httpclient_internal_client_connection_timeout
httpclient_internal_connmgr_connection_timeout
httpclient_internal_connmgr_idle_reaper_connection_timeout
httpclient_internal_connmgr_idle_reaper_sleep_interval
httpclient_internal_connmgr_keepalive_connections
httpclient_internal_connmgr_max_host_connections
httpclient_internal_connmgr_max_total_connections
httpclient_internal_connmgr_so_timeout
httpclient_internal_connmgr_tcp_nodelay
httpclient_external_client_connection_timeout
httpclient_external_connmgr_connection_timeout
httpclient_external_connmgr_idle_reaper_connection_timeout
httpclient_external_connmgr_idle_reaper_sleep_interval
httpclient_external_connmgr_keepalive_connections
httpclient_external_connmgr_max_host_connections
httpclient_external_connmgr_max_total_connections
httpclient_external_connmgr_so_timeout
httpclient_external_connmgr_tcp_nodelay

  • We are not removing zextras zimlets from LDAP node as it can break multi node rolling upgrade setup, so after upgrade is complete on all nodes customers can undeploy below zimlets for cleanup.

com_ng_auth
com_zextras_zextras
com_zextras_client
com_zimbra_connect_classic
com_zimbra_connect_modern
com_zextras_docs
com_zimbra_docs_modern
com_zimbra_drive_modern
com_zextras_drive
com_zextras_drive_open
com_zextras_chat_open
com_zextras_talk
zimbra-zimlet-briefcase-edit-lool

Installing External Zimlets for Modern Web App

These five zimlets are available.

  • Slack

  • Zoom

  • Dropbox

  • Google Drive

  • Onedrive

You have to install and configure them for users to integrate and use these zimlets. Once you are done installing the zimlet(s), you need to restart the mailbox service before configuring them.

Slack

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-slack

    Ubuntu

    apt-get install zimbra-zimlet-slack

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Zoom

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-zoom

    Ubuntu

    apt-get install zimbra-zimlet-zoom

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Dropbox

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-dropbox

    Ubuntu

    apt-get install zimbra-zimlet-dropbox

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Google Drive

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-google-drive

    Ubuntu

    apt-get install zimbra-zimlet-google-drive

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Onedrive

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-onedrive

    Ubuntu

    apt-get install zimbra-zimlet-onedrive

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Please visit Configuring Zimlets for Modern Web App for instructions for on how to configure zimlets for Modern Web App users.

Ephemeral Data Migration

Versions of Zimbra prior to 9.0.0 stored ephemeral data in LDAP. Examples of ephemeral data include:

  • zimbraAuthTokens

  • zimbraCsrfTokenData

  • zimbraLastLogonTimestamp

Zimbra Collaboration versions after 9.0.0 introduced the ability to store ephemeral data in an external service such as SSDB. This is an optional feature; however, it can improve LDAP performance and stability.

Please refer to the Zimbra Daffodil Administration Guide for more information. Migration of ephemeral data out of LDAP and into SSDB must be performed after an install or upgrade has been completed.

Remove Current Version and Perform Clean Install of Zimbra 10

If you do not want to upgrade, but prefer to install Zimbra Daffodil (v10) as a new installation, when you run the Zimbra Daffodil (v10) install script, enter N 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, 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 Daffodil might be deprecated and/or overwritten during upgrades, removing any customizations. This includes customized themes, logo branding changes, and crontab changes.

Branding needs to be re-configured to work with the Modern Web App. And the Modern Web App currently does not support themes.

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.

Zimlets are supported on both the Classic Web App and the Modern Web App. However, Zimlets used for Classic Web Client are not compatible with the Modern Web App. Currently, there is no way to migrate the zimlets from Classic to the Modern Web App or vice-versa. Existing zimlets need to be re-developed for them to work on the Modern Web App.

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