Developers Documentation



301 error for file:

User Tools

Site Tools

Migrating Email Stores for Cyrus POP and IMAP

This guide will help you move email from one ClearOS installation to another. This is useful if you are upgrading between versions that cannot be upgraded. It is also useful if you are migrating your ClearOS instance to different physical hardware or to a VM.


There are various steps you will need to take to plan your migration. Of particular concern is the cutover. At some point you will stop services on your box and move the mail over. If you plan appropriately, this downtime can be as short as just a few minutes. If you fail to plan…plan to fail.


If you are performing this migration with two different boxes, you will have an easy time of things and you will have minimal downtime. In addition, you can test things out before committing all the data over. As such, this is the best practice for mail migration and an inline migration is not recommended but you can use these steps to help you nonetheless. For this guide, we will assume a two system migration from the old to the new.

On the new box, you will need to install the POP and IMAP server from the marketplace or from command line:

yum install app-imap

You will also need to have a directory of users that is the same more or less as the directory you are coming from. At a minimum, the usernames need to be the same. In most cases, you can migrate the directory by performing a configuration backup from the old server and a configuration restore. This works for boxes running the same version of ClearOS as each other and it can work as well for migrations from 6 to 7 using the migration tools in the marketplace (released in 7.2). If you are coming from version 5 of ClearOS, please contact ClearCARE support for assistance in moving your directory.

Another way to re-create uses is to use the Account Import tool. Once you have the users, validate that they are part of the IMAP extensions or plugin group. This enables them for access to the service.

Lastly, make sure the IMAP is a supported protocol during the migration. You can use IMAPS later but for the migration of data you must have IMAP for the tools to work.


For the pre-migration, we will actually take a snapshot of all the mail and install it on the new system. There is a two-fold purpose here. First, we get a large chunk of data to be moved over and will subsequently make incremental and differential changes to the mail stores. Second, we can test the system to ensure that we can both send and receive email before ever moving this mail server into production.

From command line, login to cyradm:

cyradm --user root --server localhost

Enter root's password.

Here is the tedious bit. You will need to create all the mailboxes. It is possible to copy and paste the list from a file but you will need to do this for each user. Here is an example:

cm user/john
cm user/sue
cm user/benson

You can validate your users by typing:


When you are finished, Type 'quit' to quit cyradm

Now, reconstruct the mailboxes:

su -c "/usr/lib/cyrus-imapd/reconstruct -r -f user/*" cyrus -s /bin/bash

Now, rsync from the old server by running this command from the new server (substituting 'current.server' for the hostname or IP of the production server):

rsync -avz --delete -e ssh root@current.server:/var/spool/imap/* /var/spool/imap/

Sit back, this can take a while…or you can come back later. For big installs, consider running this from 'screen' (available in the clearos-centos repo) so that it will keep running even if your ssh session disconnects. Don't worry though…if it failes to run properly, just re-run it.

chown -R cyrus.mail /var/spool/imap/*

Next, run reconstruct again:

su -c "/usr/lib/cyrus-imapd/reconstruct -r -f user/*" cyrus -s /bin/bash

At this point you can test sending and receiving email from this copy of the server. This configuration should NOT be used as the production server right now because in the time it took to copy the mail, you probably got new messages. But as was mentioned, we can test now to see if things are in order.


The server is now in a state of cloning. You can re-run the last 3 steps whenever you like and it will give you a snapshot (more or less) of what you have on the original server (I say less because changes happen on the old server while the service are running and you won't get those changes. To review, those steps are:

rsync -avz --delete -e ssh root@current.server:/var/spool/imap/* /var/spool/imap/
chown -R cyrus.mail /var/spool/imap/*
su -c "/usr/lib/cyrus-imapd/reconstruct -r -f user/*" cyrus -s /bin/bash

Cut over

Now that you are familiar with taking cloned images of your old server, you can schedule your outage of the production server and move this one into place. You may have other migration tasks to do if you have other services but here is what you will need to do for the cutover of IMAP and POP3 services.

On the old server run the following:

service cyrus-imapd stop
service postfix stop
chkconfig cyrus-imapd off
chkconfig postfix off

Now on the new server run a cloning ONE LAST TIME:

rsync -avz --delete -e ssh root@current.server:/var/spool/imap/* /var/spool/imap/
chown -R cyrus.mail /var/spool/imap/*
su -c "/usr/lib/cyrus-imapd/reconstruct -r -f user/*" cyrus -s /bin/bash

There you go, now all you have to do is to redirect the mail to the new server by doing perhaps one of the following:

  • Re-IP the new server to what the old server was (most common)
  • Redirect port forwarding and firewall rules to the new server and all the email clients who don't use hostnames.
  • Visit all the appropriate DNS records and make sure they are pointing to the new server.

Finishing Up

Congratulations. Hopefully you didn't encounter any issues and were able to validate all your capabilities before cutting over the server.

One last mandatory step:

  • Treat yourself to something nice…you deserve it.
content/en_us/kb_migrating_email_cyrus.txt · Last modified: 2016/02/02 18:21 by dloper