Cool Solution - Migrate Dovecot to UCS Dovecot

Version 4.1

Note: Cool Solutions are articles documenting additional functionality based on Univention products. Packages provided by a Cool Solutions Repository are built by Univention, but will not be maintained. Not all of the shown steps in the article are covered by Univention Support. For questions about your support coverage contact your contact person at Univention before you want to implement one of the shown steps.

Also regard the legal notes at Terms of Service.

Note: This article is not yet reviewed.

This article describes how to migrate mails from one Dovecot server (running Debian Jessie in this case) to an UCS Dovecot.

The new (empty) mailboxes have to exist on the destination system. The listener module automatically creates them for every user with a primary mail address, once the mail server app from the App Center is installed. Once these mailboxes exist we will then use "offlineimap" to migrate the mails into those boxes.

To be able to access the mails we will create a Dovecot master user on the old mail server. This user is able to access any mailbox and thus makes the migration much easier. You can easily remove this user afterwards if you want to use the mailserver somewhere else for example.

This guide uses a helper script created by Univention, which will create configuration files, move mails etc.

Create master user on old mailserver

The following steps have to be executed on the old non-UCS mail server!

Create a passwd file for the master user:

echo "migration:SHA256{$(echo -n "<your password>" | sha256sum | head -c 64)}" > /etc/dovecot/passwd.masterusers

If you do not want the master user's password to be found in the shell history, you can also create the file with a silent prompt:

read -s -p "Password: " passwd ; echo "migration:{SHA256}$(echo -n "$passwd" | sha256sum | head -c 64)" > /etc/dovecot/passwd.masterusers

This will create a master user with the username "migration" and the SHA256 hashed password "<your password>".

Now we have to make this known to Dovecot.

Open the authentication configuration file:

vim /etc/dovecot/conf.d/10-auth.conf

Paste the following lines at the end of the file:

auth_master_user_separator = *
passdb {
  driver = passwd-file
  args = /etc/dovecot/passwd.masterusers
  master = yes
  pass = yes
}
passdb {
  driver = shadow
}
userdb {
  driver = passwd
}

Reload Dovecot afterwards to read the new configuration:

service dovecot reload

Now we can access any mailbox with the user "migration" and the separator "*". For example, to access the mailbox of user "john.doe@mydomain.demo" with the master user "migration" you would have to login with "john.doe@mydomain.demo*migration" and the master user's password.

Install required packages

On the new UCS server (the destination of the migration), two packages have to be installed. The helper script by Univention will install the other needed program (offlineimap) aswell, since it is configured as dependency.

Install the package univention-dovecot-migration from the Cool Solutions repository.

ucr set repository/online/unmaintained=yes

univention-install univention-dovecot-migration

Migrate mails

All following steps have to be executed on the destination UCS server! As mentioned above, the mailboxes have to exist already on the destination UCS server.

Create a configuration file for offlineimap with the supporting script. This tool reads all users with a primaryMailAddress attribute and the current server set as univentionMailHomeServer from the LDAP and uses the given start parameters to create a config file.

univention-dovecot-migration -sd <old mail domain> -dd <new mail domain> -mu <master user name> -mp <master user password> \
-r <old mailserver hostname or IP> -rPort <IMAP port on old mail server> [-ssl] -lf <absolute path to work folder> \
-of <name of file to write config to> -g

So in an example environment with the following characteristics:

Option	Value
old mail domain	oldmaildomain.web
new mail domain	newmaildomain.web
master user on the old server	migration
password for the master user on the old server	univention
old mail server	oldmailserver.mydomain.web
IMAP port to use on old mailserver	993
Use SSL	yes
folder to work in (has to be empty!):	/root/migration
file to write configuration to	migration.conf

Note, that the local folder (parameter: -lf) has to be completely empty for the migration process to succeed!

the command would look as follows:

univention-dovecot-migration -sd oldmaildomain.web -dd newmaildomain.web -mu migrationuser -mp univention \
-r oldmailserver.mydomain.web -rPort 993 -ssl -lf /root/migration \
-of migration.conf -g

Now we have to create the specified work folder for offlineimap.

mkdir -p migration/<old mail domain>

Start offlineimap with the configuration file. Output will be written both to standard out and the file offlineimap.log

offlineimap -c <config file> | tee offlineimap.log

If you do not want any output

offlineimap -u quiet -c <config file>

Unless you use the "quiet" option, you will see each migrated mail for all users one by one. Offlineimap also logs errors, so you can check what went wrong if something could not be migrated. At the end of every migrated mailbox, offlineimap calls a so called "PostSyncHook" from univention-dovecot-migration, which moves the migrated mailboxes to the listener-created mailboxes below /var/spool/dovecot/private and makes Dovecot the owner. It also removes them from the work directory afterwards.

After the offlineimap has finished you can use another function from the script to make sure all mails have been migrated. It counts all mails on the old and new mail server. If the two numbers are the same you all mails have been migrated.

To count all objects in the old mail server spool:

univention-dovecot-migration -ru <old mail server ssh user name> -rp <old mail server ssh user password> -r <old mail server hostname or IP> -rPath <Path on old mail server that contains the mail domain folder> -sd <old mail domain> -ts -t

Example:

univention-dovecot-migration -ru root -rp univention -r oldmailserver.mydomain.intern -rPath /var/vmail -sd oldmaildomain.web -ts -t

To count all objects in the the new/current mail server spool:

univention-dovecot-migration -dd <new mail domain> -td -t