License

CC BY-SA Synacor, Inc., 2022-2023

© 2022-2023 by Synacor, Inc. Zimbra Daffodil (v10) Multi-Node NG Modules Migration Guide through Rolling-Upgrade

This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License unless another license agreement between you and Synacor, Inc. provides otherwise. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0 or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.

Synacor, Inc., 2022-2023
505 Ellicott Street, Suite A39
Buffalo, NY 14203
US

Introduction

This guide provides steps to migrate the 8.8.15/9.0.0 Multi-Node NG/Non-NG servers to Zimbra Collaboration Daffodil (v10) using the Rolling-upgrade method.

This method does not support migrating the 8.8.15-FOSS with/without Zimbra Suite Plus (ZSP) setup. To migrate such setup, please refer to in-place upgrade guide.

Zimbra Collaboration when installed with NG modules installs the following modules:

  • Hierarchical Storage Management.

  • Backup & Restore.

  • Mobile - ActiveSync.

  • Device Management - ABQ.

  • Delegated Admin.

  • Drive.

  • Connect.

The migration is only supported from Zimbra Collaboration 8.8.15 and 9.0.0 versions running the latest patch release.
This method of migration does not support migrating the 8.8.15-FOSS with/without Zimbra Suite Plus (ZSP) setup.
This migration utility currently does not support the migration of Zimbra Connect / Chat data.
For Backup & Restore feature, Zimbra Collaboration Daffodil (v10) currently does not support storing backup files on S3 external storage or restoring backup from S3 external storage.

When executing these steps, it is recommended to test within a test environment and ensuring there is a backup just in case. Also, this guide is created in steps that can be done once or within different maintenance windows.

Overview

In this method, we leverage the Zimbra server’s ability to cluster multiple systems together to add a new system containing the latest version, migrate account data, then deprecate the existing system.

This method is suitable for you, if:

  • You want to move to new hardware, data centers, or to the cloud, and/or change operating systems.

  • You want limited downtime.

  • You want to test configuration and setup prior to migration.

  • You want to maintain Account Integrity.

Audience

This migration guide assumes you have a thorough understanding of system administration concepts and tasks and are familiar with email communication standards, security concepts, directory services, and database management.

Migration using Rolling-Upgrade method

The ability to use the rolling upgrade methodology allows for extreme flexibility to manage and upgrade ZCS servers. Because ZCS server is OS independent, this migration method allows the ability to add and upgrade new LDAP, MTA, Proxy, and Mailbox servers using the same ZCS version with an updated or different OS.

We will assume following are the components setup in the multi-node environment. You will need to upgrade/migrate each component in the following order:

  1. Two MMR LDAP Servers

  2. Two Proxy Servers

  3. Two MTA Servers

  4. Two Mailbox Servers

Because the NG modules is a mailbox servers feature, this allows the ability to upgrade the LDAP, Proxy, and MTA without effecting the current mailbox server functionality. Also since each mailbox is independent of the other, you can upgrade one mailbox server at a time until all of the mailbox servers are upgraded to Daffodil (v10). This means the mailbox servers within the cluster will be running in a mixed mode where some mailbox servers will be on Daffodil (v10) and others on an older version until all servers are migrated.

The design of this document was develop to provide steps on how to do a rolling upgrade but Zimbra is design to provide flexibility and it is possible to do an in-place upgrade of LDAP, proxy and MTA while doing a rolling upgrade of the mailbox servers. Following are the steps involved in the rolling upgrade method:

Create a new server for each existing server within the cluster using the desired OS version. Then perform the following steps in order:

  1. LDAP

    1. Install LDAP using current version on the new OS

    2. Add to LDAP cluster

    3. Point all existing servers to the new LDAP servers and decommission existing LDAP servers

    4. Upgrade new LDAP’s to Daffodil

  2. Proxy

    1. Install & Configure Daffodil proxy

    2. Direct Production traffic to Daffodil proxy

    3. Deprecate existing proxy servers

  3. MTA

    1. Install & Configure Daffodil MTA

    2. Direct Production traffic to Daffodil MTA

    3. Deprecate existing MTA servers

  4. Mailbox

    1. Install Daffodil Mailbox services using the existing package configuration

    2. Customize and test the environment.

    3. Migrate accounts

    4. Deprecate existing Mailbox servers

To assist in this transition, LDAP servers are backward compatible which means that older Proxy, MTA and Mailbox servers can run against an updated LDAP. There are many different scenarios that can occur and it’s always recommended to identify what is best for your environment before starting any upgrade.

The migration of NG data to Daffodil (v10) is only supported from Zimbra 8.8.15 and 9.0.0 versions running the latest patch release.
If you’re using Zimbra Connect or Chat, please note that migration of these modules is not currently supported. Please contact Zimbra Support or Sales for guidance.

This document will provide details about the NG migration tool and how to migrate NG configuration. Customers who are running without NG modules can proceed with these steps but will skip all NG migration steps.

Pre-Requisites And Networking Considerations

To support a rolling upgrade migration, new systems will need to be created. When creating new systems, you will need to use a new hostname and build the system to meet your current and future needs. Also, networking needs to be taken into consideration. Network speed and reliability are critical between these systems, especially if the migration is between data centers or different locations. If there is a firewall between these systems, you will need to ensure that these servers can communicate on HTTP/S, SSH, LMTP, SMTP, LDAP, etc. For more information about all intra-node communication ports, please see Default Ports Used by Zimbra.

When developing this document, we made some assumptions that individuals have a basic understanding of networking, troubleshooting, and how to set up a Zimbra instance. The document will assume a standard installation is being used but before executing the steps on a production system, it is recommended to review in detail, test within a test environment, and ensure there is a backup before starting the migration.

For guidance on which version being discussed, we will use the following examples across the guide:

  • 8.8.15/9.0.0 Nodes:

    • LDAP - #.old.ldap.com

    • Proxy - #.old.proxy.com

    • MTA - #.old.mta.com

    • Mailbox - #.old.mailbox.com

  • Daffodil (v10) Nodes:

    • LDAP - #.new.ldap.com

    • Proxy - #.new.proxy.com

    • MTA - #.new.mta.com

    • Mailbox - #.new.mailbox.com

LDAP Upgrade

In this section, we will be using the MMR replication to replace and upgrade the current ldap servers to Daffodil. Steps will be provided to enable and create a new MMR instance, add new MMR and slave/replica servers to an existing cluster, then implement the Daffodil migration. Once completed, the LDAP servers will be running Daffodil and all other services will be running the original version.

Enabling MMR

Environments running a single master LDAP with or without slave/replicas will need to enable MMR using the following steps, if MMR is enabled, this section can be skipped.

Upgrading LDAP will not affect the NG modules since the NG modules are installed on the Mailbox server and zimlet attributes for the NG modules will still exist after the LDAP upgrade.

Before starting this process, new systems using an OS version that is supported by the current production version Daffodil (v10) and Daffodil needs to be created. This system should have the required environmental configuration (CPU, Memory, etc) to support current and future growth. Operating system (OS) are server-specific and does not effect application level functionality and OS provider and version can differ on each server.

The screen shots are examples of the Zimbra Collaboration installation script. The actual script may be different.

Before enabling MMR, you will need to obtain existing passwords from #.old.ldap.com to use during the installation on #.new.ldap.com. Please save these passwords as we will need them when configuring LDAP MMR setup.

  • As a zimbra user, execute the following command:

$ zmlocalconfig -s ldap_amavis_password ldap_bes_searcher_password ldap_nginx_password ldap_postfix_password ldap_replication_password ldap_root_password zimbra_ldap_password

A common issue is the LDAP port being blocked. Please ensure port 389 is accessible between servers.

Enabling MMR

Once you have the #.new.ldap.com server setup and the required password information, it’s time to enable MMR on your current production system which requires a restart of the LDAP service.

  • Maintenance window - 5 minutes approx.

  • As a zimbra user, execute the following commands on the current production server - #.old.ldap.com:

 $ /opt/zimbra/libexec/zmldapenable-mmr -s 1 -m ldap://new.ldap.com:389/
 zmcontrol restart

Installing new LDAP and syncing LDAP replication

In this section:

  • New MMR and slave/replica systems using the latest OS will be added to the MMR cluster.

  • All ldap traffic will be pointed to the new LDAP servers.

  • Existing LDAP servers will be disabled and removed.

  • New LDAP servers will be upgraded to Daffodil.

For new MMR instances, once the first steps been completed, there will be three servers within the cluster (Original and two new servers) For existing MMR cluster, the server count should double (X Original + X new servers). Lastly, new slave/replica replacement servers will be added matching existing count.

On the #.new.ldap.com servers, download the current production version of ZCS that matches your OS version. Please refer to the Download Page to get the ZCS version build. Once the download has been completed, untar and run ./install.sh.

  • Packages to be installed:

    • zimbra-ldap

    • zimbra-snmp

./install.sh

The following is an overview of a typical installation:

Do you agree with the terms of the software license agreement? [N] Y

Install zimbra-ldap [Y] Y
Install zimbra-logger [Y] N
Install zimbra-mta [Y] N
Install zimbra-dnscache [Y] N
Install zimbra-snmp [Y] Y
Install zimbra-store [Y] N
Install zimbra-apache [Y] N
Install zimbra-spell [Y] N
Install zimbra-convertd [Y] N
Install zimbra-memcached [Y] N
Install zimbra-proxy [Y] N
Install zimbra-archiving [N]
Install zimbra-drive [Y] N
Install zimbra-imapd (BETA - for evaluation only) [N]
Install zimbra-network-modules-ng [Y] N
Install zimbra-chat [Y] N

The installer will enter into a configuration section where you will need to configure this new instance to the production server. This process does not affect your current production environment.

  • Select 1 - Common Configuration, then configure options 2 and 4. Once entered, the system will verify if the #.new.ldap.com can connect to the #.old.ldap.com.

1) Common Configuration:
        2) Ldap master host: <old.ldap.com>
        4) Ldap Admin password: <ldap_root_password>
        Select, or 'r' for previous menu [r] r
  • The system will verify the connection between the two LDAPs and will return with no ** if successful.

  • Select r to return then select 2 zimbra-ldap.

2 zimbra-ldap.

1) Status:                                  Enabled
2) Create Domain:                           yes
3) Domain to create:                        Domain.com
4) Ldap replication type:                   replica
5) Ldap root password:                      set
    ** 6) Ldap replication password:               Not Verified
    ** 7) Ldap postfix password:                   Not Verified
    ** 8) Ldap amavis password:                    Not Verified
    ** 9) Ldap nginx password:                     Not Verified
  • Select 4 Ldap replication type: and change to mmr:

Please enter the LDAP replication type (replica, mmr) [replica] mmr

Note: For slave/replica installations, do not update this section.

  • Then update the password for all other components using the password obtained from the production server #.old.ldap.com:

   ** 6) Ldap replication password:               Not Verified
   ** 7) Ldap postfix password:                   Not Verified
   ** 8) Ldap amavis password:                    Not Verified
   ** 9) Ldap nginx password:                     Not Verified

Once the installation has been completed, replication can be checked by updating an attribute for a test user, on #.old.ldap.com, then verifying the change on #.new.ldap.com. Then restore the attribute back to the original configuration on #.new.ldap.com then verify the change on the #.old.ldap.com.

  • Obtain current configuration:

zmprov ga <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries
#name test-user@domain.com
zimbraZimletUserPropertiesMaxNumEntries: 150
  • Update configuration on #.old.ldap.com then verify the change on #.new.ldap.com.

    • On #.old.ldap.com, execute this command as a zimbra user:

zmprov ma <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries 160
  • On #.new.ldap.com, execute this command as a zimbra user:

zmprov -l ga <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries
  • Restore configuration on #.new.ldap.com then verify the change on #.old.ldap.com.

    • On #.new.ldap.com, execute this command as a zimbra user:

zmprov ma <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries 150
  • On #.old.ldap.com, execute this command as a zimbra user:

zmprov -l ga <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries
-l is required for the call to obtain the attribute from the configured LDAP. If -l is not used, the server will obtain the attribute from the cache of the server.

Repeate this section on all new LDAP MMR and replicate

Redirect LDAP traffic and Upgrade new servers to Daffodil

This stage consists of two steps which the first step requires downtime:

Step One

  1. Configure all production servers (New LDAP’s, MTA, Proxy, Mailbox, etc) to use the new LDAP services.

  2. Upgrade the #.new.ldap.com servers to Zimbra Collaboration Daffodil (v10).

To remove existing LDAP servers from the pool of MMR replica update ldap_master_url and ldap_url on all of your systems including the #.new.ldap.com and excluding #.old.ldap.com.

Note: At this time it is important to take advantage of configuring the cluster for failover. What this means is if the first master or replica listed in the server configuration goes down, then the second master or replica will be used. This will support an upgrade of your LDAP with no downtime. For larger clusters, it is recommended to stagger servers to different masters or replicas to distribute traffic and load. It is also recommended to point read services like Proxy & MTA to replicas and write services like Mailbox to master to improve LDAP performance. The following is an example:

Server A

su - zimbra
zmlocalconfig -e ldap_master_url="ldap://1new.ldap.com:389 ldap://2new.ldap.com:389"
zmlocalconfig -e ldap_url="ldap://1new.ldap.com:389 ldap://2new.ldap.com:389"

Server B

su - zimbra
zmlocalconfig -e ldap_master_url="ldap://2new.ldap.com:389 ldap://1new.ldap.com:389"
zmlocalconfig -e ldap_url="ldap://2new.ldap.com:389 ldap://1new.ldap.com:389"
  • Restart zimbra services on both servers:

zmcontrol restart

Once the all of the original LDAP servers have been removed from production, you can uninstall LDAP from these systems by running:

/opt/zimbra/libexe/installer/install.sh -u

By uninstalling each LDAP instance will remove the instance from the cluster.

If the following error occurs when starting the servers on either system, it means there is an issue within the DNS, hostname or zmhostname does not match or a password within zmlocalconfig is not set correctly. Also, if the #.old.ldap.com LDAP is not it will cause this error.

Failed to start slapd. Attempting debug start to determine error.
 6425fca4 daemon: bind(7) failed errno=99 (Cannot assign requested address)
 6425fca4 slap_open_listener: failed on ldap://hostname:389

Step Two

It is time to upgrade all of your #.new.ldap.com servers to Daffodil (v10). All #.new.ldap.com servers need to be upgraded within same maintenance window but one at a time. This will allow you to upgrade the LDAP’s without effecting current production, a partial upgrade will lead to schema mismatch and we recommend scheduling a Maintenance window for 15 minutes for each LDAP server as a pre-cautionary measure. The following steps will need to be performed on each ldap server.

  1. Download the Daffodil (v10) package onto #.new.ldap.com and run install.sh script.

    Do you wish to upgrade? [Y] Y
    Install zimbra-archiving [N] N
    Install zimbra-onlyoffice [N] N
    Install chat and video features [N] N
    Install zimbra-logger[Y] N
    Install zimbra-mta[Y] N
    Install zimbra-dnscache[Y] N
    Install zimbra-store[Y] N
    Install zimbra-apache[Y] N
    Install zimbra-spell[Y] N
    Install zimbra-convertd[Y] N
    Install zimbra-memcached[Y] N
    Install zimbra-proxy[Y] N
    Install zimbra-onlyoffice[Y] N
    Install zimbra-license-tools[Y] N
    Install zimbra-license-extension[Y] N
    Install zimbra-network-store[Y] N
    Install zimbra-modern-ui[Y] N
    Install zimbra-modern-zimlets[Y] N
    Install zimbra-zimlet-document-editor[Y] N
    Install zimbra-zimlet-classic-document-editor[Y] N
    Install zimbra-patch[Y] N
    Install zimbra-mta-patch[Y] N
    Install zimbra-proxy-patch[Y] N
    Install zimbra-rabbitmq-server[Y] N
    Installing:
    zimbra-core
    zimbra-ldap
    zimbra-snmp
    zimbra-ldap-patch
    The system will be modified. Continue? [N] Y
  2. If there are any configuration issues needed to be updated, the installer script list the issue using '**'. This will differ on each installation but most of the time it is caused by a password issue which will need to be obtained from #.old.ldap.com.

    zimbra-ldap: Enabled
    +Create Domain: no
    +Ldap root password: set
    +Ldap replication password: set
    +Ldap postfix password: set
    +Ldap amavis password: set
    +Ldap nginx password: set
    ******* +Ldap Bes Searcher password: Not Verified
  3. After providing the required information, complete the upgrade.

Status: All LDAP servers MMR and replica’s are running Daffodil and all other systems are running the originals version {8815 or 900}

Installing Proxy service on the new server

Now it is time to replace existing proxy servers with the same number of Daffodil servers. This is another example where an in-place upgrade can occur if the current OS is supported by Daffodil. Before starting the installation, the targeted ldap hosts and passwords will need to be obtained. The only package need to be installed is zimbra.proxy. Optional packages are zimbra-snmp and zimbra-memcached. For zimbra-memcached can be installed on one or more ldap servers.

During the installation process, all new proxy servers will be added to the cluster but no traffic will be delivered to them until production traffic is redirected. It is recommended to install one proxy at a time, perform your testing on each new proxy, then forward production traffic to the new proxy servers while removing all of the old.proxy.com from the flow. Once you have confirm there is no issue then you can remove the #.old.proxy.com servers from the cluster.

  1. On the #.new.proxy.com servers, download the Daffodil (v10) installer which can be obtained from the download page. Once the download has been completed, untar and run ./install.sh.

    • Packages to be installed:

      • zimbra-proxy

      • zimbra-memcached

        The other packages should be marked n.

        If SNMP is used, the zimbra-snmp package must also be installed.
  2. Execute the installer:

    ./install.sh
  3. The following is an overview of a typical installation:

    Do you agree with the terms of the software license agreement? [N] Y
    
    Select the packages to install
    
    Install zimbra-ldap [Y] N
    Install zimbra-logger [Y] N
    Install zimbra-mta [Y] N
    Install zimbra-dnscache [N] N
    Install zimbra-snmp [Y] N
    Install zimbra-store [Y] N
    Install zimbra-apache [Y] N
    Install zimbra-spell [Y] N
    Install zimbra-convertd [N] N
    Install zimbra-memcached [N] Y
    Install zimbra-proxy [N] Y
    Install zimbra-archiving [N] N
    Installing:
        zimbra-memcached
        zimbra-proxy
    This system will be modified. Continue [N] Y
    Configuration section
  4. Type Y, and press Enter to install the selected packages.

  5. The Main menu displays. Type 1 and press Enter to go to the Common Configuration menu.

    The mailbox server hostname is displayed. You must change the LDAP master host name and password to be the values configured on the LDAP server.

    • Type 2, press Enter, and type the LDAP host name. (#.new.ldap.com, in this example.)

    • Type 4, press Enter, and type the LDAP password.

      After you set these values, the server immediately contacts the LDAP server. If it cannot contact the server, you cannot proceed.

    • Type 7 to set the correct time zone

  6. Type r to return to the Main menu.

  7. Type 2 to select zimbra-proxy.

    Main menu
    
    1) Common Configuration:
            +Hostname:                              localhost
            +Ldap master host:                      new.ldap.com
            +Ldap port:                             389
            +Ldap Admin password:                   set
            +LDAP Base DN:                          cn=zimbra
            +Store ephemeral attributes outside Ldap: no
            +Secure interprocess communications:    yes
            +TimeZone:                              (GMT-08.00) Pacific Time (US & Canada)
            +IP Mode:                               ipv4
            +Default SSL digest:                    sha256
    
    2) zimbra-proxy:                              Enabled
            +Enable POP/IMAP Proxy:                 TRUE
            +IMAP server port:                      7143
            +IMAP server SSL port:                  7993
            +IMAP proxy port:                       143
            +IMAP SSL proxy port:                   993
            +POP server port:                       7110
            +POP server SSL port:                   7995
            +POP proxy port:                        110
            +POP SSL proxy port:                    995
    ******* +Bind password for nginx ldap user:     Not Verified
            +Enable HTTP[S] Proxy:                  TRUE
          	+Web server HTTP port:				  	8080
    		+Web server HTTPS port:				  	8443
    		+HTTP proxy port: 					  	80
    		+HTTPS proxy port:					  	443
    		+Proxy server mode:					  	https
    
    3) Enable default backup schedule:			  	yes
    s) Save config to file
    x) Expand menu
    q) Quit
    
    Select, or 'r' for previous menu [r] 2
  8. The Proxy Configuration menu displays. You can modify any of the values.

    The Bind password for Nginx ldap user is configured when the LDAP server was installed. This is set when the MTA connected to the LDAP server. This is not used unless the Kerberos5 authenticating mechanism is enabled.

    Setting the password even though GSSAPI auth/proxy is not set up does not cause any issues.
    Proxy configuration
    
       1) Status:                                  Enabled
       2) Enable POP/IMAP Proxy:                   TRUE
       3) IMAP server port:                        7143
       4) IMAP server SSL port:                    7993
       5) IMAP proxy port:                         143
       6) IMAP SSL proxy port:                     993
       7) POP server port:                         7110
       8) POP server SSL port:                     7995
       9) POP proxy port:                          110
      10) POP SSL proxy port:                      995
      11) Bind password for nginx ldap user:       set
      12) Enable HTTP[S] Proxy:                    TRUE
      13) Web server HTTP port:                    8080
      14) Web server HTTPS port:                   8443
      15) HTTP proxy port:                         80
      16) HTTPS proxy port:                        443
      17) Proxy server mode:                       https
  9. Type r to return to the Main menu.

  10. When the proxy server is configured, return to the Main menu and type a to apply the configuration changes. Press Enter to save the configuration data.

  11. When Save Configuration data to a file appears, press Enter.

  12. The next request asks where to save the files. To accept the default, press Enter. To save the files to another directory, enter the directory and then press Enter.

  13. When The system will be modified - continue? appears, type y and press Enter.

  14. When Installation complete - press return to exit displays, press Enter.

The installation of the proxy server is complete and repeat to configure the remaining proxy server. Test proxy configuration by accessing the hostname of one or more of the #.new.proxy.com servers and log into and test account functionality.

Redirect Proxy Traffic

At this time all proxy traffic is passing through the #.old.proxy.com servers and #.new.proxy.com servers are configured but are idle. After completing your testing, Add the #.new.proxy.com and remove #.old.proxy.com from the production traffic.

Remove #.old.proxy.com servers from cluster

Once all traffic is successfully passing through your #.new.proxy.com servers, uninstall #.old.proxy.com servers from the cluster by running the following on each of the #.old.proxy.com servers.

/opt/zimbra/libexec/installer/install.sh -u

Note: this command will remove all services on the server that the command is ran on, please verify there are no other Zimbra services on the system before performing the un-installation.

Installing MTA service on the new server

Like Proxy, setting up new MTA’s consist of the same steps, add and configure new servers using daffodil, test, direct production traffic to the MTA’s then uninstall the #.old.mta.com servers. To configure new MTA’s to the cluster, the master or replica hostname and password are needed.

On the #.new.mta.com server, download the Daffodil (v10) installer which can be obtained from the download page. Once the download has been completed, untar and run ./install.sh.

  • Packages to be installed:

    • zimbra-mta

    • zimbra-dnscache

      The other packages should be marked n.

      If SNMP is used, the zimbra-snmp package must also be installed.
      1. Execute the installer:

        ./install.sh
      2. The following is an overview of a typical installation:

        Select the packages to install
        
        Install zimbra-ldap [Y] n
        
        Install zimbra-logger [Y] n
        
        Install zimbra-mta [Y] Y
        
        Install zimbra-dnscache [Y] Y
        
        Install zimbra-snmp [Y] n
        
        Install zimbra-store [Y] n
        
        Install zimbra-apache [Y] n
        
        Install zimbra-spell [Y] n
        
        Install zimbra-memcached [Y] n
        
        Install zimbra-proxy [Y] n
        Checking required space for zimbra-core
        
        Installing:
            zimbra-core
            zimbra-mta
            zimbra-dnscache
        
        The system will be modified.  Continue? [N] y
        Installing packages
      3. Type Y, and press Enter to modify the system. The selected packages are installed on the server.

      4. The Main menu displays the default entries for the Zimbra component you are installing. To expand the menu to see the configuration values, type x and press Enter.

      5. The main menu expands to display configuration details for the package being installed.

        Values that require further configuration are marked with asterisks (*).

        To navigate the Main menu, select the menu item to change. You can modify any of the values. See the section Main Menu options for a description of the Main menu.

        Main menu
        
           1) Common Configuration:
                +Hostname:                             new.mta.com
         +Ldap master host:                     UNSET
                +Ldap port:                            389
         +Ldap Admin password:                  UNSET
                +LDAP Base DN:                         cn=zimbra
                +Store ephemeral attributes outside Ldap: no
                +Secure interprocess communications:   yes
                +TimeZone:                             Africa/Monrovia
                +IP Mode:                              ipv4
                +Default SSL digest:                   sha256
        
           2) zimbra-mta:                              Enabled
                +Enable Spamassassin:                  yes
                +Enable Clam AV:                       yes
                +Enable OpenDKIM:                      yes
                +Notification address for AV alerts:   admin@example.domain.com
         +Bind password for postfix ldap user:  UNSET
         +Bind password for amavis ldap user:   UNSET
        
           3) zimbra-dnscache:                         Enabled
           s) Save config to file
           x) Expand menu
           q) Quit
        
        Address unconfigured (**) items  (? - help)
      6. Type 1 to display the Common Configuration submenu.

        Common configuration
        
           1) Hostname:                                new.mta.com
         2) Ldap master host:                        UNSET
           3) Ldap port:                               389
         4) Ldap Admin password:                     UNSET
           5) LDAP Base DN:                            cn=zimbra
           6) Store ephemeral attributes outside Ldap: no
           7) Secure interprocess communications:      yes
           8) TimeZone:                                Africa/Monrovia
           9) IP Mode:                                 ipv4
          10) Default SSL digest:                      sha256

        The mta server hostname is displayed.

        You must change the LDAP master host name and password to be the values configured on the LDAP server.
        • Type 2, press Enter, and type the LDAP host name. (#.new.ldap.com in this example.)

        • Type 4, press Enter, and type the LDAP password.
          To obtain the LDAP password, you will need to log on to the LDAP server as the zimbra user, and run the following command:

        zmlocalconfig -s zimbra_ldap_password

        After you set these values, the server immediately contacts the LDAP server. If it cannot contact the server, you cannot proceed.

      7. Type 8 to set the correct time zone.

        1 Africa/Algiers
        ~
        94 Europe/London
        ~
        109 Pacific/Tongatapu
        110 UTC
        Enter the number for the local timezone: [110] 94
      8. Type r to return to the Main menu.

      9. Type 2 to got to the Mta configuration menu.

        Mta configuration
        
           1) Status:                                  Enabled
           2) Enable Spamassassin:                     yes
           3) Enable Clam AV:                          yes
           4) Enable OpenDKIM:                         yes
           5) Notification address for AV alerts:      admin@example.domain.com
         6) Bind password for postfix ldap user:     UNSET
         7) Bind password for amavis ldap user:      UNSET
        
        Select, or 'r' for previous menu [r]
      10. You can change the Notification address for AV alerts. This should be an address on the domain, such as the admin address. (admin@example.com)

        If you enter an address other than the admin address, you must provision an account with that address after the installation is complete.
      11. Select the menu number for Bind password for postfix ldap user.
        You must use the same value for this as is configured on the LDAP master server.

      12. Select the menu number for Bind password for amavis ldap user.
        You must use the same value for this as is configured on the LDAP master server.

      13. Type r to return to the Main menu.

      14. When the MTA server is configured, return to the Main menu and type a to apply the configuration changes.
        Press Enter to save the configuration data.

      15. When Save configuration data to file appears, type Yes and press Enter.

      16. The next request asks where to save the file. To accept the default, press Enter. To save the files to another directory, enter the directory and then press Enter.

      17. When The system will be modified - continue? appears, type Yes and press Enter.

        The server is modified. Installing all the components and configuring the MTA server can take a few minutes. This can include setting passwords, setting ports, setting time zone preferences, and starting the server, among other processes.

      18. When Installation complete - press return to exit displays, press Enter.

The installation of the MTA server is complete, repeat the steps until all Daffodil servers have been created..

Redirect MTA Traffic

After performing testing, it is time redirect the MTA traffic from the #.old.mta.com’s to the #.new.mta.com’s.

  • As a zimbra user, execute this command on #.old.mta.com:

su - zimbra
zmprov ms old.mailbox.com zimbraSmtpHostname new.mta.com

Remove #.old.mta.com servers from cluster

Once all traffic is successfully passing through your #.new.mta.com servers, uninstall #.old.mta.com servers from the cluster by running the following on each #.old.mta.com server.

/opt/zimbra/libexec/installer/install.sh -u
This command will remove all services on the server that the command is ran on, please verify there are no other Zimbra services on the system before performing the un-install.

Installing Mailbox service on the new server

At this time the cluster will be running Daffodil LDAP, Proxy, MTA and #.old.mailbox.com servers. The next step is to add Daffodil mailbox servers to the cluster. It is recommended to match the same number of mailbox servers that is currently being used within the cluster. For clusters running archive, since archive servers are mailbox servers which house archive accounts, you will need to follow the same steps in this section.

  1. On the #.new.mailbox.com server, download the Daffodil (v10) installer which can be obtained from the download page. Once the download has been completed, untar and run ./install.sh using the license file.

    • Packages to be installed:

      • zimbra-snmp

      • zimbra-store

      • zimbra-apache

      • zimbra-spell

      • zimbra-convertd

    The other packages should be marked n.

    + NOTE: If SNMP and archiving are being used, zimbra-archiving and zimbra-snmp packages need to be installed.

  2. Type y and press Enter to install the zimbra-logger package (optional and only on one mail server)

  3. Execute the installer:

    ./install.sh -l /path/license.xml
  4. The following is an overview of a typical installation:

    Do you agree with the terms of the software license agreement? [N] Y
    
    Install zimbra-ldap [Y] N
    
    Install zimbra-logger [Y] Y
    
    Install zimbra-mta [Y] N
    
    Install zimbra-dnscache [Y] N
    
    Install zimbra-snmp [Y] Y
    
    Install zimbra-store [Y] Y
    
    Install zimbra-apache [Y] Y
    
    Install zimbra-spell [Y] Y
    
    Install zimbra-convertd [Y] Y
    
    Install zimbra-memcached [Y] N
    
    Install zimbra-proxy [Y] N
    
    Install zimbra-archiving [N] N
    
    
    WARNING
    
    Checking required space for zimbra-core
    Checking space for zimbra-store
    Checking required packages for zimbra-store
         FOUND: libreoffice-1:4.2.8-0ubuntu4
    zimbra-store package check complete.
    
    Installing:
        zimbra-core
        zimbra-logger
        zimbra-snmp
        zimbra-store
        zimbra-apache
        zimbra-spell
        zimbra-modern-ui
        zimbra-convertd
    
    The system will be modified.  Continue? [N]
  5. Type Y, and press Enter to modify the system. The selected packages are installed on the server.

    Once the package are installed a Main Menu page will show default settings with many configurations showing incorrect or need to be updated. Many of these issues will be resolved once the new server has been configured to the LDAP.

    Values that require further configuration are marked with asterisks (*).

    To configure the new server to the LDAP, the LDAP master hostname and password will need to be obtain. Select option 1 "Common Configuration", then option 2 "Ldap master host" and option 4 "Ldap Admin password" in this order. Once the password is configured, the server will connect to the LDAP and update the majority of the configuration. If the sync fails, there will be no change to the existing configuration and you will need to review why the server was unable to connect to the LDAP.

    Main menu
       1) Common Configuration:
            +Hostname:                             new.mailbox.com
    ******* +Ldap master host:                     UNSET
            +Ldap port:                            389
    ******* +Ldap Admin password:                  UNSET
            +LDAP Base DN:                         cn=zimbra
            +Store ephemeral attributes outside Ldap: no
            +Secure interprocess communications:   yes
            +TimeZone:                             UTC
            +IP Mode:                              ipv4
            +Default SSL digest:                   sha256
Common configuration

   1) Hostname:                                aeng-test1.zimbrasupportlab.com
** 2) Ldap master host:                        UNSET
   3) Ldap port:                               389
** 4) Ldap Admin password:                     UNSET
   5) LDAP Base DN:                            cn=zimbra
   6) Store ephemeral attributes outside Ldap: no
   7) Secure interprocess communications:      yes
   8) TimeZone:                                UTC
   9) IP Mode:                                 ipv4
  10) Default SSL digest:                      sha256

Once the server has been configured to the Master LDAP, in the majority of the installations, the admin password and the SMTP host will need to be added. For the Admin password, the existing password can be used.

   3) zimbra-store:                            Enabled
        +Create Admin User:                    yes
        +Admin user to create:                 admin@zimbrasystems.com
******* +Admin Password                        UNSET
        +Enable automated spam training:       yes
******* +SMTP host:                            UNSET

Once all of the configuration has been resolved press 'a' to apply the changed.

Main menu

   1) Common Configuration:
   2) zimbra-snmp:                             Enabled
   3) zimbra-store:                            Enabled
   4) zimbra-spell:                            Enabled
   5) zimbra-convertd:                         Enabled
   6) Default Class of Service Configuration:
   7) Enable default backup schedule:          yes
   s) Save config to file
   x) Expand menu
   q) Quit

*** CONFIGURATION COMPLETE - press 'a' to apply
Select from menu, or press 'a' to apply config (? - help)

Warning: The installer script will configure the new mailbox server in to the Proxy. It is recommended to remove the new mailbox server from the proxy list until the mailbox server is ready to go live.

Install your Signed certificate

Copy the files within /opt/zimbra/ssl/zimbra/commercial/ from your #.old.mailbox.com to the #.new.mailbox.com.

Ensure the permissions are set to zimbra on all files.

As root user, execute this command on #.new.mailbox.com:

/opt/zimbra/bin/zmcertmgr deploycrt comm commercial.crt commercial_ca.crt

Repeat these steps until all new mailbox servers have been added.

Final Set-Up

After the Daffodil (v10) servers are configured in a multi-node configuration, the following functions must be configured before proceeding to account and data migration:

  • In order for remote management and postfix queue management, the ssh keys must be manually populated on each server. See Update the SSH Keys.

  • If logger is installed, set up the syslog configuration files on each server to enable server statistics to display on the administration console, and then enable the logger monitor host. The server statistics includes information about the message count, message volume, and anti-spam and anti-virus activity. See Enabling Server Statistics Display.

  • Daffodil (v10) ships a default zimbra user with a disabled password. {product-abbrev} requires access to this account via ssh public key authentication. On most operating systems this combination is okay, but if you have modified spam rules to disallow any ssh access to disabled accounts then you must define a password for the zimbra UNIX account. This will allow ssh key authentication for checking remote queues. See Mail queue monitoring.

Update the SSH Keys

To configure ssh access to data between all the servers, an ssh key will need to be generated on each server, then each server needs to sync the other servers ssh key. To create ssh keys run zmsshkeygen as a zimbra user on all the servers:

zmsshkeygen

Once the keys are generated, sync the keys by running zmupdateauthkeys on both servers:

zmupdateauthkeys

Key updates take effect immediately and do not necessitate a server restart. Please refer to guide for more information.

Enabling Server Statistics Display

In order for the server statistics to display on the administration console, the syslog configuration files must be modified.

Daffodil (v10) supports the default syslog of a supported operating system. Depending on your operating system, the steps contained in this section might not be correct. See your operating system documentation for specific information about how to enable syslog.
  1. On each server, as root, type /opt/zimbra/libexec/zmsyslogsetup. This enables the server to display statistics.

  2. On the logger monitor host, you must enable either syslog or rsyslog to log statistics from remote machines:

    For syslog:

    1. Edit the /etc/sysconfig/syslog file, add -r to the SYSLOGD_OPTIONS setting, SYSLOGD_options="-r -m 0".

    2. Stop the syslog daemon. Type /etc/init.d/syslog stop.

    3. Start the syslog daemon. Type /etc/init.d/syslog start.

For syslog on Debian or Ubuntu:

  1. Edit the /etc/default/syslogd file, add -r to the SYSLOGD_OPTIONS setting, SYSLOGD_options="-r -m 0"

  2. Stop the syslog daemon. Type /etc/init.d/sysklogd stop.

  3. Start the syslog daemon. Type /etc/init.d/sysklogd start.

For rsyslog:

  1. Uncomment the following lines in /etc/rsyslog.conf

    $modload imudp
    $UDPServerRun 514
  2. Restart rsyslog

For rsyslog on RHEL or CentOS:

  1. Uncomment the following lines in /etc/rsyslog.conf.

    # Provides UDP syslog reception
    #$ModLoad imudp
    #$UDPServerRun 514
    
    # Provides TCP syslog reception
    #$ModLoad imtcp
    #$InputTCPServerRun 514

Spam/Ham Training on MTA servers

New installs of {product-abbrev} limit spam/ham training to the first MTA installed. If you uninstall or move this MTA, you will need to enable spam/ham training on another MTA, as one host should have this enabled to run zmtrainsa --cleanup. To do this, set zmlocalconfig -e zmtrainsa_cleanup_host=TRUE.

Installing NG Migration tool and Exporting NG Data

Customers not using NG modules can skip this step.

The NG migration utility was developed to migrate NG-dependent configuration and data to the Daffodil (v10) systems. The utility will need to be installed on all mailbox servers - #.old.mailbox.com and #.new.mailbox.com to support the export and import of the NG data. Data export is only required for the components that are currently being used.

The admin user used in export/import command is the Global Admin on the server.
Execute all the data export and import commands from the Daffodil (v10) mailbox server.

Download and Installing Migration Tool

The migration utility package is available on Zimbra’s public repository.

Following are the steps to download and install the migration utility on Daffodil (v10) mailbox server.

  • On RHEL/CentOS system, execute as root:

 yum clean metadata
 yum check-update
 yum install zimbra-modules-porter
  • On Ubuntu system, execute as root:

 apt-get update
 apt-get install zimbra-modules-porter

After successful installation, a command zmmodulesport will be available on the server.

Migrating HSM Configuration

Customers not using HSM or using Non-S3 volumes can skip this step.

Setting up volumes is critical and will be different for each customer, but this is also a time when you can reconsider your volume configuration.

From Daffodil 10.0.5 Patch onwards, support for Unified Storage has been added in the Storage Management module. Unified Storage allows better data management by storing the data from the multiple mailbox servers under the same directory structure in a single S3 bucket.

When using Unified Storage, you can also do a blobless migration if you are using NG HSM’s Centralized Storage feature. In this case, the mail data is not required to be migrated from the S3 bucket and continue to be present at the same location.

Please refer to admin-guide for more details on the feature.

zmmodulesport tool provides the ability to copy your HSM configuration within #.old.mailbox.com into the #.new.mailbox.com and based on storage type, each migration will be different.

Following are the details of the attributes we need to use when migrating the data and the behavior when they are set to TRUE:

  • zimbraMailboxMoveSkipBlobs = Blob data will be excluded in the move.

  • zimbraMailboxMoveSkipHsmBlobs = Primary store blobs will be moved. The HSM (Secondary) blobs will be skipped.

Depending upon your Primary and Secondary storage setup, the steps to migrate the HSM data and accounts will vary. Please refer to the following guidelines depending upon your storage setup:

Unified Storage - Primary Storage - Internal | Secondary Storage - External

Following are the details of this setup:

  • You are using NG HSM’s Centralized Storage feature.

  • The Primary Storage is setup on Internal storage.

  • The Secondary storage is setup on External S3 storage.

You will have to set the zimbraMailboxMoveSkipBlobs attribute to FALSE and zimbraMailboxMoveSkipHsmBlobs attribute to TRUE on the global config level before initiating the account migration.

zmprov mcf zimbraMailboxMoveSkipBlobs FALSE
zmprov mcf zimbraMailboxMoveSkipHsmBlobs TRUE

This configuration will move primary data but all data within the S3 volume will be skipped.

Unified Storage - Primary and Secondary Storage - External

Following are the details of this setup:

  • You are using NG HSM’s Centralized Storage feature.

  • The Primary and Secondary Storage is setup on External S3 storage.

You will have to set attribute zimbraMailboxMoveSkipBlobs TRUE on the global config level before initiating the account migration.

zmprov mcf zimbraMailboxMoveSkipBlobs TRUE

This configuration will skip moving primary and secondary storage data.

Primary and Index Storage - Internal | Secondary Storage - External

Following are the details of this setup:

  • You are not using NG HSM’s Centralized Storage feature.

  • The Primary and Index Storage is setup on Internal storage.

  • The Secondary storage is setup on External S3 storage.

You will have to set zimbraMailboxMoveSkipHsmBlobs to TRUE at the global config level by running:

zmprov mcf zimbraMailboxMoveSkipHsmBlobs TRUE

This configuration will move primary and index data but all data within the S3 volume will be skipped.

Before moving the data, the volume configuration will need to be migrated to the #.new.mailbox.com server using zmmodulesport. This functionality allows you to choose to use existing volumes or move your blob data to new volumes.

Export HSM data

To support blobless move for local object-store configuration, it is required to export HSM data from a #.old.mailbox.com to a targeted {10-mailbox} server.

  • As a zimbra user, execute this command on #.new.mailbox.com:

su - zimbra
zmmodulesport system export --modules=hsm --filename=hsm-data --server=old.mailbox.com --username=admin@old.mailbox.com --password=admin_passwd >> /opt/zimbra/log/hsm-export.log

A file hsm-data.tgz will be created within /opt/zimbra/tmp/modules/hsm/.

Import HSM data
  • As a zimbra user, execute this command on #.new.mailbox.com:

su - zimbra
zmmodulesport system import --modules=hsm --filename=hsm-data --server=new.mailbox.com --username=admin@new.mailbox.com --password=admin_passwd >> /opt/zimbra/log/hsm-import.log
Using zmmodulesport will overwrite the Manage Volumes on the #.new.mailbox.com using the setup for the #.old.mailbox.com server. To redesign your new Daffodil volume, we recommend importing the #.old.mailbox.com setup, then modifying the configuration to meet your current needs. To prevent data loss, it is not recommended to delete or change configuration on volumes that currently contain data.

Migrating Backup & Restore Configuration

The migration utility only provides the information if the Backup & Restore feature is enabled/disabled for the COS.

Export Backup data
  • As a zimbra user, execute this command on #.old.mailbox.com:

su - zimbra
zmmodulesport system export --modules=backup --filename=backup-data --server=old.mailbox.com --username=admin@old.mailbox.com --password=admin_passwd >> /opt/zimbra/log/br-export.log

A file backup-data.tgz will be created within /opt/zimbra/tmp/modules/backup/.

Import Backup data
The Backup & Restore configuration cannot be imported through the utility. You will have to manually update the configuration for the domains/users on your system.
Daffodil (v10) and NG backups contain different format and you will not be able to directly use the Daffodil (v10) Backup & Restore feature to restore your NG backups. Also, if the NG backup is used for anything other than disaster recovery, we recommend copying the NG backup to an archive location. Zimbra has created a tool to allow the restoration of message data for auditing and recovery purposes only.

To manually review the backup configuration:

  • Extract the exported backup-data.tgz file.

  • In the extracted directory, open the json file and check the COS having Enabled value.

  • Log into Daffodil (v10) Admin Console.

  • Go to Configure → Global Settings → Backup/Restore.

  • Under Select users for backup → Domain and COS, click on Add COS button and add COS for which backup was enabled in the json file.

  • Repeat the steps if there are multiple COS. Click on Save.

Once the backup configuration has been set, a full backup will be created for any new account that was migrated each night. Backups can manually execute once the targeted accounts are migrated for the day.

Migrating Delegated Admin configuration

Customers who are using NG Delegated Admin can migrate or manually configure admins within Daffodil Admin UI. Since migrating delegated admin configuration is an LDAP attribute, migration only needs to be done once for the full cluster.

Export Delegated Admin data
  • As a zimbra user, execute this command on #.old.mailbox.com:

su - zimbra
zmmodulesport system export --modules=admin --filename=admin-data --server=old.mailbox.com --username=admin@old.mailbox.com --password=admin_passwd >> /opt/zimbra/log/da-export.log

A file admin-data.tgz will be created within /opt/zimbra/tmp/modules/admin/.

Import DA data
  • As a zimbra user, execute this command on #.old.mailbox.com:

su - zimbra
zmmodulesport system import --modules=admin --filename=admin-data --server=new.mailbox.com --username=admin@new.mailbox.com --password=admin_passwd >> /opt/zimbra/log/da-export.log

Delegated admin permissions are only applied to the version in which it was created in. This means Delegated Admin has the ability to log into the admin UI within #.new.mailbox.com but will not have any rights until the permissions are migrated or manually set. Once permissions are set, Delegated Admin will need to log into #.old.mailbox.com to manage NG modules, or #.new.mailbox.com to manage Daffodil modules. Basic account information can be managed by either server but we recommend using the Admin UI of the server the account resides on.

Migrating Mobile data

If ABQ rules and share folder support for mobile are not being used, you can skip the migration section but please review the device migration section to ensure you are aware of behavior changes after the migration.

Mobile data consists of ABQ rules and share folder configuration for mobile devices and are LDAP attributes that can be migrated before the accounts.

Export Mobile data
  • As a zimbra user, execute this command on #.old.mailbox.com:

su - zimbra
zmmodulesport system export --modules=mobile --filename=mobile-data --server=old.mailbox.com --username=admin@old.mailbox.com --password=admin_passwd >> /opt/zimbra/log/mobile-export.log

A file mobile-data.tgz will be created within /opt/zimbra/tmp/modules/mobile/.

  • To export the Mobile data in batches, create a file accounts-file.txt which will have email addresses of the accounts separated by new line. Make sure to use a different file in the --filename parameter when exporting for multiple batches. Execute this command as a zimbra user.:

zmmodulesport system export --modules=mobile --accounts=/path/to/accounts-file.txt --filename=mobile-data1-batch1 --server=server.com --username=admin@domain.com --password=admin_passwd >> /opt/zimbra/log/mobile-export-batch1.log

This will create a file mobile-data1-batch1.tgz under /opt/zimbra/tmp/modules/mobile.

Device Migration

When moving accounts from #.old.mailbox.com to #.new.mailbox.com the active-sync module will be updated, which will cause the sync token to be reset. For most devices, it will recognize the account re-sync request and reload the account with no action by the user. Some older devices may require the profile to be recreated.

Some environments can see a spike in CPU and IO due to the amount of data being synced. To delay devices from syncing you can disable mobile sync for selected accounts prior to the mailbox move:

zmprov ma account@domain zimbraFeatureMobileSyncEnabled FALSE

Then once the accounts have been moved, you can enable mobile for these accounts by staggering when they are enabled to ensure that when the devices re-sync they do not affect your user’s experience.

This is just a recommendation and each environment is different. It is up to the system admin to choose the best method that meets their environment limitations.

Customization and Unit testing

Each environment is different but you need to configure your environment to support new.server.com, ie the ability to send outbound mail.

The following are some tests you should perform :

  1. Create a few accounts on #.new.mailbox.com.

  2. Log in to one of the new accounts and send and receive mail to the other new accounts.

  3. Move test accounts from #.old.mailbox.com to #.new.mailbox.com (See next section for steps).

  4. Client sync (IMAP, POP, COS, Mobile, etc) from proxy on new.server.com to accounts on both systems.

Spend time testing and customizing the new user experience to ensure that when you redirect traffic to the new MTA and proxy there are no issues.

Redirect MTA, Proxy traffic to the Daffodil (v10) server new.server.com

  • Maintenance window - 15 minutes.

Direct MTA and Proxy traffic to the #.new.mailbox.com server. During this transition, web users may see a slight delay and may need to reload their browser since https/http traffic will be redirected.

All other clients should not experience any sync issues if the hostname they are using does not change. If the hostname is changed then all clients will need to be reconfigured with the new hostname.

We also recommend configuring your COS to create new accounts on the new system by performing the following steps:

  • Obtain the zimbraID from the new.mailbox.com:

zmprov gs new.mailbox.com zimbraId

Using the zimbraID that was obtained and updating all of the COS’s:

for c in $(zmprov gac); do zmprov mc $c zimbraMailHostPool <zimbraId>; done;
zimbraMailHostPool supports multiple settings and should contain both server zimbraId. The above script will remove and then reset the setting to the #.new.mailbox.com zimbraId.

Migrating Accounts

This section will cover migrating account data from the #.old.mailbox.com to the #.new.mailbox.com servers. This migration can consist of following steps:

  1. Export Zimbra Drive Data.

  2. Migrating the mailbox account from #.old.mailbox.com to #.new.mailbox.com using the zmmboxmove command.

  3. Import Zimbra Mobile Data.

  4. Import Zimbra Drive Data.

If Zimbra Drive is not being used, step #1 and #4 can be skipped.

Exporting Zimbra Drive Data

If Zimbra Drive is being used, the data can be exported for all or selected accounts based on the migration schedule. We recommend exporting data prior to moving an account to ensure all the latest files are migrated.

  • Why doesn’t zmmboxmove migrate Zimbra Drive data?

Zimbra Drive for 8.8.15 and 9 stores its data outside of the account. The drive migration tool will migrate Drive Data into the Briefcase of the account for better management and data ownership.

Following are the recommendations when migrating Zimbra Drive data:

  1. Make sure you have provisioned enough free storage space in the /opt/zimbra/<partition> to accommodate the drive data during the export and import process. For e.g., if you have Drive data of 10GB, it is recommended to provision 30GB of free space.

  2. In case you have a large size of Drive data, it is highly recommended to export and import in batches.

  3. Ensure the targeted server drive data is migrating to contains the targeted accounts.

    • As a zimbra user, execute this command:

su - zimbra
zmmodulesport account export --modules=drive --filename=drive-data --server=<old.server.com> --username=admin@domain.com --password=admin_passwd >> /opt/zimbra/log/drive-export.log

A file drive-data.tgz will be created within /opt/zimbra/tmp/modules/drive/.

  • To export the Drive data in batches, create a file accounts-file.txt which will have email addresses of the accounts separated by new line. Make sure to use a different file in the --filename parameter when exporting for multiple batches. Execute this command as a zimbra user.:

su - zimbra
zmmodulesport account export --modules=drive --accounts=/path/to/accounts-file.txt --filename=drive-data-batch1 --server=<old.server.com> --username=admin@domain.com --password=admin_passwd >> /opt/zimbra/log/drive-export.log

A file drive-data-batch1.tgz will be created within /opt/zimbra/tmp/modules/drive/.

The import command is NOT shown at this time as we will have to migrate the account before importing. The command will be provided below at the appropriate time.

Migration of Accounts

A Successful migration will automatically enable the profile on the #.new.mailbox.com.

It’s time to move accounts from #.old.mailbox.com to #.new.mailbox.com using the zmmboxmove command. This command will be used for all accounts (users and systems).

When using local object store with blobless move, the destination server #.new.mailbox.com must contain the same store configuration as the targeted server #.old.mailbox.com which the account resides on. Blobs will not render if an account is moved to any-other server
su - zimbra
zmmboxmove -a <user-account@domain.com> -f <old.server.com> -t <new.server.com> --sync

For systems that are using S3 storage, you will need to use --ngMigration flag to update the blob locater once the account has been moved.

su - zimbra
zmmboxmove -a <user-account@domain.com> -f <old.server.com> -t <new.server.com> --sync --ngMigration

After a successful move, the migration script will update the user LDAP to point to #.new.mailbox.com. When the user logs in they will access the data on the new system and if the user is currently logged in, they will receive a message requesting them to reload the browser. For devices using active-sync, when sync is enabled, the clients will receive a re-sync request and will re-sync the account. For all other clients, they should not experience any sync issues.

To obtain a list of all users on a server:

zmprov -l gaa -s <new.server.com>

To obtain a list of all calendar accounts on a server:

zmprov -l gacr -s <new.server.com>

The zmmboxmove command moves a single mailbox at a time but can be scripted to move

To rollback to the account data on the #.old.mailbox.com for any reason, update zimbraMailHost and zimbraMailTransport and this will redirect the user back to the account on #.old.mailbox.com.
zmprov ma <user-account@domain.com> zimbraMailHost old.server.com
zmprov ma <user-account@domain.com> zimbraMailTransport lmtp:old.server.com:7025
When reverting back to #.old.mailbox.com, any data that was delivered to the account when hosted on #.new.mailbox.com will be missing.

Accounts that exist within the LDAP but haven’t been created will receive the following error when moving:

zmmboxmove -a <user-account@domain.com> -f old.server.com -t new.server.com
An error occurred: system failure: Account user@domain.com does not have a mailbox on server new.server.com

Update the account manually by updating the zimbraMailHost and zimbraMailTransport attributes by running:

zmprov ma user@domain.com zimbraMailHost new.server.com zimbraMailTransport lmtp:new.server.com:7025

Once all accounts have been migrated, it’s time to update your distribution lists zimbraMailHost with #.new.mailbox.com. Modify and run the following command to update all of your existing DLs

for l in $(zmprov gadl); do zmprov mdl $l zimbraMailHost new.server.com; done

It is recommended to purge user data on the #.old.mailbox.com once all data has been verified and the account is in production on the #.new.mailbox.com. When doing a purge, all data will be deleted on #.old.mailbox.com including drive data. This can be done hours, days, or weeks after the account has been moved based on your business needs, and can be done by running:

zmpurgeoldmbox -a user@domain.com -s old.server.com

If you performed a blobless move, set zimbraMailboxMoveSkipBlobs to FALSE:

zmprov mcf zimbraMailboxMoveSkipBlobs FALSE
If blobless move is being used, updating zimbraMailboxMoveSkipBlobs needs to be done after all accounts have been deleted from #.old.mailbox.com.

Import Mobile data

For NG Mobile, if you have set the ABQ mode to Strict and if there are any devices updated in the Allowed Device list on NG server, after the mobile data import to the new.server.com server, update the zimbraMobileBlockedDevices to allow syncing of the allowed devices:

  • As a zimbra user, execute this command on #.new.mailbox.com:

su - zimbra
zmprov md domain.com +zimbraMobileBlockedDevices "*"
  • As a zimbra user, execute this command on #.new.mailbox.com:

su - zimbra
zmmodulesport system import --modules=mobile --filename=mobile-data1 --server=new.mailbox.com --username=admin@new.mailbox.com --password=admin_passwd >> /opt/zimbra/log/mobile-import.log
This step only needs to be done once per cluster since all attributes are domain level and resides within the LDAP.
After the import, user’s who are using NG Mobile Password feature will have to update their zimbra account’s password in mobile settings.

Import Zimbra Drive Data

Before you start the import, it is recommended to increase the file upload size and auth token lifetime.

The default value of zimbraFileUploadMaxSize is 10MB (10485760) and zimbraAdminAuthTokenLifetime is 12 hour (12h).

If you want to increase the zimbraFileUploadMaxSize value to 100MB, please specify the value in bytes and update the zimbraFileUploadMaxSize attribute on mailbox server.

On COS level, if you want to increase zimbraAdminAuthTokenLifetime value to 24 hours, please specify the value as 24h and update the zimbraAdminAuthTokenLifetime attribute on mailbox server.

su - zimbra
zmprov mcf zimbraFileUploadMaxSize 104857600
zmprov mc default zimbraAdminAuthTokenLifetime 24h

Restart mailbox service to make the changes effective:

su - zimbra
zmmailboxdctl stop

Once the accounts are moved to #.new.mailbox.com, import Drive data by executing the following on #.old.mailbox.com:

su - zimbra
zmmodulesport account import --filename=drive-data --modules=drive --server=new.server.com --username=admin@domain.com --password=admin_passwd >> /opt/zimbra/log/drive-import.log
  • To import the Drive data in batches, specify the correct file in the --filename. Execute this command as a zimbra user.:

su - zimbra
zmmodulesport account import --filename=drive-data-batch1 --modules=drive --server=new.server.com --username=admin@domain.com --password=admin_passwd >> /opt/zimbra/log/drive-import-batch1.log
The destination server #.new.mailbox.com must be where the account resides on. Selecting a server that does not have an account will result in an error.

Repeat this on all servers until all accounts have been migrated.

Remove Old Production Servers

At this time, #.new.mailbox.com servers are now managing 100% of the load, and #.old.mailbox.com services can be stopped. Stop all services on the #.old.mailbox.com servers by running the following command on each mailbox server:

su - zimbra
zmcontrol stop

Allow #.new.mailbox.com servers to run for a period of time with #.old.mailbox.com services stopped, to allow users to report any issues. Once you feel it’s safe to remove _#.old.mailbox.com_servers you can uninstall Zimbra:

cd /opt/zimbra/libexec/installer/
./install.sh -u

Remove old.ldap.com from new.ldap.com LDAP tree

  • Delete the old.ldap.com server entry. Execute this command on #.new.mailbox.com:

su - zimbra
zmprov ds old.ldap.com
  • Update the convertd URL. Execute this command on new.server.com:

su - zimbra
zmprov mcf zimbraConvertdURL 'http://new.mailbox.com:7047/convert'
  • When a server is deleted, the loggerhost map entries are not deleted. Check for any stale entries related to old.server.com. Execute this command on new.server.com:

zmloggerhostmap
  • In case any stale entries found in the output of the above command, execute this command to remove them:

zmloggerhostmap -d old old.server.com
zmloggerhostmap -d old.server.com old.server.com