Dovecot dsync Replication: Standby Setup, Verification, and Failover

The single-instance risk and what dsync solves

A single Dovecot server is a single point of failure. If the host or its storage dies, users lose mailbox access until the server is rebuilt. Dovecot's dsync replication keeps a standby server in near real-time sync so you can promote it quickly. This guide covers the task: pairing the servers, proving the replication works, and recovering after a failure.

Desired outcome

Maintain a standby Dovecot server that mirrors user mailboxes from a primary, allowing failover with minimal data loss. The standby should present the same users, folders, and message state, limited only by the replication interval.

Prerequisites

• Identical Dovecot builds. Both servers must run the exact same Dovecot version and plugin set. dsync speaks a binary protocol; a mismatch can cause sync failures or silent divergence.
• Same mailbox layout. Use the same mail location driver (for example, Maildir or mdbox) and the same namespace hierarchy on both hosts.
• Network path. TCP connectivity between the nodes on the dsync port (default 12345).
• Administrative access. Root or sudo rights to edit /etc/dovecot/dovecot.conf and /etc/dovecot/dovecot-dsync.conf on both machines.
• Local storage on each node. dsync synchronizes mailbox state over TCP. It does not require shared storage between the servers; each node keeps its own mail data and index files.

Focused procedure

Enable the dsync service and define the remote target

On both servers, ensure the dsync service is listening. Add or confirm the following block in /etc/dovecot/dovecot.conf:

service dsync {
  inet_listener dsync {
    port = 12345
  }
}

Restart Dovecot to apply the change on both hosts:

sudo systemctl restart dovecot

Expected check: systemctl status dovecot reports active (running) on each server.

On the primary, configure the replication target in /etc/dovecot/dovecot-dsync.conf. Point dsync at the standby and require TLS so credentials are protected:

dsync_remote = tcp:backup.example.com:12345

Replace backup.example.com with the standby's resolvable hostname or IP address. Configure a dedicated replication user in your passdb and enforce TLS on the dsync listener so authentication uses PLAIN over an encrypted channel rather than plaintext.

Run the initial full synchronization

Execute the first full sync from the primary to the standby. Run as root or a user with Dovecot admin rights:

sudo doveadm dsync -R -u [contact removed] tcp:backup.example.com:12345

Replace [contact removed] with the mailbox you are replicating. Test with a single mailbox before using -u '*' to sync all users. The -R flag reverses direction when run from the standby; when run on the primary without -R, it pushes changes to the remote. The command should exit with status 0 and produce no error output.

Expected checks

• Clean completion. The initial sync command returned exit code 0 with no error text.
• UIDVALIDITY match. On each server, run:
  sudo doveadm mailbox status -u [contact removed] uidvalidity INBOX
  The value must match on both sides. A mismatch means dsync treats the folders as unrelated and will not merge them.
• Test message arrival. Send a message to the primary mailbox. On the standby, verify it arrived:
  sudo doveadm fetch -u [contact removed] mailbox INBOX
  The test message should appear with the same UID and flags as on the primary. The default replication interval is 30 seconds, so allow at least one interval before checking.
• Log review. Check Dovecot logs (/var/log/dovecot.log or the systemd journal) for dsync warnings or errors. A healthy sync produces no error-level entries.

Recovery and failover options

Promote the standby

If the primary fails, promote the standby by updating MX records or the load balancer to point to the standby IP. Keep the failed primary offline until it is repaired and resynced. Running both nodes independently creates a split-brain scenario where each accepts mail separately, making later reconciliation difficult.

Resync back to a repaired primary

After the primary is restored, resync any missed changes from the standby back to the primary. Run on the standby:

sudo doveadm dsync -R -u [contact removed] tcp:primary.example.com:12345

Or run on the primary without -R if you prefer to pull from the standby. Re-verify UIDVALIDITY before returning the primary to service.

Rebuild after drift

If the two sides have diverged—for example, because a mailbox was deleted on one node—empty the affected mailboxes on the standby and re-run the initial full sync. This is safer than attempting to merge conflicting state automatically.

Limitations and risks

dsync replicates mailbox contents and indexes, not configuration files, SSL certificates, or admin logs. Maintain separate backups for those artifacts. Because replication is near real time rather than synchronous, messages delivered in the final seconds before a primary crash may not reach the standby. Finally, dsync assumes both nodes run identical Dovecot builds; a version or plugin mismatch can break the protocol or cause silent data loss.