Dovecot Pro
2.3
main

Appearance

Note: This is pre-release documentation.
Please access https://doc.dovecotpro.com/latest/ for documentation on released versions.

Dovecot Pro: Getting Started ​

This page provides an overview of how to set up and configure a basic, minimal Dovecot Pro Palomar system.

It is designed to help system administrators become familiar with the Palomar architecture and the various Dovecot features, systems, and software packages required for this purpose.

IMPORTANT

It is the responsibility of Dovecot Pro administrators to design and build a configuration tailored to their specific use case, rather than re-using a generic template. For this reason, quick-start "sample configurations" are not provided.

This page should provide all information needed to create this initial configuration to fit your local environment.

Contact Open-Xchange Support if you have questions during your initial configuration process.

Dovecot Pro and Palomar ​

The single most important page to read and understand is the Dovecot Pro Product Description.

Read it carefully — then read it again.

The product description page describes the various components of Dovecot Pro, as well as the Palomar architecture. Once you're familiar with the concepts described on that page, you'll be equipped with the knowledge to configure your local installation and interpret the guidance presented on this page.

Palomar Architecture ​

Next, review Palomar Architecture to understand Palomar, the architecture at the core of Dovecot Pro 3.x.

Release Notes ​

Finally, read the Release Notes for (at least) the latest Dovecot Pro release.

The Release Notes serve as the official source for information on changes and improvements in new versions.

Even if some details seem unfamiliar now, reading them early in your educational process will help you get used to the types of updates included in future releases. These notes often contain essential updates requiring your attention.

The Dovecot carefully curates this information to ensure it is valuable to admins and it serves as the primary knowledge base for how the product's evolution.

Prerequisites ​

External Services ​

You must setup and populate your user database for authentication.

For mail delivery, ensure that SMTP services are available for inbound and outbound mail delivery. Spam and antivirus (AV/AS) filtering are handled in these systems.

If you are deploying virtual machines, confirm adequate resource availability.

Hardware Requirements ​

WARNING

These are not sizing guidelines, but rather minimum required resources.

These sizing recommendations reflect typical historical customer usage, often influenced by the sizes of available VMs in local environments. It is possible to size components larger or smaller based on the deployment resources - there is no required sizing for any Dovecot component.

For sizing tailored to your local environment, OX Professional Services are available to assist.

A minimum Palomar installation requires the following Dovecot Pro provided components:

  • one Dovecot Pro Proxy
  • two Dovecot Pro Backends
  • one Dovecot Pro Cluster Controller container

These components may run on virtual machines.

You will require at least three nodes for a highly-available Cassandra cluster.

For storage hardware requirements, consult your storage provider's documentation or support.

Proxy ​

Each Proxy should have at least 4 CPU cores and 4 GiB of memory.

Backend ​

Each Backend should have at least 4 CPU cores and 32 GiB of memory.

Additionally:

Supported Operating Systems ​

See supported operating systems for the rules governing Operating System (OS) version support in Dovecot Pro releases.

The supported OS versions for a specific release are listed in the Release Notes.

Required System Users ​

Dovecot packages automatically create the required dovenull and dovecot user accounts.

An additional account for temporary user data is also required; typically vmail, which is assumed for this documentation.

User overview:

  • dovenull: used for login processes
  • dovecot: usd for Dovecot internal processes
  • vmail: used for user mail access

Distinct system users with distinct privileges are required for security.

See system users configuration.

Network Connectivity and Firewall Rules ​

Ensure Proxies are directly accessible to end users and are placed behind transparent load balancers as described in the Dovecot Pro Product Description.

Proxies MUST be able to:

  • Connect to all local-site Backends
  • Access the Cassandra database used for Palomar GeoDB
  • Communicate with Proxy pools in other sites (for multi-site configurations)

Backends MUST be able to access:

Proxies and Backends MUST be able to access your userdb and passdb for user authentication and configuration retrieval.

Cluster Controller MUST be able to access Cassandra for Palomar GeoDB.

Firewall Rules ​

INFO

This table lists the default ports for ALL Dovecot Pro services. Local configurations may differ.

ApplicationDirectionPortExplanation
ProxyInbound110POP3 access, STARTTLS
ProxyInbound143IMAP access, STARTTLS
ProxyInbound465Submission service, SSL
ProxyInbound587Submission service, STARTTLS
ProxyInbound993POP3 access, SSL
ProxyInbound995IMAP access, SSL
ProxyInbound4190ManageSieve, STARTTLS
ProxyOutbound110POP3 to backend
ProxyOutbound143IMAP to backend
ProxyOutbound587Submission service to backend
ProxyOutbound4190ManageSieve to backend
ProxyOutbound9042Cassandra access
ProxyOutbound9142Cassandra access, SSL
BackendInbound110POP3 access
BackendInbound143IMAP access
ProxyInbound465Submission service, SSL
BackendInbound587Submission service
ProxyInbound993POP3 access, SSL
ProxyInbound995IMAP access, SSL
BackendInbound4190ManageSieve access
BackendOutbound9042Cassandra access
BackendOutbound9142Cassandra access, SSL
Cluster ControllerInbound8443Management API
Cluster ControllerOutbound9042Cassandra access
Cluster ControllerOutbound9142Cassandra access, SSL

Storage

Consult your storage vendor for required storage access ports.

Time Synchronization ​

Dovecot REQUIRES all synchronized time across all components.

Use a time sync service such as systemd-timesyncd or ntpd to avoid issues like Time Moved Backwards Error.

See Time Synchronization.

Dovecot Pro Components ​

With your understanding of Dovecot Pro and the prerequisites in place, you're ready to begin installing and configuring each Dovecot Pro component.

This guide outlines one suggested path — installing and configuring components individually. This is a suggestion, not a requirement.

Broader Dovecot concepts (e.g., configuration syntax, repository setup) are introduced once and assumed throughout.

This guide assumes Dovecot Pro will handle and route IMAP and LMTP. Support for additional protocols is out of scope.

NOTE

This guide describes configuration of a single Palomar site. Multi-site setups are out of scope.

Proxy and Backend Shared Configuration ​

Dovecot is configured via /etc/dovecot/dovecot.conf. Configuration can be centralized in this file (RECOMMENDED for clarity and ease of support) or split into multiple included files.

See Dovecot Config File Syntax for syntax details.

TIP

Use doveconf(1) to inspect how Dovecot has actually parsed the configuration, helpful if it seems like some change isn't effective.

All Dovecot configurations MUST include:

See All Dovecot Settings.

Logging ​

See logging for logging configuration.

Service Configuration ​

Service settings, including process limits and session reuse, are controlled via the service configuration.

Dovecot Pro defaults to high-performance service settings. Modifications to this mode are typically unnecessary.

See services configuration for more details.

Statistics and Metrics ​

Dovecot exports internal events, referred to as "metrics". You can configure which metrics to expose via Event Filtering.

To enable default metrics:

doveconf
@metric_defaults = proxy    # For Proxy
@metric_defaults = backend  # For Backend

For further details, see Statistics.

OpenMetrics ​

To enable OpenMetrics support, configure an inet_listener for the stats service:

doveconf
service stats {
  inet_listener http {
    port = 9900
  }
}
Events Export ​

You can export events using event_exporter. See Event Export for details.

doveconf
# Create a JSON log exporter
event_exporter log-export {
  driver = log
  format = json
  time_format = rfc3339
}

# Export the metacache_user_clean_finished metric which is part of
# @metric_defaults=backend using the log-export configured above.
metric metacache_user_clean_finished {
  exporter = log-export
}

Security Best Practices ​

WARNING

This is a non-exhaustive list of security considerations.

Networking / Listening Ports ​
  • listen: Configures listening IP addresses
  • login_trusted_networks: Defines trusted IP addresses.
    • Backends must trust IP addresses of local site Proxies. In multi-site environments, Proxies must trust connections from remote site Proxies.
Authentication ​

Avoid using auth_allow_cleartext, which allows insecure authentication from any source. Instead, restrict plaintext authentication to trusted networks using login_trusted_networks and enforce TLS-secured connections between all nodes.

Storing Secrets ​

Passwords and secrets should be stored in root-readable-only files.

Typically dovecot.conf is world-readable. Although it could be set readable only by root, this might cause issues in some situations, such as trying to execute dovecot-lda(1) or doveadm(1) as non-root. Instead, store secrets via environment variables.

For example, to store the authentication master password for a Backend:

doveconf
passdb static {
  fields {
     password = $ENV:MASTER_PASSWORD
  }
}

To securely set the environment variables, use the Environment setting in a systemd drop-in file, which is readable only by root. See the systemd documentation.

Alternatively, include a root-readable file:

doveconf
!include_try dovecot-secrets.conf

If unreadable, this inclusion is silently skipped.

Proxies ​

The Proxy's main function is initial authentication/authorization and user identity normalization. Dovecot supports proxying IMAP, POP3, Submission, LMTP, ManageSieve, and doveadm connections to other hosts.

Proxies directly expose publicly available services and handle initial client connections. They make a user database lookup to the customer's identity management or authentication system (e.g., LDAP) to authenticate and authorize the user, and to lookup user-specific routing parameters.

Proxies are usually configured to handle SSL/TLS encryption, including the SSL certificate management. This may also be done by the external load balancer in front of the Proxies, but STARTTLS commands cannot be used in that case.

Authentication and user identity normalization MUST be done at this layer. Palomar assumes the user has been authorized in all layers below the Proxy.

After authentication, sessions are routed to the site where the user is currently assigned.

The cluster service, which runs on the Proxies, makes sure that a user’s data is not concurrently accessed by multiple Backends. This is required to optimize performance and to avoid seeing stale user data.

Proxies are stateless allowing any of them to be removed or become unavailable without end-user impact. A user's session may be terminated on the client, but this is an expected event in mail access protocols and transparent client reconnection will re-enable the session.

Proxies are connected to:

  • the customer's authentication systems (passdb/userdb) to authenticate the platform and (optionally) enforce routing decisions.
  • (optionally) OX Abuse Shield to apply authentication policy.
  • Palomar GeoDB to track user routing inside the Palomar platform.
  • Backends in order to route authenticated users to the system that will handle the mail session.
  • external load-balancer layers in foreign sites to route connecting users that are not being serviced by the local site.

The Proxies do NOT need to connect to mail storage, backends in foreign sites, or any other Proxies directly.

Installation ​

Proxies are configured as part of the base Dovecot software.

Required Dovecot Packages ​

WARNING

Proxies must understand proxying-related Dovecot features, especially doveadm commands.

Thus, packages like FTS are required even if the Proxy itself does not process mail.

Install Dovecot Pro from the repository listed under your OS in the Release Notes.

Minimum required package list:

dovecot-pro-core
dovecot-pro-cassandra-plugin
dovecot-pro-cluster
dovecot-pro-fts
dovecot-pro-imapd
dovecot-pro-lmtpd
dovecot-pro-lua
dovecot-pro-obox
dovecot-pro-pigeonhole

Configuration ​

INFO

See the common configuration section above for general Dovecot requirements.

Proxy Authentication ​

Authentication configuration — generally tied to an installation's existing IDM and user databases — is often the most complex part of a Dovecot setup.

NOTE

Dovecot Pro does not provide IDM or user databases. The customer must supply these systems. Dovecot Pro is designed only to integrate with these systems.

See:

Dovecot natively supports a variety of authentication databases (e.g., LDAP authentication). If local authentication requires an unsupported database, or requires customization for the local environment, the Lua authentication database driver should be used.

Proxying to Backends ​

passdb must return the proxy=yes extra field and specify how to authenticate to Backends. There are two supported methods:

  1. Forward the user-given password (or OAUTH token) to the remote server. This is done by returning pass=%{password} and proxy_mech=%{mechanism} extra fields.

    • This doesn't work if any non-cleartext, non-token-based authentication mechanisms are used, because they prevent such password forwarding by design.
    • proxy_mech is needed only if both OAUTH and cleartext mechanisms are enabled.

  2. Login to the remote server using a master password. This is done by returning pass=master_secret extra field. This allows client to use also non-cleartext authentication.

Cluster ​

See Palomar Proxy Configuration for configuring Palomar for Proxy, including the monitoring users.

Doveadm ​

Doveadm is a useful protocol for executing Dovecot administration commands. Some of these are "mail commands" that work on user data. The cluster service also executes some of these commands internally. If these commands are run on the proxy, they are automatically proxied to the user's correct backend.

See Doveadm Configuration. To expose commands via HTTP, refer to Doveadm HTTP API.

HAProxy ​

If HAProxy (or compatible load balancer) is used in front of the Proxies, see Palomar Configuration for necessary trust configuration.

Mail Plugins ​

Some mail plugins offer doveadm commands that can be proxied to Backends. Enable these commands on Proxies by loading the plugins:

mail_plugins = obox quota fts fts_dovecot

Protocols ​

Configure enabled protocols:

protocols = imap pop3 lmtp submission managesieve

LMTP ​

By default, Dovecot Pro's LMTP service listens on port 24.

Cassandra & GeoDB ​

See Palomar GeoDB Configuration.

SSL/TLS ​

See SSL for configuring SSL/TLS on Proxies.

Backends ​

The Backend does the primary work of reading and writing mails to storage and handling the bulk of the mail protocol interaction with the client.

The Backends are organized as a pool of independent nodes. A user is not permanently assigned to a specific Backend. However, due to the performance and load reasons, the platform is designed to allow users to move between Backends.

Backends are connected to:

The Backends do NOT need to connect to Backends on foreign sites, or any Proxies.

Backend states ​

Each backend can be in one of the pre-defined states at each point in time:

  • online: Backend is functional and active in the site. Users are routed to the backend.
  • offline: Backend is active in the site but has been temporarily deactivated by the automation based on the outcome of Health Check. Offline backends can still serve users but proxies don't route actual users to them. Instead, Dovecot proxies probe them with test accounts to check if they are healthy again and are automatically set to online again if the test passes.
  • standby: Backend is manually taken out of service and won't automatically change status to online. This mode is mostly intended for admins to perform maintenance or fleet management operations.

Installation ​

Backends are also configured as part of the base Dovecot Pro software installation.

Required Dovecot Packages ​

Install Dovecot Pro from the repository listed under your OS in the Release Notes.

Minimum required package list:

dovecot-pro-core
dovecot-pro-cassandra-plugin
dovecot-pro-cluster
dovecot-pro-fts
dovecot-pro-imapd
dovecot-pro-lmtpd
dovecot-pro-lua
dovecot-pro-obox
dovecot-pro-pigeonhole
dovecot-pro-sqlite

Configuration ​

INFO

See the common configuration section above for general Dovecot requirements.

Authentication ​

Backend authentication is determined by how the Proxy is configured to authenticate against the Backend. See Proxy Authentication.

See also:

Palomar (Cluster) ​

Refer to Palomar Backend Configuration for configuring Palomar for the Backend role.

TIP

Remember to configure the monitoring users and userdb extra fields.

Doveadm ​

See Doveadm Configuration for how to configure doveadm for Backends.

FTS Settings ​

Full Text Search (FTS) configuration details are available at:

Mail Settings ​

For more details please refer to Obox Configuration. Key settings include:

Mail Plugins ​

Dovecot Pro relies heavily on its plugin system. The following plugins are mandatory for Dovecot Pro:

doveconf
mail_plugins = obox fts fts_dovecot

To view all available plugins, see the "Dovecot Core -> Plugins" and "Pro Plugins" lists in the documentation sidebar.

Quota ​

To prevent excessive storage usage by end users, it is recommended to configure a quota. See quota plugin for details.

Protocols ​

Configure enabled protocols:

protocols = imap pop3 lmtp submission managesieve

SSL ​

To enable SSL Encryption and configure Certificate Authorities, see SSL.

Storage ​

Dovecot storage configuration involves defining how to manage and access email and index data. As Storage backend it is suggested to use a S3 compatible Storage or AWS S3 see AWS S3 and S3 Compatible Storage for more details on the S3 Storage options.

Additionally Dovecot Pro requires a Cassandra cluster which is used via the dictionary functionality in Dovecot Pro. The distributed and scalable NoSQL database is used to support fast listings of directories which are too expensive or too slow when directly asking the S3 storage for it. The feature of supporting the storage with a dict is called Dictmap in Dovecot Pro. See Cassandra for more details on Cassandra and Dovecot Pro. For more details on product description see Dovecot Pro Product Description.

Make sure that the obox plugin is enabled before attempting to configure storage.

doveconf
mail_plugins {
  obox = yes
}

For more general information on Storage and Storage support please refer to dictmap.

Dictmap Configuration ​
  1. Configure a Cassandra cluster and create the keyspace mails and the needed tables see Cassandra Keyspace/Tables.
  2. Configure Dovecot Pro with a dict-server to use this Cassandra cluster
  3. Provide AWS-S3 or a S3-compatible storage and configure Dovecot Pro to use it.

Configure Dovecot Pro to use Cassandra

doveconf
# Load suggested default settings for dictmap and configure your Cassndra hosts
@fs_dictmap_defaults = cassandra
cassandra_hosts = 10.2.3.4 10.3.4.5 10.4.5.6

For more Cassandra configuration options please refer to Cassandra configuration.

S3 Storage Configuration ​

There are two storage driver options for S3 aws-s3 and s3. The aws-s3 driver is supposed to be used with AWS-S3 for other S3 compatible storages it is suggested to use the s3 driver.

The examples below use @fs_defaults. It defaults to:

Click to show @fs_defaults = aws-s3
doveconf
  fs_compress_write_method = zstd
  obox {
    fs fscache {
      path = /var/cache/mails/%{user | sha1 % 4}
      log_path = /var/cache/mails-%{user | sha1 % 4}.log
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_objectid_prefix = %{user}/mails/
    }
    fs aws-s3 {
    }
  }
  metacache {
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_passthrough_paths = full
    }
    fs aws-s3 {
    }
  }
Click to show @fs_defaults = s3
doveconf
  fs_compress_write_method = zstd
  obox {
    fs fscache {
      path = /var/cache/mails/%{user | sha1 % 4}
      log_path = /var/cache/mails-%{user | sha1 % 4}.log
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_objectid_prefix = %{user}/mails/
    }
    fs s3 {
    }
  }
  metacache {
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_passthrough_paths = full
    }
    fs s3 {
    }
  }

Note especially that the defaults use /var/cache/mails directory, which must be created and be writable to the mail_uid = vmail user.

Configuration Example for the aws-s3 driver using IAM configuration:

doveconf
# BUCKET_NAME: Storage bucket name to use.
# REGION: AWS region to use for storage.
# S3ACCESS: IAM role to use for storage access.
@fs_defaults = aws-s3
fs_s3_url = https://{{BUCKET_NAME}}.s3.{{REGION}}.amazonaws.com/
fs_s3_region = {{REGION}}
fs_s3_auth_role = {{S3ACCESS}}

For more details about IAM configuration please refer to IAM Authentication

Configuration Example for the s3 driver:

doveconf
# S3_STORAGE_URL: URL to S3 compatible storage
# BUCKET_NAME: S3 Storage bucket name to use.
# REGION: S3 region to use for storage.
# ACCESSKEY: S3 AccesskeyId to use for storage access.
# SECRET: S3 SecretKey to use for storage access.
@fs_defaults = s3
fs_s3_url = https://{{S3_STORAGE_URL}}/
fs_s3_access_key = {{ACCESSKEY}}
fs_s3_secret = {{SECRET}}
fs_s3_bucket = {{BUCKET_NAME}}
fs_s3_region = {{REGION}}
Compression ​

INFO

Compression is enabled by default when using @fs_defaults = s3|aws-s3 with fs_compress_write_method = zstd

doveconf
metacache {
  fs compress {
  }
  fs dictmap {
    storage_passthrough_paths = full
  }
  fs s3 {
  }
}

See this documentation for supported algorithms and their settings: fs-compress plugin. For some more information on Compression please refer to Compression

Data Encryption ​

It is recommended to use fs_crypt to encrypt mail data in rest at storage.

INFO

Using fs crypt and compress will leave mails uncompressed and unencrypted to local fs cache. This is a designed trade-off between performance and security.

INFO

Encryption is part of the @fs_defaults = s3|aws-s3 and is enabled by adding crypt_global_private_key.

To use fs crypt, You need to generate a keypair using openssl. See Encryption.

doveconf
crypt_global_public_key_file = /etc/dovecot/public.pem
crypt_global_private_key main {
  crypt_private_key_file = /etc/dovecot/private.pem
}
FTS Storage configuration ​

When Dovecot Pro FTS (Dovecot FTS Plugin, FTS Settings) is configured and enabled the FTS index files are stored in the same storage as mails or index files. The following example uses the s3 driver globally configured.

Configuration Example for storing fts index files using the s3 driver:

doveconf
# Enable fts and fts_dovecot plugins
mail_plugins {
  fts = yes
  fts_dovecot = yes
}
# Configure a fts storage using s3:
@fts_fs_defaults =  s3

INFO

This relies on having a fs_s3_url and other needed s3 driver configuration configured globally already

Namespace/Mailbox Configuration ​

Enable default INBOX namespace and English language mailbox names with mailbox_special_use flags added:

doveconf
@mailbox_defaults = english

To configure non-default namespaces, refer to Namespaces.

IMAP ​

See IMAP server.

LMTP ​

The LMTP service listens on port 24 by default.

For additional details, see LMTP Server.

You may want to adjust postmaster_address.

Sieve ​

To enable Sieve filtering capabilities, see Sieve installation.

Cluster Controller ​

The Cluster Controller component manages the Palomar site's cluster state.

Each site must run one Controller, which handles:

While a Controller's failure does not cause immediate system issues, it should be restored promptly.

Deployment Methods ​

See Cluster Controller Installation.

Configuration ​

See Cluster Controller Configuration.

Monitoring ​

See Cluster Controller Monitoring.

Troubleshooting ​

If issues arise during installation or setup, check the logs for error messages and ensure all dependencies are operational.

Best Practices ​

For optimal performance and scalability, follow best practices for health checks, user management, and more.

A full list of recommendations is available at Palomar Administration.

Troubleshooting and Debugging ​

See Troubleshooting and Debugging.

Support (SLA) ​

See Dovecot Pro SLA.

System Testing ​

After deploying the basic system, perform initial verification tests to ensure correct operation. Testing is essential to validate each component’s integration.

Refer to testing Dovecot installation for guidance on performing:

  • Basic Dovecot service tests
  • Authentication and user login verification
  • Backend and Proxy functionality tests

Use dedicated test accounts to avoid impacting (potential) production users. It is also beneficial to maintain test users in your production system for future debugging and validation.

Once these tests have been done, you should test moving users with doveadm-cluster-user(1) command and ensure that everything still works.

Administration ​

NOTE

This is not a comprehensive administration guide. It provides a quick reference to basic and essential Dovecot Pro administration concepts.

Dovecot administration can be done using Doveadm utility. It can also be configured to provide JSON API, see Doveadm HTTP API.

After changing configuration files, apply changes with the doveadm reload command.

User Administration ​

Dovecot has no concept of internal users, so there are no direct user data manipulation commands.

However, Dovecot Pro does provide user-related tools:

Cluster Administration ​

Use doveadm-cluster(1) commands to manage the Palomar cluster.

Mailbox Administration ​

Use doveadm-mailbox(1) commands for mailbox management. These allow full control over user mailboxes.

For example, you can use doveadm mailbox list to list all mailboxes for a user.

Mail Administration ​

Dovecot provides various mail administration commands:

Events ​

Dovecot supports events for logging and metric generation. These events provide insights into system behavior without requiring verbose or debug-level logging. They also allow Dovecot operations data to be machine processed for analysis and storage.

For example, to log failed authentication attempts with events:

doveconf
event_exporter log {
  format = json
  time_format = rfc3339
}

metric auth_failures {
  exporter = log
  filter = event=auth_request_finished AND (NOT success=yes)
}

See also:

See Recommended Metrics on which metrics we recommend.

Optimizations ​

Once the system is fully deployed and validated, consider applying performance optimizations.

A (non-comprehensive) collection of common optimization practices is provided in Dovecot Optimizations. These include tuning for speed, resource efficiency, and service robustness.

Congratulations! ​

If you have reached this point, you should now have a basic functioning Palomar deployment.

Dovecot Pro offers many features not covered in this quick-start guide. Explore the full documentation or contact your Account Manager to learn more about advanced capabilities and integrations.

Revision: 455bfe4

Last updated:

Copyright © Open-Xchange GmbH