Zimbra Daffodil (v10) Single-Node NG Modules Migration Guide through Rolling-Upgrade

This document is applicable for Zimbra Daffodil versions 10.0 and 10.1.0.

License

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

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

http://www.synacor.com

Licensing changes introduced in Zimbra Daffodil (v10.1)

Zimbra Daffodil (v10.1) onwards, a new licensing system has been introduced which allows more flexibility in managing licenses and enable future granular feature add-ons.

Before you begin with the migration, refer to the Zimbra Daffodil (v10.1) Licensing section and review the changes.

Introduction

This guide provides steps to migrate the 8.8.15/9.0.0 Single-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 a ZCS server. 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.

Following are the steps involved in this method:

Create a New Server.
Enable MMR on the Production Server.
Install using the current production version with all modules on the New Server, which will initiate LDAP replication.
Point Production Server to the new LDAP and deprecate the existing LDAP module.
Upgrade New Server to Daffodil.
Customize and Test New Server.
Redirect production connection to the New Server.
Migrate accounts.
Deprecate Production Server.

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 best to identify what is needed 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 section 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 model, a new system will need to be created. When creating the new system, 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.

Setting up MMR and installing services on the new server

For better understanding, we will use the following examples across the guide:

8.8.15/9.0.0 server - old.server.com
Daffodil (v10) - new.server.com

This section will be enabling MMR on the current production server (old.server.com), then a new system will be added (new.server.com) using the current ZCS version to make a two-server cluster. Once the following steps within this installation have been completed, old.server.com will be using the LDAP service on new.server.com and the LDAP service on old.server.com will be disabled.

This will not affect the NG modules since the attributes that enable the modules are located on the old.server.com mailbox store and are listed as available zimlets. Since NG is not installed on the new.server.com mailbox store, the new.server.com server will ignore the NG zimlet configuration.

Before starting this process, you will need to create a new system using an OS version that is supported by your current Zimbra version and Daffodil (v10). This system should have the required environmental configuration (CPU, Memory, etc) to support current and future growth.

The operating system (OS) is a server-specific requirement and does not need to be the same version as your current production server.

Before enabling MMR, you will need to obtain existing passwords from old.server.com to use during the installation on new.server.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.server.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.server.com:

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

Please refer to this guide for more information on enabling Multi-Master Replication on an existing Single Node Master server.

Installing and syncing LDAP replication

On the new.server.com server, download the current production version of ZCS and the active license file. Please refer to the Download Page to get the ZCS version build. Once the download has been completed, untar and run ./install.sh using the license file.

All Zimbra components along with the LDAP module need to be installed to take advantage of the installation script auto-configuring the cluster.

./install.sh -l /path/license.xml

DO NOT install any of the NG modules, zimbra-network-modules-ng, zimbra-chat, Zimbra Drive, or Connect at this time. In the following section, new.server.com will be upgraded to Daffodil (v10) which has updated features to replace these components.

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]
Install zimbra-logger [Y]
Install zimbra-mta [Y]
Install zimbra-dnscache [Y]
Install zimbra-snmp [Y]
Install zimbra-store [Y]
Install zimbra-apache [Y]
Install zimbra-spell [Y]
Install zimbra-convertd [Y]
Install zimbra-memcached [Y]
Install zimbra-proxy [Y]
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.server.com can connect to the old.server.com.

1) Common Configuration:
        2) Ldap master host: <old.server.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

Then you will need to update the password for all other components using the password obtained from the production server old.server.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

Lastly, you will need to update the admin password within section 7, zimbra-store using the existing administrator password:

7) zimbra-store:                            Enabled
    ** 4) Admin Password                           UNSET

The above menu items are not complete and may differ based on the selected components to be installed. But based on the environment setup, there may be more or fewer requirements and other customization but the above LDAP configuration is required for enabling MMR.

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

Obtain current configuration:

zmprov ga <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries
#name test-user@domain.com
zimbraZimletUserPropertiesMaxNumEntries: 150

Update configuration on old.server.com then verify the change on new.server.com.
- On old.server.com, execute this command as a zimbra user:

zmprov ma <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries 160

On new.server.com, execute this command as a zimbra user:

zmprov -l ga <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries

Restore configuration on new.server.com then verify the change on old.server.com.
- On new.server.com, execute this command as a zimbra user:

zmprov ma <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries 150

On old.server.com, execute this command as a zimbra user:

zmprov -l ga <test-user@domain.com> zimbraZimletUserPropertiesMaxNumEntries

Note: -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.

Upgrade the new server to Zimbra Collaboration Daffodil (v10)

This stage consists of two steps which both require downtime:

Configure old.server.com to use the new LDAP on new.server.com.
Upgrade the new.server.com to Zimbra Collaboration Daffodil (v10).

Once the first step is completed, old.server.com will function the same except it will be using the LDAP on new.server.com.

The second step will upgrade the components on new.server.com to Zimbra Collaboration Daffodil (v10) while giving the option to install the only office and the updated chat & video features. Once the upgrade is completed, new.server.com LDAP will have a new schema, and the old.server.com will be configured to use the updated LDAP which will be running Daffodil (v10).

Configuring the production system (old.server.com) to use the new LDAP

Maintenance window - 5 minutes approx.

To remove the existing LDAP from the MMR replica update ldap_master_url and ldap_url on both systems to point to new.server.com.

As zimbra user execute these commands on both servers:

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

On the old.server.com, remove LDAP from zimbraServiceEnable and zimbraServiceInstalled:

zmprov ms <old.zimbra.com> -zimbraServiceEnabled ldap -zimbraServiceInstalled ldap

Restart zimbra services on both servers:

zmcontrol restart

After the restart of both servers, the old.server.com is now using the LDAP on new.server.com. Since we removed the production LDAP from the list of enabled services, it still could be running but is not being used. On old.server.com, you may need to stop the production LDAP by running:

ldap stop

Note: The new.server.com currently has a self-sign certificate.

The Admin UI is running on both systems and will reflect the version installed on the system. Log into old.server.com and new.server.com admin UI and verify you can access, view, and edit server, user, and COS configuration.

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.server.com LDAP is not removed within step 2 above, then 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

Install your Signed certificate

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

Ensure the permissions are set to zimbra on all files.

As root user, execute this command:

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

Update SSH Keys

To configure ssh access to sync account data between old.server.com and new.server.com, an ssh key will need to be generated on each server, then each server needs to sync the other server’s ssh key. To create ssh keys run zmsshkeygen as a zimbra user on both systems:

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.

Status: At this stage, both servers have the same version running but old.server.com is pointing to the new LDAP. All activity other than LDAP is occurring on old.server.com. On new.server.com, Proxy, MTA and mailbox services are running and accessible but in an idle state. The installation can be tested by passing data through new.server.com MTA and Proxy, these servers will redirect the connection to the server where the accounts reside on. The Admin UI is also accessible on both systems. The old.server.com will contain the NG modules and new.server.com will not. Because of this, all accounts need to be managed using the old.server.com admin UI.

Add OnlyOffice repository

Add the OnlyOffice repository on the system.

If you are not using Zimbra Docs or do not intend to use it after the upgrade to Daffodil (v10), then you can skip this section.

Following are the steps. Execute the commands as root user

RHEL 7

$ cat > /etc/yum.repos.d/zimbra-onlyoffice.repo <<EOF
[zimbra-onlyoffice]
name=Zimbra Onlyoffice RPM Repository
baseurl=https://repo.zimbra.com/rpm/onlyoffice/rhel7
gpgcheck=1
enabled=1
EOF

$ yum --disablerepo=* --enablerepo=zimbra-onlyoffice clean metadata

$ yum check-update --disablerepo=* --enablerepo=zimbra-onlyoffice --noplugins

RHEL 8

$ cat > /etc/yum.repos.d/zimbra-onlyoffice.repo <<EOF
[zimbra-onlyoffice]
name=Zimbra Onlyoffice RPM Repository
baseurl=https://repo.zimbra.com/rpm/onlyoffice/rhel8
gpgcheck=1
enabled=1
EOF

$ yum --disablerepo=* --enablerepo=zimbra-onlyoffice clean metadata

$ yum check-update --disablerepo=* --enablerepo=zimbra-onlyoffice --noplugins

UBUNTU 18

$ cat > /etc/apt/sources.list.d/zimbra-onlyoffice.list << EOF
deb [arch=amd64] https://repo.zimbra.com/apt/onlyoffice bionic zimbra
deb-src [arch=amd64] https://repo.zimbra.com/apt/onlyoffice bionic zimbra
EOF

$ apt-get update

UBUNTU 20

$ cat > /etc/apt/sources.list.d/zimbra-onlyoffice.list << EOF
deb [arch=amd64] https://repo.zimbra.com/apt/onlyoffice focal zimbra
deb-src [arch=amd64] https://repo.zimbra.com/apt/onlyoffice focal zimbra
EOF

$ apt-get update

Upgrading the new.server.com to Daffodil (v10)

Maintenance window - 60 minutes approx.

It is time to upgrade new.server.com to Daffodil (v10).

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

The installer will ask if you wish to upgrade and list all uninstalled packages. For Daffodil there will be two, zimbra-onlyoffice that’s used for document editing and Chat & Video used for chat and video calling. Following is the overview of the upgrade screen:

Do you wish to upgrade? [Y] Y
Install zimbra-archiving [N] n
Install zimbra-onlyoffice [N] y
Install chat and video features [N] n
Installing:
zimbra-core
zimbra-ldap
zimbra-logger
zimbra-mta
zimbra-dnscache
zimbra-snmp
zimbra-store
zimbra-apache
zimbra-spell
zimbra-convertd
zimbra-memcached
zimbra-proxy
zimbra-onlyoffice
zimbra-license-tools
zimbra-license-extension
zimbra-network-store
zimbra-modern-ui
zimbra-modern-zimlets
zimbra-zimlet-document-editor
zimbra-zimlet-classic-document-editor
zimbra-patch
zimbra-mta-patch
zimbra-proxy-patch
zimbra-ldap-patch
zimbra-rabbitmq-server
The system will be modified. Continue? [N] Y

If there is any configuration that needs to be modified during the installation, the configuration prompt will show which contains '**'. This will differ on each installation but most of the time is caused by a password issue which will need to be obtained from old.server.com using the steps at the beginning fo this document.
```
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
```
After providing the required information, complete the upgrade.

Note: Once MMR has been enabled OpenLDAP does not support disabling MMR. Because we are using MMR as the method to move to another server, once the old.server.com LDAP has been removed, the new.server.com LDAP will start reporting connection errors within zimbra.log. This does not have any effect on the new LDAP except for excessive logging to the zimbra.log. To prevent this log from filling up, we recommend purging the logging every hour or two by creating the following crontab entry:

*/2 0 * * * sed -i -e '/ldap_start_tls failed\|rc -1 retrying/d' /var/log/zimbra.log

Status: After the upgrade is completed, all modules on new.server.com have been upgraded to Daffodil (v10). This means old.server.com is now using a Daffodil (v10) LDAP server which supports backward compatibility. All other components on new.server.com are in an idle state.

Customization, configuration and test the Daffodil (v10) system

It’s time to finish configuring, customizing, and testing new.server.com. Accessing the hostname of the new.server.com or old.server.com will direct you to the login page that resides on the server. Accessing the accounts will redirect the user to the server that the account resides on. Accessing the admin UI will log the user into the selected server admin page. For the Admin UI, new.server.com will have the Daffodil (v10) experience, and old.server.com hostname will have the NG experience.

We recommend managing the account using the Admin UI version that the server belongs to ensure that the changes are recognized. Also, the Daffodil (v10) UI will report that some services are down and there is no backup. For the services, this is understandable since we did not configure the server to report their status to each other since the old.server.com system will be deprecated.

Because the hostname of the original server is changing, the login URL needs to be added to the domain virtual host list. This can be done by going into the Admin UI, then selecting Domain → editing <domain> → Virtual Hosts.

You can also add the virtual host through command. As a zimbra user, execute the command:

zmprov md <Domain.com> +zimbraVirtualHostname <hostname>

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

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

Following are the details of the attributes we need to use whe 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:

Primary Storage - Internal | Secondary Storage - External

Following are the details of this setup:

You are using NG HSM.
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.

Primary and Secondary Storage - External

Following are the details of this setup:

You are using NG HSM.
The Primary and Secondary Storage is setup on External S3 storage.

You will have to set attribute zimbraMailboxMoveSkipBlobs to 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 using NG HSM.
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

As a zimbra user, execute this command:

su - zimbra
zmmodulesport system export --modules=hsm --filename=hsm-data --server=old.server.com --username=admin@domain.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:

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

Using zmmodulesport will overwrite the Manage Volumes on the new.server.com using the setup for the old.server.com server. To redesign your new Daffodil volume, we recommend importing the old.server.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:

su - zimbra
zmmodulesport system export --modules=backup --filename=backup-data --server=old.server.com --username=admin@domain.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 new.server.com’s 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.

Export Delegated Admin data

As a zimbra user, execute this command:

su - zimbra
zmmodulesport system export --modules=admin --filename=admin-data --server=old.server.com --username=admin@domain.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:

su - zimbra
zmmodulesport system import --modules=admin --filename=admin-data --server=new.server.com --username=admin@domain.com --password=admin_passwd >> /opt/zimbra/log/da-import.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.server.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.server.com to manage NG modules, or new.server.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:

su - zimbra
zmmodulesport system export --modules=mobile --filename=mobile-data --server=old.server.com --username=admin@domain.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.server.com to new.server.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 :

Create a few accounts on new.server.com.
Log in to one of the new accounts and send and receive mail to the other new accounts.
Move test accounts from old.server.com to new.server.com (See next section for steps).
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.server.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.server.com:

zmprov gs new.server.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.server.com zimbraId.

Migrating Accounts

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

Export Zimbra Drive Data.
Migrating the mailbox account from old.server.com to new.server.com using the zmmboxmove command.
Import Zimbra Mobile Data.
Import Zimbra Drive Data.

If you are not using Zimbra Drive, you can skip step #1 and #4.

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 the 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:

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.
In case you have a large size of Drive data, it is highly recommended to export and import in batches.
- 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.server.com.

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

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 locator 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.server.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.server.com for any reason, update zimbraMailHost and zimbraMailTransport and this will redirect the user back to the account on old.server.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.server.com, any data that was delivered to the account when hosted on new.server.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 ga 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.server.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.server.com once all data has been verified and the account is in production on the new.server.com. When doing a purge, all data will be deleted on old.server.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.server.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.server.com to set zimbraMobileBlockedDevices on domain level:

su - zimbra
zmprov md domain.com +zimbraMobileBlockedDevices "*"

As a zimbra user, execute this command on new.server.com to set zimbraMobileBlockedDevices on global level:

su - zimbra
zmprov mcf +zimbraMobileBlockedDevices "*"

As a zimbra user, execute this command:

su - zimbra
zmmodulesport system import --modules=mobile --filename=mobile-data1 --server=new.server.com --username=admin@domain.com --password=admin_passwd >> /opt/zimbra/log/mobile-import.log

To import the Mobile data in batches, specify the correct file in the --filename. Execute this command as a zimbra user.:

su - zimbra
zmmodulesport system import --modules=mobile --filename=mobile-data1-batch1 --server=new.server.com --username=admin@domain.com --password=admin_passwd >> /opt/zimbra/log/mobile-import.log

After the import, user’s who are using NG Mobile Password feature will have to update their zimbra account’s password in mobile settings.

Importing 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.server.com, import Drive data by executing the following on old.server.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

Remove Old Production Server old.server.com

At this time, new.server.com is now managing 100% of the load, and old.server.com services can be stopped. Stop all service on old.server.com by running:

su - zimbra
zmcontrol stop

Allow new.server.com to run for a period of time with old.server.com services stopped, to allow users to report any issues. Once you feel it’s safe to remove old.server.com run:

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

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

Delete the old.server.com server entry. Execute this command on new.server.com:

su - zimbra
zmprov ds old.server.com

Update the convertd URL. Execute this command on new.server.com:

su - zimbra
zmprov mcf zimbraConvertdURL 'http://new.server.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

Remove Zimbra Docs

If you are running Zimbra Docs on a separate node, you can remove the server details from the Daffodil (v10) LDAP tree after the upgrade.

Execute this command as a zimbra user:

su - zimbra
zmprov ds docs.server.com