Palomar: Transition from OX Dovecot Pro 2.3.x Architecture

WARNING

This document describes one method, that has successfully been performed in production systems, for transitioning to Palomar from director based clusters. There are other methods that may or may not be right for your platform.

Another method that may fit your needs is a migration.

For additional guidance about your transition and your specific needs please contact Open-Xchange for consultation.

All configuration and steps below should be thoroughly tested on a staging or development platform before deployment in production.

Upgrade to latest 2.3.x release

All Dovecot infrastructure should be on the latest release of the 2.3.x branch.

Configure backend and proxy servers

See Palomar Configuration.

At this time make sure that the passdb configuration on proxy servers contains the host setting. This setting allows the Palomar capable proxy servers to continue to proxy through directors.

Upgrade to 3.0

Dovecot backends and proxies will need to be updated to the 3.0.x version. Make sure that the dovecot-pro-cluster package is installed.

Build director hash to Palomar group mapping

WARNING

The director map created in the first step is only valid for a time. That default time is 15 minutes. These commands should be run within that timeframe.

1. Create map of users from director

   director_server:$ doveadm -f json director status > directors.json
   director_server:$ doveadm -f json director map > director_user_map.json

2. Create a list of all users and save it to a file called usrlist.txt

3. Gather above lists to a proxy server

4. Populate geodb with users from the generated lists

   WARNING

   Running the migrate_start.py command will essentially create your cluster groups. See Palomar Configuration Settings cluster_default_group_count

   # Decompress required scripts
   proxy_server:$ gunzip /usr/share/doc/dovecot-pro-cluster/scripts/migrate-start.py.gz
   proxy_server:$ gunzip /usr/share/doc/dovecot-pro-cluster/scripts/migrate-finish.py.gz
   
   # Initialize groups
   proxy_server:$ doveadm cluster site init
   
   # Generate output file for import
   proxy_server:$ python3 /usr/share/doc/dovecot-pro-cluster/scripts/migrate-start.py \
     --director-info directors.json \
     --director-map-info director_user_map.json \
     --dns-socket /run/dovecot/dns-client \
     -p -o /tmp/output.json
   
   # Import Users Into GeoDB
   proxy_server:$ python3 /usr/share/doc/dovecot-pro-cluster/scripts/migrate-finish.py \
     -c /tmp/output.json -f /tmp/extra-users.list \
     --cassandra-nodes <space_separated_list_of_geodb_cassandra servers> \
     --cassandra-keyspace <cassandra_keyspace> \
     --cassandra-batch-size-limit 100

5. Check a user to confirm that backend is consistent from director and Palomar

   director_server:$ doveadm director status <user_id>
   proxy_server:$ doveadm cluster user status <user_id>

Enable Palomar

Your Dovecot installation is now ready for Palomar. The next steps will transition your routing from a Director-based architecture to a Proxy-based architecture.

• Remove the host extra field from the proxy passdb.
• Restart Dovecot.

After some time, the Controller will begin moving groups around to balance your cluster. It is also worth mentioning that enabling Dry Run mode at this stage can be helpful. This will log the actions the Controller would take without actually performing them.