Template:Dovecot:Main Page BackendConf

Dovecot Pro Backend Configuration

See dovecot-backend.conf for the full example configuration file. This document explains the settings grouped to logical sections.

Note that this is not an exhaustive list of options that may need to be set for a Backend.

Generic Settings

protocols = imap pop3 smtp sieve

Protocols to enable.

verbose_proctitle = yes

Show state information in process titles (in “ps” output).

mail_log_prefix = "%s(%u)<%{session}>: "

Include the session string in all log messages to make it easier to match log lines together.

Authentication

Note that Proxy or Director already verifies the authentication (in the reference Dovecot architecture; password has been switched to a master password at this point), so we don’t really need to do it again. We could, in fact, even avoid the password checking entirely, but for extra security it’s still done in this document.

'auth_mechanisms = plain login

Enables the PLAIN and LOGIN authentication mechanisms. The LOGIN mechanism is obsolete, but still used by old Outlooks and some Microsoft phones.

service anvil {

  unix_listener anvil-auth-penalty {

    mode = 0

  }

}

Disable authentication penalty. Proxy/Director already handled this.

auth_cache_size = 100M

Specifies the amount of memory used for authentication caching (passdband userdb lookups).

login_trusted_networks = 10.0.0.0/24

Space-separated list of IP/network ranges that contain the Dovecot Directors. This setting allows Directors to forward the client’s original IP address and session ID to the Backends.

mail_max_userip_connections = 10

Maximum number of simultaneous IMAP/POP3 connections allowed for the same user from the same IP address (10 = 10 IMAP + 10 POP3)

ssl = no

disable_plaintext_auth = no

Proxy/Director already decrypted the SSL connections. The Backends will always see only plaintext connections.

LDAP Authentication

See http://wiki.dovecot.org/AuthDatabase/LDAP for more details.

passed {

  args = /etc/dovecot/dovecot-ldap.conf.ext

  driver = ldap

}

userdb {

  driver = prefetch

}

userdb {

  args = /etc/dovecot/dovecot-ldap.conf.ext

  driver = ldap

}

These enable LDAP to be used as passdb and userdb. The userdb prefetch allows IMAP/POP3 logins to do only a single LDAP lookup by returning the userdb information already in the passdb lookup. http://wiki.dovecot.org/UserDatabase/Prefetch has more details on the prefetch userdb. 

LDAP Backend Configuration

The included dovecot-ldap-backend.conf.ext can be used as template for the /etc/dovecot/dovecot-ldap.conf.ext. Its most important settings are:

hosts = ldap.example.com

dn = cn=admin,dc=example,dc=com

dnpass = secret

base = dc=example,dc=com

Configure how the LDAP server is reached.

auth_bind = yes

Use LDAP authentication binding for verifying users’ passwords.

blocking = yes

Use auth worker processes to perform LDAP lookups in order to use multiple concurrent LDAP connections. Otherwise only a single LDAP connection is used.

'pass_attrs = \

  =user=%{ldap:mailRoutingAddress}, \

  =password=%{ldap:userPassword}, \

  =userdb_quota_rule=*:storage=%{ldap:messageQuotaHard}k

Normalize the username to exactly the mailRoutingAddress field’s value regardless of how the pass_filter found the user. The userdb_quota_rule is used by userdb prefetch to return the userdb values. If other userdb fields are wanted, they must be placed to both user_attrs (without “userdb_” prefix) and pass_attrs (with “userdb_” prefix).

user_attrs = \

  =user=%{ldap:mailRoutingAddress}, \

  =quota_rule=*:storage=%{ldap:messageQuotaHard}

Returns userdb fields when prefetch userdb wasn’t used (LMTP & doveadm). The username is again normalized in case user_filter found it via some other means.

pass_filter = (mailRoutingAddress=%u)

user_filter = (mailRoutingAddress=%u)

How to find the user for passdb lookup.

iterate_attrs = mailRoutingAddress=user

iterate_filter = (objectClass= smiMessageRecipient)

How to iterate through all the valid usernames.

Mail Location Settings (Object Storage)

See http://wiki.dovecot.org/MailLocation for more details.

Note: these settings are assuming that message data is being stored in object storage (obox mailbox).  These settings should not be used if a block storage driver (e.g. mdbox) is being used. 

mail_home = /var/vmail/%2Mu/%u

Specifies the location for the local mail cache directory. This will contain Dovecot index files and it needs to be high performance (e.g. SSD storage).  Alternatively, if there is enough memory available to hold all concurrent users’ data at once, a tmpfs would work as well. The “%2Mu” takes the first 2 chars of the MD5 hash of the username so everything isn’t in one directory.

mail_uid = email

mail_gid = email

UNIX UID & GID which are used to access the local cache mail files.

mail_fsync = never

We can disable fsync()ing for better performance. It’s not a problem if locally cached index file modifications are lost.

mail_temp_dir = /tmp

Directory where downloaded/uploaded mails are temporarily stored to. Ideally all of these would stay in memory and never hit the disk, but in some situations the mails may have to be kept for a somewhat longer time and it ends up in disk. So there should be enough disk space available in the temporary filesystem.

mailbox_list_index = yes

Enable mailbox list indexes. This is required with obox format.

Namespace Settings

See http://wiki.dovecot.org/Namespaces for more details.

namespace inbox {

  prefix =

  separator = /

  inbox = yes

}

Configure the INBOX namespace with specified IMAP namespace prefix and separator. When migrating from an existing system the prefix and separator must match exactly what the old system used. Otherwise clients may download all mails again or become otherwise confused.

namespace inbox {

  mailbox Drafts {

    special_use = \Drafts

    auto = create

  }

mailbox Junk {

    special_use = \Junk

    auto = create   }

  mailbox Trash {

    special_use = \Trash

    auto = create

  }

  mailbox Sent {

    special_use = \Sent

    auto = create

  }

}

These can be used to automatically create some default folders for all users with auto=create settings. The autocreated folders aren’t automatically subscribed though, that can be done with auto=subscribe setting. The autocreated/autosubscribed folders can’t be deleted/unsubscribed by the users.

The special_use setting specifies the IMAP SPECIAL-USE (RFC 6154) flags for the folders. Some newer IMAP clients can use these to automatically configure themselves to use the server-provided default folder names. See http://imapwiki.org/SpecialUse

Obox Settings

mail_plugins = $mail_plugins box

Enable obox plugin.

mail_prefetch_count = 10

How many mails to download in parallel from object storage. A higher number improves the performance, but also increases the local disk usage and number of used file descriptors. This setting is also the default for obox_max_parallel_* settings below.

plugin {

  # Store object IDs to Dovecot indexes (will become default later)

  obox_use_object_ids = yes

  # How much disk space metacache can use before old data is cleaned up.   # This should usually fill up most of the available disk space.

  metacache_max_space = 200G

  # Avoid uploading indexes at the cost of more GETs on failures

  # (will become default later)

metacache_delay_uploads = yes

  # How often to upload modified indexes to object storage?   # This is done on background. Default 5 min.

  #metacache_upload_interval = 5min

  # If delayed index uploads are enabled, upload indexes anyway   # after this many mails have been saved. Default 10.

  #obox_max_rescan_mail_count = 10

  # Override mail_prefetch_count setting for write, copy and delete   # operations.

  #obox_max_parallel_writes = $mail_prefetch_count

  #obox_max_parallel_copies = $mail_prefetch_count

  #obox_max_parallel_deletes = $mail_prefetch_count

  # If user’s index cache was accessed max this many seconds ago, assume    # it’s up-to-date and there’s no need to refresh them from object storage.   # Default 2 seconds.

  metacache_close_delay = 2s

  # If activated, when an unexpected 404 is found when retrieving a   # message from object storage, Dovecot will rescan the mailbox by   # listing its objects.  If the 404-object is still listed in this query,   # Dovecot issues a HEAD to determine if the message actually exists.   # If this HEAD request returns a 404, the message is dropped from   # the index. The message object is not removed from the object   # storage.  THIS SHOULD NORMALLY NOT BE ACTIVATED.

  # obox_autofix_storage = no

}

The rest of the obox settings are specific to the object storage backend that is used.

fscache

plugin {

  obox_fs = fscache:1G:/var/cache/mails:…

}

All of the object storage Backends should be set up to use fscache with at least some amount of disk space, otherwise some operations will be very inefficient (such as IMAP client downloading a mail in small pieces). The fscache is also ideally large enough that when a mail is delivered, any IMAP and POP3 client that is actively downloading the mails should download it from the cache.

Other than that, the fscache doesn’t usually need to be very large. It’s more useful to give the extra disk space to metacache (obox_fs setting).

Note that if fscache sees cache write failures (e.g. out of disk space) those will cause client-visible errors. The disk space usage also isn’t strictly enforced due to race conditions, so if you set fscache limit to 1 GB it may temporarily grow above it. So make sure that the fscache always has some extra disk space available for writing (e.g. a 1 GB fscache mounted on a 1.1 GB mount point).

compress

plugin {

  obox_index_fs = compress:gz:6:…

}

All of the object storage backends should be set up to compress index bundle objects. This commonly shrinks the indexes down to 20-30% of the original size with gzip -6 compression. It’s possible to use also other compression algorithms. The level parameter must be between 1..9. See http://wiki.dovecot.org/Plugins/Zlib for the current list of supported algorithms.

Note: Currently, there is no compression auto-detection for index bundles.  Therefore, all index bundles must either be compressed (or uncompressed) in object storage; mixing and matching compressed index bundles is not possible automatically.

Email object (a/k/a message blob data) compression should be done with the zlib plugin instead of via the “compress” fs wrapper.  Example:

# See http://wiki.dovecot.org/Plugins/Zlib

mail_plugins = $mail_plugins lib

plugin {

  zlib_save = gz

  zlib_save_level = 6

}

Compression status of email object data is auto-detected.  Therefore, zlib_save may safely be added to a currently existing system; existing non-compressed mail objects will be identified correctly.

HTTP-based object storages

The HTTP-based object storages use an HTTP URL to specify how the object storage is accessed. The parameters are specified as URL-style parameters, such as http://url/?param1=value1&param2=value2. The parameters common to all object storages include:

• connect_timeout_msecs=<ms>: Timeout for establishing a TCP connection (default: 5s)

• max_connect_retries=<n>: Number of connect retries (default: 2)

• timeout_msecs=<ms>: Timeout for receiving a HTTP response (default: 10s)

• max_retries=<n>: Max number of HTTP request retries (default: 4)

• addhdr=<name>:<value>: Add the specified header to all HTTP requests. This can only be specified once. This may be useful for load balancing purposes.

Scality CDMI

mail_location = obox:%2Mu/%2.3Mu/%u:INDEX=~/:CONTROL=~/

We’ll use 2 + 3 chars of the MD5 of the username at the beginning of each object path to improve performance. These directories should be pre-created to CDMI. The index and control dirs have to point to the user’s home directory.

plugin {

  obox_fs = fscache:1G:/var/cache/mails:scality:http://scality-url/mails/?addhdr=X-Dovecot-

Hash:%2Mu/%2.3Mu&bulk_delete=1&bulk_link=1

  obox_index_fs = compress:gz:6:scality:http://scality-url/mails/?addhdr=X-Dovecot-

Hash:%2Mu/%2.3Mu&bulk_delete=1&bulk_link=1

  # With bulk-delete and bulk-link enabled, these can be large:

  obox_max_parallel_copies = 100

  obox_max_parallel_deletes = 100

}

The X-Dovecot-Hash header is important for CDMI load balancer stickiness.

Amazon S3

mail_location = obox:%2Mu/%2.3Mu/%u:INDEX=~/:CONTROL=~/

We’ll use 2 + 3 chars of the MD5 of the username at the beginning of each object path to improve performance. The index and control dirs have to point to the user’s home directory.

plugin {

  obox_fs = fscache:1G:/var/cache/mails:s3: https://ACCESSKEY:SECRET@BUCKETNAME.s3.amazonaws.com/

  obox_index_fs = compress:gz:6:s3: https://ACCESSKEY:SECRET@BUCKETNAME.s3.amazonaws.com/

}

Get ACCESSKEY and SECRET from http://aws.amazon.com/ -> My account -> Security credentials -> Access credentials. Create the BUCKETNAME from AWS Management Console -> S3 -> Create Bucket.

If the ACCESSKEY or SECRET contains any special characters, they can be %hex-encoded. Note that dovecot.conf handles %variable expansion internally as well, so % needs to be escaped as %% and ‘:’ needs to be escaped as %%3A.

Mail Event Logging

See http://wiki.dovecot.org/Plugins/MailLog for more details.

mail_plugins = $mail_plugins notify mail_log

Enable the mail_log plugin.

plugin {

  mail_log_events = delete undelete expunge copy mailbox_delete mailbox_rename

  mail_log_fields = uid box msgid size from

}

Log a line about events that may cause message to be deleted. This is commonly useful when debugging why users have lost messages.

Quota

See http://wiki.dovecot.org/Quota/Configuration for more details.

mail_plugins = $mail_plugins quota

Enable quota plugin for tracking and enforcing the quota.

protocol map {

  mail_plugins = $mail_plugins map_quota

}

Enable the IMAP QUOTA extension, allowing IMAP clients to ask for the current quota usage.

plugin {

  quota = count:User quota

Track the current quota usage in Dovecot’s index files.

  quota_vsizes = yes

Required by quota=count backend. Indicates that the quota plugin should use “virtual sizes” rather than “physical sizes” when calculating message sizes. 

  quota_warning = storage=100%% quota-warning 100 %u

  quota_warning2 = storage=95%% quota-warning 95 %u

  quota_warning3 = -storage=100%% quota-warning below %u

Configure quota warning scripts to be triggered at specific sizes. Note that %% needs to be written twice to avoid %variable expansion. For example, at 95% usage a warning email could be sent to user. At 100% an external SMTP database could be updated to reject mails directly. At -100% user allow mails again. The “quota-warning” means to connect to the quota-warning UNIX socket, which is a Dovecot script service described below. }

service quota-warning {

  executable = script /usr/local/bin/quota-warning.sh

  user = email

  unix_listener quota-warning {

  }

}

Example quota-warning service which executes quota-warning.sh script.

You may also want to use quota_clone plugin to keep track of all the users’ quotas in an efficient database. (It’s very slow to query every user’s quota from the index files directly.) See http://wiki.dovecot.org/Plugins/QuotaClone 

IMAP

imap_client_workarounds = tb-extra-mailbox-sep tb-lsub-flags

Enable some workarounds for Thunderbird.

POP3

See http://wiki.dovecot.org/POP3Server for more details.

pop3_no_flag_updates = yes

Improve performance by not updating the IMAP \Seen flag whenever downloading mails via POP3.

pop3_client_workarounds = outlook-no-nuls oe-ns-eoh

Enable some workarounds for Outlook clients so they won’t hang on unexpected data.

pop3_uidl_format = %g

Use message GUID as POP3 UIDL. For old mails their UIDLs must be migrated using the migration scripts.

LMTP & Sieve

postmaster_address = postmaster@%d

Email address to use in the From: field for outgoing email rejections. The %d variable expands to the recipient domain.

submission_host = smtp-out.example.com:25

SMTP server which is used for sending email rejects, Sieve forwards, vacations, etc. Alternatively, sendmail_path setting can be used to send mails using the sendmail binary.

protocol smtp {

  mail_plugins = $mail_plugins sieve

}

Enable Sieve plugin.