Dovecot CE
Search K

Appearance

Dovecot Dictionary (dict) ​

Dovecot's lib-dict can be used to access simple key-value databases. This is used by, for example, last-login plugin and imap_metadata.

The dictionaries can be accessed either directly by the mail processes or they can be accessed via proxy processes.

Currently supported drivers are:

NameDescription
fileFlat Files
fsFS (lib-fs wrapper)
ldapLDAP (read only)
proxyProxy
redisRedis
sqlSQL

Connection Pooling ​

The SQL drivers keep a persistent connection open to the database after it's been accessed once. The connection is reused for other SQL lookups as long as their SQL settings are exactly the same. Opened SQL connections are currently never closed.

Drivers ​

Flat Files ​

The file will contain all the keys that are used. Not very efficient for large databases, but good for small ones such as a single user's quota.

dict_file_path

Default[None]
Valuestring

Path for the dictionary file.

Filesystem (lib-fs-wrapper) ​

This is a wrapper for lib-fs, which most importantly has the posix driver. Use the fs setting to configure the filesystem. For example:

dict fs {
  fs posix {
    prefix = /var/lib/dovecot/dict/
  }
}

This create a separate file under /var/lib/dovecot/dict for each key.

LDAP ​

LDAP support is very similar to sql support, but there is no write support.

Note that the LDAP driver must be used via proxy.

See LDAP authentication.

Configuration ​

dict_server {
  dict ldap {
    driver = ldap
    ldap_uris = ldap://{{LDAPHOST}}
    ldap_auth_dn = uid=testadmin,cn=users,dc=dovecot,dc=net
    ldap_auth_dn_password = testadmin
    ldap_timeout_secs = 5
    ldap_base = dc=dovecot,dc=net
    ldap_starttls = no
    ssl_client_require_valid_cert = no

    dict_map priv/test/home {
      ldap_filter = (&(homeDirectory=*)(uid=%{user}))
      value = %{ldap:homeDirectory}
    }
  }
}

LDAP Settings ​

dict_map_ldap_filter

Default[None]
Valuestring

The ldap filter to use to find the ldap entry.

This setting is required for ldap dict_map

dict_map_pattern

Default[None]
Valuestring

Pattern that is matched to the accessed dict keys. The dict_map filter name refers to this setting. If the pattern matches the key, this dict map (and no other) is used. The dict maps are processed in the order listed in the configuration file.

ldap_auth_dn

Default[None]
Valuestring

Specify the Distinguished Name (the username used to login to the LDAP server).

Leave it commented out to bind anonymously (useful with passdb_ldap_bind = yes).

Example: ldap_auth_dn = uid=dov-read,dc=example,dc=com,dc=.

ldap_auth_dn_password

Default[None]
Valuestring

Password for LDAP server. Used if ldap_auth_dn is specified.

ldap_base

Default[None]
Valuestring

LDAP base.

Settings variables can be used.

Example: ldap_base = dc=mail, dc=example, dc=org

ldap_debug_level

Default0
Valueunsigned integer

LDAP library debug level as specified by LDAP_DEBUG_* in ldap_log.h.

Value -1 means everything.

You may need to recompile OpenLDAP with debugging enabled to get enough output.

ldap_max_idle_time

Default[None]
Valuetime

Disconnect from LDAP server after connection has been idle for this many seconds.

ldap_scope

Defaultsubtree
Valuestring
Allowed Valuesbaseonelevelsubtree

This specifies the search scope.

ldap_starttls

Defaultno
Valueboolean

Set to yes to use TLS to connect to the LDAP server.

ldap_uris

Default[None]
Valuestring

LDAP URIs to use.

Configure this setting to specify what LDAP server(s) to connect to.

The URIs are in syntax protocol://host:port.

Example: ldap_uris = ldaps://secure.domain.org

ssl_cipher_list

DefaultALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@STRENGTH (for ssl_server, empty for ssl_client)
Valuestring
See Also

The list of SSL ciphers to use for TLSv1.2 and below connections, in order of preference. Use ssl_cipher_suites for TLSv1.3 connections.

You do not need to edit this setting in order to disable specific SSL protocols; that is best done with ssl_min_protocol instead.

This setting is used for both incoming and outgoing SSL connections.

ssl_client_ca_dir

Default[None]
Valuestring
See Also

The directory where trusted SSL CA certificates can be found. For example /etc/ssl/certs. These certificates are used only for outgoing SSL connections (e.g. with the imapc driver).

For extra security you might want to point to a directory containing certificates only for the CAs that are actually needed for the server operation instead of all the root CAs.

ssl_client_ca_file

Default[None]
ValueFile
See Also

File containing the trusted SSL CA certificates. For example /etc/ssl/certs/ca-bundle.crt.

These certificates are used only for outgoing SSL connections (e.g. with the imapc driver).

Note that this setting isn't recommended to be used with large CA bundles, because all the certificates are read into memory. This leads to excessive memory usage, because it gets multiplied by the number of imap processes. It's better to either use ssl_client_ca_dir setting or use a CA bundle that only contains the CAs that are actually necessary for the server operation.

ssl_client_cert_file

Default[None]
ValueFile
See Also

Public SSL certificate used for outgoing SSL connections. This is generally needed only when the server authenticates the client using the certificate.

ssl_client_key_file is also needed for the private certificate.

Example:

ssl_client_cert_file = /etc/dovecot/dovecot-client.crt
ssl_client_key_file = /etc/dovecot/dovecot-client.key

ssl_client_require_valid_cert

Defaultyes
Valueboolean
See Also

Require a valid certificate when connecting to external SSL services?

ssl_curve_list

Default<defaults from the SSL library>
Valuestring
See Also

Colon separated list of elliptic curves to use, in order of preference. An empty value uses the defaults from the SSL library.

This setting is used for both incoming and outgoing SSL connections.

Example:

ssl_curve_list = P-521:P-384:P-256

ssl_min_protocol

DefaultTLSv1.2
Valuestring
See Also

The minimum SSL protocol version Dovecot accepts.

This setting is used for both incoming and outgoing SSL connections.

Supported values are:

ANY

WARNING

This value is meant for tests only. It should not be used in any deployment of any value/relevance.

TLSv1
Support TLSv1+. (TLSv1 deprecated: RFC 8996)
TLSv1.1
Support TLSv1.1+. (TLSv1.1 deprecated: RFC 8996)
TLSv1.2
Support TLSv1.2+.
TLSv1.3
Support TLSv1.3+.
LATEST
Support only the latest version available.

Examples ​

To map a key to a search:

dict_map priv/test/mail {
  ldap_filter = (&(uid=%{user})(mail=*))
  ldap_base = ou=container,dc=domain
  value = %{ldap:mail}
}

To do a more complex search:

dict_map priv/test/mail/$location {
  ldap_filter = (&(uid=%{user})(mail=*)(uid=%{pattern:location}))
  ldap_base = ou=container,dc=domain
  value = %{ldap:mail}
}

Proxy ​

The proxy driver performs dictionary accessing via the Dictionary Proxy Process. (The dict processes exist only if dict proxying is used.) This is especially useful with drivers where their initialization is relatively expensive, such as SQL. The dict processes will perform connection pooling.

dict_proxy_idle_timeout

Default[None]
Valuetime (milliseconds)

How long to keep the connection open to dict server before disconnecting. 0 means immediate disconnection after finishing the operation.

dict_proxy_name

Default[None]
Valuestring
See Also

Name of the dict to access in the dict server. This refers to the dict_name setting.

dict_proxy_slow_warn

Default5s
Valuetime (milliseconds)

Log a warning about dict lookups that take longer than this interval.

dict_proxy_socket_path

Defaultdict
Valuestring

Points to the dict server's UNIX socket. The path is relative to the the base_dir setting. This should be changed to dict-async if the dict driver supports asynchronous lookups (e.g. ldap, pgsql, cassandra, NOT mysql). The dict-async service allows more than one client, so this configuration prevents creating unnecessarily many dict processes.

Redis ​

The Redis driver is recommended to be used via proxy to support connection pooling.

WARNING

Currently using Redis without proxying may cause crashes.

redis_expire

Defaultinfinite
Valuetime

Expiration value for all keys.

redis_host

Default127.0.0.1
Valuestring

Redis server host.

redis_key_prefix

Default[None]
Valuestring

Prefix to add to all keys.

redis_password

Default[None]
Valuestring

Redis server password.

redis_port

Default[None]
ValuePort Number

Redis server port.

redis_request_timeout

Default30s
Valuetime (milliseconds)

How long to wait for answer before aborting request.

redis_socket_path

Default[None]
Valuestring

UNIX socket path to the Redis server. This is preferred over redis_host if both are set.

SQL ​

WARNING

Note that the SQL driver must be used with proxy.

dict_map_expire_field

Default[None]
Valuestring

Field in the SQL table to use for tracking dict key expiration. This field is optional if no expiration is used by the code accessing the dict map.

dict_map_pattern

Default[None]
Valuestring

Pattern that is matched to the accessed dict keys. The dict_map filter name refers to this setting. If the pattern matches the key, this dict map (and no other) is used. The dict maps are processed in the order listed in the configuration file.

dict_map_sql_table

Default[None]
Valuestring

SQL table to use for accessing this dict map.

dict_map_username_field

Default[None]
Valuestring

Field in the SQL table to use for accessing private dict keys in this dict map. This setting is optional if only shared keys are accessed.

SQL Mapping ​

The SQL database fields are mapped into dict keys using the dict_map setting. When a dict lookup or update is done, Dovecot goes through all the maps and uses the first one whose pattern matches the dict key.

For example when using dict for a per-user quota value the map looks like:

dict_map priv/quota/storage {
  sql_table = quota
  username_field = username
  value_field quota_bytes {
  }
}

  • The dict key must match exactly priv/quota/storage. The dict keys are hardcoded in the Dovecot code, so depending on what functionality you're configuring you need to know the available dict keys used it.

  • This is a private dict key (priv/ prefix), which means that there must be a username_field. The username_field is assumed to be (at least part of) the primary key. In this example we don't have any other primary keys.

  • With MySQL the above map translates to SQL queries:

    • SELECT quota_bytes FROM quota WHERE username = '$username_field'
    • INSERT INTO quota (username, quota_bytes) VALUES ('$username_field', '$value') ON DUPLICATE KEY UPDATE quota_bytes='$value'

You can also access multiple SQL fields. For example acl_sharing_map can contain:

dict_map shared/shared-boxes/user/$to/$from {
  sql_table = user_shares
  value_field dummy {
  }

  key_field from_user {
    pattern = $from
  }
  key_field to_user {
    pattern = $to
  }
}

  • The acl_sharing_map always uses 1 as the value, so here the value is called dummy.

  • The SQL from_user and to_user fields are the interesting ones. Typically the extra fields would be part of the primary key.

  • With MySQL the above map translates to SQL queries:

    • SELECT dummy FROM user_shares WHERE from_user = '$from' AND to_user = '$to'
    • INSERT INTO user_shares (from_user, to_user, dummy) VALUES ('$from', '$to', '$value') ON DUPLICATE KEY UPDATE dummy='$value'

SQL dict with mail_attribute ​

It's possible to implement mail_attribute also with SQL dict.

WARNING

Using shared attributes in mail_attribute requires the mailbox GUID to be unique between users. This is not the case when mails were migrated via imapc, because it uses a hash of the mailbox name as the GUID. So every migrated user would have exactly the same INBOX GUID, preventing the use of dict-sql. It is currently not possible to add a username as an additional unique identifier.

# CREATE TABLE mailbox_private_attributes (
#   username VARCHAR(255),
#   mailbox_guid VARCHAR(32),
#   attr_key VARCHAR(255),
#   attr_value TEXT,
#   PRIMARY KEY (username, mailbox_guid, attr_key)
# )
dict_map priv/$mailbox_guid/$key {
  sql_table = mailbox_private_attributes
  username_field = user
  value_field attr_value {
  }

  key_field attr_key {
    pattern = $key
  }
  key_field mailbox_guid {
    pattern = $mailbox_guid
  }
}

# CREATE TABLE mailbox_shared_attributes (
#   mailbox_guid VARCHAR(32),
#   attr_key VARCHAR(255),
#   attr_value TEXT,
#   PRIMARY KEY (mailbox_guid, attr_key)
# );
dict_map shared/$mailbox_guid/$key {
  sql_table = mailbox_shared_attributes
  value_field attr_value {
  }

  key_field attr_key {
    pattern = $key
  }
  key_field mailbox_guid {
    pattern = $mailbox_guid
  }
}

Dictionary Proxy Process ​

Dict server is used for providing dictionary access via server processes instead of doing it directly from whichever process wants to access the dictionary. This is useful for some drivers with relatively high connection cost (e.g. sql), but not necessarily for others (e.g., redis.

When a mail process uses the dict proxy, it needs to have access the dict UNIX socket. By default only the dovecot user has access to the dict socket, which doesn't typically work in any installation. However, giving too wide permissions by default might allow untrusted users to access the dict and cause problems.

If all users share a single UNIX UID (e.g. vmail), you could make the dict socket accessible only to it:

service dict {
  unix_listener dict {
    mode = 0600
    user = vmail
  }
}

If you use multiple UNIX UIDs, you can add an extra group for all Dovecot mail processes. This works even if you have untrusted system users who have shell access to the server:

mail_access_groups = dovecot

service dict {
  unix_listener dict {
    mode = 0660
    group = dovecot
  }
}

However, it works with LDA only if it's started as root. If this isn't possible, use LMTP Server instead.

Settings ​

dict_server

Default[None]
ValueNamed Filter
See Also

Named filter for the dict server settings. Add the available named dicts for the dict server under this filter using the dict settings.

For example:

dict_server {
  dict quota {
    driver = sql
    # ...
  }
  dict acl {
    driver = file
    # ...
  }
}

Copyright © Open-Xchange GmbH