Migrating from any IMAP/POP3 server to Dovecot via dsync
========================================================

You need Dovecot v2.1.4+ for this.

This page describes how to migrate mails to Dovecot from a remote IMAP/POP3
server, preserving the IMAP UIDs, POP3 UIDLs and everything else.

We'll assume that you can log in with master user "master" that has a password
"secret". If you can't use master users, you'll need the users' plaintext
passwords and change the appropriate configuration to use them.

IMAP migration configuration
----------------------------

Set up configuration for the IMAP server you wish to migrate from:

---%<-------------------------------------------------------------------------
imapc_host = imap.example.com
imapc_user = %u
imapc_master_user = master
imapc_password = secret
imapc_features = rfc822.size
# If you have Dovecot v2.2.8+ you may get a significant performance improvement
with fetch-headers:
imapc_features = $imapc_features fetch-headers
# Read multiple mails in parallel, improves performance
mail_prefetch_count = 20

# If the old IMAP server uses INBOX. namespace prefix, set:
#imapc_list_prefix = INBOX

# for SSL:
#imapc_port = 993
#imapc_ssl = imaps
#imapc_ssl_ca_dir = /etc/ssl
#imapc_ssl_verify = yes
---%<-------------------------------------------------------------------------

POP3 migration configuration
----------------------------

Set up configuration for the POP3 server you wish to migrate from:

---%<-------------------------------------------------------------------------
pop3c_host = pop3.example.com
pop3c_user = %u
pop3c_master_user = master
pop3c_password = secret

# for SSL:
#pop3c_port = 995
#pop3c_ssl = pop3s
#pop3c_ssl_ca_dir = /etc/ssl
#pop3c_ssl_verify = yes

namespace {
  prefix = POP3-MIGRATION-NS/
  location = pop3c:
  list = no
  hidden = yes
}
protocol doveadm {
  mail_plugins = $mail_plugins pop3_migration
}
plugin {
  pop3_migration_mailbox = POP3-MIGRATION-NS/INBOX
}
---%<-------------------------------------------------------------------------

The pop3-migration plugin is used to preserve POP3 UIDLs. When dsync is
handling IMAP INBOX and requests a POP3 UIDL, the plugin connects to the POP3
server and figures out which IMAP messages match which POP3 messages and then
returns the appropriate POP3 UIDL.

Running
-------

Make sure destination is exactly as source, deleting/reverting any changes in
destination if necessary:

---%<-------------------------------------------------------------------------
doveadm -o mail_fsync=never backup -R -u user@domain imapc:
---%<-------------------------------------------------------------------------

or incremental one-way merge (it's ok to do changes on both sides):

---%<-------------------------------------------------------------------------
doveadm -o mail_fsync=never sync -1 -R -u user@domain imapc:
---%<-------------------------------------------------------------------------

(Fsyncing is disabled just for migration efficiency.)

For per-user user/passwords use:

---%<-------------------------------------------------------------------------
doveadm -o imapc_user=foo -o pop3c_user=foo -o imapc_password=bar -o
pop3c_password=bar backup -R -u user@domain imapc:
---%<-------------------------------------------------------------------------

Once the users are migrated, remember to remove the pop3_migration plugin from
settings.

Problems
--------

 * POP3 message order (when it's different from IMAP message order) is
   currently preserved only when destination is Maildir, sdbox or mdbox.
 * If source POP3 server merges multiple IMAP mailboxes into one POP3 INBOX,
   the migration won't be transparent.
 * If source IMAP and POP3 servers return messages somehow differently,
   pop3-migration plugin might not be able to match the messages

(This file was created from the wiki on 2014-10-03 04:43)