Preferred Method of Moving Users To New Machine (zmmailboxmove - Network Edition Only)

Preferred method of Moving Users to New Machine (zmmailboxmove - Network Edition Only)

   KB 2674        Last updated on 2015-07-11  

(0 votes)

The preferred method of transferring users from one ZCS machine to another ZCS machine is the "mailbox move" method. There are two main advantages of this method:

  1. User data (e.g. mail, contacts, and calendar) is maintained.
  2. Accounts are moved one at a time while both servers are active, so that only the account currently being moved will be inaccessible.

This method typically involves three main stages:

  1. Making the new server an LDAP replica of the original server.
  2. Moving all the accounts to the new server.
  3. Promoting the new server to be the master.


You have an old server called mail1, and you have a new server called mail2. You wish to transfer users from mail1 to mail2. You are installing ZCS on mail2 and configuring it as an LDAP-replica.

Configuring the New Server

First, enable LDAP replication on the old server (mail1).

[root@mail1]# su - zimbra
[zimbra@mail1]$ ~/libexec/zmldapenablereplica

Then check the current version and LDAP passwords on mail1.

[zimbra@mail1 ~]$ zmcontrol -v
Release 5.0.9_GA_2534.RHEL4_20080814054137 RHEL4 NETWORK edition

[zimbra@mail1 ~]$ zmlocalconfig -s |grep ldap |grep password
ldap_amavis_password = zmamavis
ldap_nginx_password = zmnginx
ldap_postfix_password = zmpostfix
ldap_replication_password = zmreplica
ldap_root_password = A1eRG0zP
zimbra_ldap_password = A1eRG0zP

Install ZCS on mail2.

Important: Make sure to install the same ZCS version as mail1.

1. During the configuration stage of the installation, you will be presented will the configuration main menu.

Main menu

   1) Common Configuration:
   2) zimbra-ldap:                             Enabled
   3) zimbra-store:                            Enabled
        +Create Admin User:                    yes
        +Admin user to create:       
******* +Admin Password                        UNSET
  • Choose the first item, Common Configuration, so that you can designate mail1 as the existing LDAP master.

2. You should see something like this:

Common configuration

   1) Hostname:                          
   2) Ldap master host:                  
   3) Ldap port:                                   389
   4) Ldap Admin password:                         set
   5) Require secure interprocess communications:  yes
   6) TimeZone:                                (GMT-08.00) Pacific Time (US & Canada)
  • Choose item 2, Ldap master host, and enter mail1 as the LDAP master.
  • Choose item 4, Ldap Admin password, to enter the LDAP password observed on mail1 (see above or zmlocalconfig -s zimbra_ldap_password).

3. Return to the main menu and choose item 2 for the LDAP Configuration.

Ldap configuration

   1) Status:                                 Enabled                       
   2) Create Domain:                   yes
   3) Domain to create:              
   4) Ldap Root password:              set
   5) Ldap Replication password:       set
   6) Ldap Postfix password:           set
   7) Ldap Amavis password:            set
  • You can choose item 2 to elect not to create a new domain (presumably you already have domains provisioned on mail1).
  • Choose each password item to set these to the corresponding values from mail1.

4. Return to the main menu and choose zimbra-store. Since admin and spam training accounts already exist on mail1, you can choose the Create Admin User and Enable automated spam training items to not create new accounts. If you do this, don't forget to also move the mailboxes for these accounts.

Store configuration

   1) Status:                                  Enabled
   2) Create Admin User:                       no
   3) Enable automated spam training:          no
   4) Global Documents Account:      
   5) SMTP host:                     

As of ZCS 5.0.9, even if you choose to not create a new domain, you can't disable the Global Documents Account in the store configuration menu. You will see a harmless failed to initialize documents warning during configuration. You should already have a global documents account on mail1, which you can mailbox move to mail2.

Moving users to the new server

You can move mailboxes on the server command-line with zmmailboxmove, or through the Administrator Web Console (by logging in to

Promoting the LDAP Replica to be the LDAP Master

If you want the new machine to be the LDAP master, follow the guide for Promoting Replica to LDAP Master, which also explains how to demote the LDAP master to be a replica.

Additional Considerations


Be sure to edit your DNS records to include the new server.

Before the migration:

$ host -t mx mail is handled by 10

After the migration:

$ host -t mx mail is handled by 10

If you wish to maintain the same exact zmhostname as the old server, use zmsetservername to change the hostname.

Commercial SSL Certificates

If the hostname stays the same (e.g. the old server was and the new server gets renamed, copy the certificate files over from the old server and restart services.


If the hostname has changed, generate a new certificate signing request (CSR), submit the CSR to a Commercial Certificate vendor (e.g. GoDaddy), and import the new certificate using the SSL Certificates Wizard in the Admin Console.


If you have changed what Zimlets are available or if you have custom skins or branding, don't forget to re-deploy these customizations.

The Old Server

If you are decommissioning the old server, verify that no accounts remain there, and then delete the server entry from LDAP.

On the new server, check for any accounts that LDAP shows as still on the old server.

zmprov searchAccounts "("

On the old server, check for any accounts that remain there. If any accounts have moved but not purged from the old server, they will still show up.

mysql zimbra -e "select * from mailbox"

Remove the old server from the host pool for all classes of service in the COS section of the admin console. Once you are satisfied that the old server is no longer active, you can delete the server entry.

zmprov deleteServer

Note: Moving accounts with zmmailboxmove is a staged process. You can leave the old server up as an LDAP master, MTA, etc., after the accounts are migrated in order to minimize the number of changes happening at one time.


  • If you are only moving some users to the new server, and the old server will remain active (for example, if you are just adding a new mailstore to the installation), it is not necessary to configure the new server as an LDAP replica and even if you do, it is not necessary to promote it to be the master.
  • This method is only available for the Network Edition of ZCS.
  • You can use your existing license from the master for this multi-node setup.
  • If you encounter a zmmailboxmove: authtoken expired error, verify that the date/time for each server is accurate.
  • For multi-node installations, run zmupdateauthkeys to update the SSH keys.

Verified Against: ZCS 5.0.10 Date Created: 10/13/2008
Article ID: Date Modified: 2015-07-11

Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search