Dovecot Pro Palomar Architecture

Dovecot Pro's Palomar Architecture replaces the earlier director-based clustering with a modern, scalable, and resilient cluster service.

This design enables:

• Load balancing between Proxies and Backends
• User stickiness, ensuring each user is routed consistently to the same Backend
• High availability across Backends and multi-site environments
• Load redistribution, allowing users to be actively balanced across Backends
• Multi-site support, enabling clusters to span multiple physical or virtual locations

The principal goal is to ensure that users are serviced by a single Backend at any given time, optimizing caching and performance.

In split-brain scenarios — particularly relevant with object storage and multi-site configurations — obox resolves conflicts by merging changes and synchronizing user and site data when connectivity is restored.

Overview

Sites

A "site" is a collection of co-managed servers controlled by a Cluster Controller.

• A single Palomar deployment can contain multiple sites.
• Multi-site support allows cross-site failover and load distribution.
• Sites can be virtual (contained within a data center).
  • Geo-redundant sites are only supported with Scality (sproxyd) storage.

Architecture Components

Dovecot Proxy

The Proxy handles initial client connections across IMAP, POP3, LMTP, Submission, ManageSieve, and doveadm protocols.

Responsibilities include:

• Authentication and userdb lookups
• Identity normalization
• TLS handshakes (if not handled upstream)
• Routing users to Backends

See: Dovecot Proxy.

INFO

Proxies are stateless and rely on the cluster service to ensure each user is consistently directed to a single Backend.

Dovecot Backend

The Backend executes session-level operations and communicates with storage.

See: Dovecot Backend.

Dovecot Cluster Controller

Controller manages the cluster state for a site.

See: Cluster Controller.

Shared Infrastructure

⚠️ TODO

Authentication

⚠️ TODO

Storage

Palomar uses the obox mailbox format, which is designed for consistency, performance, and reliability.

See: Storage.

GeoDB

A globally shared database (typically Cassandra) that tracks user assignments to Backends and sites. Proxies and Backends consult GeoDB to ensure consistent routing.

See: Palomar GeoDB.

OX Abuse Shield (Optional)

Integrates with the Proxy to enforce authentication policies and mitigate abuse.

See: OX Abuse Shield.

External Load Balancer

Distributes incoming traffic into the Proxy tier.

• Must preserve client IP transparency or support HAProxy PROXY Protocol v2.
• Proxies must remain separate from load balancers.

Functional Areas

1. Sites

• Managed by one Cluster Controller.
• Multiple Proxies and Backends register to the site.
• Multi-site support provides geographic redundancy and load distribution.

2. Users & Routing

• Palomar provides built-in functionality to manage users.
• Routing decisions and Backend assignments are tracked in GeoDB.
• Proxies consult GeoDB to route users consistently to the correct Backend.

3. Health Checking

• Controllers detect Backend health using test accounts (e.g., probe-%{backend_host}) that simulate normal user access.
• This ensures accurate detection of degraded or failed Backends.
• For configuration, see: Palomar Monitoring Users.

4. Administration

Administration is available via both doveadm cluster commands and a REST API exposed by the Controller.

Examples:

• Site operations: doveadm cluster site add, site init
• Backend operations: backend add, backend update status/load factor, backend evacuate

The REST API provides similar functionality for automation and scripting.

5. Statistics

• Controllers aggregate metrics for load balancing.
• Automatic redistribution is triggered when the Z-score difference between Backends crosses a defined threshold.
• Backends report success/failure metrics to Prometheus (part of the Controller service) for monitoring.

6. Balancing

• Controllers can automatically rebalance users to even load across Backends.
• Balancing respects retention periods (users remain on a Backend for at least one hour).
• Prometheus sampling must reach a sufficient threshold before redistribution is activated.
• See Palomar Load Rebalancing.

Logging

See Palomar Logging.