Search K
Appearance
Appearance
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.
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.
Next, review Palomar Architecture to understand Palomar, the architecture at the core of Dovecot Pro 3.x.
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.
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.
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:
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.
Each Proxy should have at least 4 CPU cores and 4 GiB of memory.
Each Backend should have at least 4 CPU cores and 32 GiB of memory.
Additionally:
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.
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 processesdovecot
: usd for Dovecot internal processesvmail
: used for user mail accessDistinct system users with distinct privileges are required for security.
See system users configuration.
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:
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.
INFO
This table lists the default ports for ALL Dovecot Pro services. Local configurations may differ.
Application | Direction | Port | Explanation |
---|---|---|---|
Proxy | Inbound | 110 | POP3 access, STARTTLS |
Proxy | Inbound | 143 | IMAP access, STARTTLS |
Proxy | Inbound | 465 | Submission service, SSL |
Proxy | Inbound | 587 | Submission service, STARTTLS |
Proxy | Inbound | 993 | POP3 access, SSL |
Proxy | Inbound | 995 | IMAP access, SSL |
Proxy | Inbound | 4190 | ManageSieve, STARTTLS |
Proxy | Outbound | 110 | POP3 to backend |
Proxy | Outbound | 143 | IMAP to backend |
Proxy | Outbound | 587 | Submission service to backend |
Proxy | Outbound | 4190 | ManageSieve to backend |
Proxy | Outbound | 9042 | Cassandra access |
Proxy | Outbound | 9142 | Cassandra access, SSL |
Backend | Inbound | 110 | POP3 access |
Backend | Inbound | 143 | IMAP access |
Proxy | Inbound | 465 | Submission service, SSL |
Backend | Inbound | 587 | Submission service |
Proxy | Inbound | 993 | POP3 access, SSL |
Proxy | Inbound | 995 | IMAP access, SSL |
Backend | Inbound | 4190 | ManageSieve access |
Backend | Outbound | 9042 | Cassandra access |
Backend | Outbound | 9142 | Cassandra access, SSL |
Cluster Controller | Inbound | 8443 | Management API |
Cluster Controller | Outbound | 9042 | Cassandra access |
Cluster Controller | Outbound | 9142 | Cassandra access, SSL |
Storage
Consult your storage vendor for required storage access ports.
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.
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.
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:
dovecot_config_version
as the first settingdovecot_storage_version
See All Dovecot Settings.
See logging for logging 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.
Dovecot exports internal events, referred to as "metrics". You can configure which metrics to expose via Event Filtering.
To enable default metrics:
@metric_defaults = proxy # For Proxy
@metric_defaults = backend # For Backend
For further details, see Statistics.
To enable OpenMetrics support, configure an inet_listener
for the stats service:
service stats {
inet_listener http {
port = 9900
}
}
You can export events using event_exporter
. See Event Export for details.
# 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
}
WARNING
This is a non-exhaustive list of security considerations.
listen
: Configures listening IP addresseslogin_trusted_networks
: Defines trusted IP addresses. 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.
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:
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:
!include_try dovecot-secrets.conf
If unreadable, this inclusion is silently skipped.
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 Proxies do NOT need to connect to mail storage, backends in foreign sites, or any other Proxies directly.
Proxies are configured as part of the base Dovecot software.
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
INFO
See the common configuration section above for general Dovecot requirements.
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.
Passdb must return the proxy=yes
extra field and specify how to authenticate to Backends. There are two supported methods:
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.
proxy_mech
is needed only if both OAUTH and cleartext mechanisms are enabled.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.
See Palomar Proxy Configuration for configuring Palomar for Proxy, including the monitoring users.
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.
If HAProxy (or compatible load balancer) is used in front of the Proxies, see Palomar Configuration for necessary trust configuration.
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
Configure enabled protocols:
protocols = imap pop3 lmtp submission managesieve
By default, Dovecot Pro's LMTP service listens on port 24.
See Palomar GeoDB Configuration.
See SSL for configuring SSL/TLS on Proxies.
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:
doveadm metacache pull
to pull index files when users are moved.The Backends do NOT need to connect to Backends on foreign sites, or any Proxies.
Backends are also configured as part of the base Dovecot Pro software installation.
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
INFO
See the common configuration section above for general Dovecot requirements.
Backend authentication is determined by how the Proxy is configured to authenticate against the Backend. See Proxy Authentication.
See also:
Refer to Palomar Backend Configuration for configuring Palomar for the Backend role.
TIP
Remember to configure the monitoring users and userdb extra fields.
See Doveadm Configuration for how to configure doveadm for Backends.
Full Text Search (FTS) configuration details are available at:
For more details please refer to Obox Configuration. Key settings include:
Dovecot Pro relies heavily on its plugin system. The following plugins are mandatory for Dovecot Pro:
mail_plugins = obox fts fts_dovecot
To view all available plugins, see the "Dovecot Core -> Plugins" and "Pro Plugins" lists in the documentation sidebar.
To prevent excessive storage usage by end users, it is recommended to configure a quota. See quota plugin for details.
Configure enabled protocols:
protocols = imap pop3 lmtp submission managesieve
To enable SSL Encryption and configure Certificate Authorities, see SSL.
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.
mail_plugins {
obox = yes
}
For more general information on Storage and Storage support please refer to dictmap.
mails
and the needed tables see Cassandra Keyspace/Tables.Configure Dovecot Pro to use Cassandra
# 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.
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:
fs_compress_write_method = zstd
obox {
fs fscache {
path = /var/cache/mails/%{user | sha1 % 4}
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 {
}
}
fs_compress_write_method = zstd
obox {
fs fscache {
path = /var/cache/mails/%{user | sha1 % 4}
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:
# 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:
# 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}}
INFO
Compression is enabled by default when using @fs_defaults = s3|aws-s3
with fs_compress_write_method = zstd
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
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.
crypt_global_public_key_file = /etc/dovecot/public.pem
crypt_global_private_key main {
crypt_private_key_file = /etc/dovecot/private.pem
}
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:
# 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
Enable default INBOX namespace and English language mailbox names with mailbox_special_use
flags added:
@mailbox_defaults = english
To configure non-default namespaces, refer to Namespaces.
See IMAP server.
The LMTP service listens on port 24 by default.
For additional details, see LMTP Server.
You may want to adjust postmaster_address
.
To enable Sieve filtering capabilities, see Sieve installation.
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.
See Cluster Controller Installation.
See Cluster Controller Configuration.
See Cluster Controller Monitoring.
If issues arise during installation or setup, check the logs for error messages and ensure all dependencies are operational.
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.
See Troubleshooting and Debugging.
See Dovecot Pro SLA.
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:
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.
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.
Dovecot has no concept of internal users, so there are no direct user data manipulation commands.
However, Dovecot Pro does provide user-related tools:
doveadm-auth(1)
: Test user authenticationdoveadm-user(1)
: Display user information and attributesdoveadm-pw(1)
: Generate user password hashesdoveadm-kick(1)
: Disconnect usersdoveadm-obox(1)
: Manage user data (including deleting data from system) for the obox mailbox formatUse doveadm-cluster(1)
commands to manage the Palomar cluster.
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.
Dovecot provides various mail administration commands:
doveadm-search(1)
: Search for mails within in user mailboxesdoveadm-fetch(1)
: Retrieve metadata on individual messagesdoveadm-expunge(1)
: Permanently delete messagesdoveadm-copy(1)
and doveadm-move(1)
: Transfer mail between mailboxesDovecot 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:
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.
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.
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.