Dovecot Pro
Search K

Appearance

All Dovecot Settings ​

Settings ​

@cluster_defaults

Default[None]
ValueGroups Includes
Allowed Valuesproxybackend

Group that expands to various settings that are required for cluster to run in a proxy or backend.

@fs_defaults

Default[None]
ValueGroups Includes
Allowed Valuesaws-s3s3azuresproxydnfs
See Also
Pluginobox plugin

Group that expands to recommended obox plugin fs settings, including compression and encryption. Note that they use /var/cache/mails directory, which must be created and be writable to the mail_uid = vmail user. Also note that you must configure the encryption keys. See below for what the groups expand to.

INFO

@fs_defaults = 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 aws-s3 {
    }
  }
  metacache {
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_passthrough_paths = full
    }
    fs aws-s3 {
    }
  }
@fs_defaults = 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 {
    }
  }
@fs_defaults = azure 
  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 azure {
    }
  }
  metacache {
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_passthrough_paths = full
    }
    fs azure {
    }
  }
@fs_defaults = sproxyd 
  fs_compress_write_method = zstd
  obox {
    fs fscache {
      path = /var/cache/mails/%{user | sha1 % 4}
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
    }
    fs sproxyd {
    }
  }
  metacache {
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
    }
    fs sproxyd {
    }
  }
@fs_defaults = nfs 
  fs_compress_write_method = zstd
  obox {
    fs fscache {
      path = /var/cache/mails/%{user | sha1 % 4}
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs posix {
    }
  }
  metacache {
    fs compress {
    }
    fs crypt {
    }
    fs posix {
    }
  }

@fts_fs_defaults

Default[None]
ValueGroups Includes
Allowed Valuesaws-s3s3azuresproxydnfs
See Also
Pluginfts-dovecot plugin

Group that expands to recommended fts-dovecot plugin fs settings, compression and encryption. Note that they use /var/cache/fts directory, which must be created and be writable to the mail_uid = vmail user. Also note that you must configure the encryption keys. See below for what the groups expand to.

INFO

@fts_fs_defaults = aws-s3 
  fts dovecot {
    fs fts-cache {
    }
    fs fscache {
      path = /var/cache/fts/%{user | sha1 % 4}
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_passthrough_paths = full
      dict proxy {
        name = mails
        socket_path = dict-async
      }
    }
    fs aws-s3 {
    }
  }
@fts_fs_defaults = s3 
  fts dovecot {
    fs fts-cache {
    }
    fs fscache {
      path = /var/cache/fts/%{user | sha1 % 4}
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_passthrough_paths = full
      dict proxy {
        name = mails
        socket_path = dict-async
      }
    }
    fs s3 {
    }
  }
@fts_fs_defaults = azure 
  fts dovecot {
    fs fts-cache {
    }
    fs fscache {
      path = /var/cache/fts/%{user | sha1 % 4}
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      storage_passthrough_paths = full
      dict proxy {
        name = mails
        socket_path = dict-async
      }
    }
    fs azure {
    }
  }
@fts_fs_defaults = sproxyd 
  fts dovecot {
    fs fts-cache {
    }
    fs fscache {
      path = /var/cache/fts/%{user | sha1 % 4}
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs dictmap {
      dict proxy {
        name = mails
        socket_path = dict-async
      }
    }
    fs sproxyd {
    }
  }
@fts_fs_defaults = nfs 
  fts dovecot {
    fs fts-cache {
    }
    fs fscache {
      path = /var/cache/fts/%{user | sha1 % 4}
      size = 512 M
    }
    fs compress {
    }
    fs crypt {
    }
    fs posix {
    }
  }

@metric_defaults

Default[None]
ValueGroups Includes
Allowed Valuesproxybackend
See Also

Group that expands to recommended metric settings in proxies or backends.

CASSANDRA_GEODB_KEYSPACE

Default"d8s_cluster"
ValuePython String
Changes
  • Added: 3.0.1

Cassandra keyspace used for dovecot cluster.

CASSANDRA_LOAD_BALANCING_POLICY

Default"DCAwareRoundRobin"
ValuePython String
Allowed Values"RoundRobin""DCAwareRoundRobin"
Changes
  • Added: 3.0.1

Policy to use for cassandra load balancing. Determines how requests are distributed among nodes in the cluster.

  • "RoundRobin": evenly distributes queries across all nodes in the cluster, regardless of what datacenter the nodes may be in.
  • "DCAwareRoundRobin": Similar to "RoundRobinPolicy", but prefers hosts in the local datacenter and only uses nodes in remote datacenters as a last resort. If this policy is selected, number of remote hosts to use can be configured with CASSANDRA_USED_HOSTS_PER_REMOTE_DC.

CASSANDRA_LOCAL_DC

Default"d8s_cluster"
ValuePython String
Changes
  • Added: 3.0.1

Name of the local datacenter in Cassandra cluster.

CASSANDRA_PORT

Default9042
ValuePython Integer

The port Cassandra servers listen on.

CASSANDRA_PROTOCOL_VERSION

Default4
ValuePython Integer

Version of the cassandra protocol to be used.

CASSANDRA_SERVERS

Default"localhost"
ValuePython String

Comma separated list of Cassandra server endpoints.

CASSANDRA_SITE

Default"d8s_cluster"
ValuePython String
Changes

Name of the local datacenter in Cassandra cluster.

CASSANDRA_TLS_ENABLED

DefaultFalse
ValuePython Boolean

Whether to use TLS in Cassandra connections.

CASSANDRA_USED_HOSTS_PER_REMOTE_DC

Default0
ValuePython Integer
Changes
  • Added: 3.0.1

If CASSANDRA_LOAD_BALANCING_POLICY is set to "DCAwareRoundRobin", controls how many nodes in each remote datacenter will have connections opened against them.

CELERY_RESULT_EXPIRES_SECS

Default60
ValuePython Integer

Time to live of task results in Redis (in seconds).

CLUSTER_SITE

Default"dc1a"
ValuePython String

Palomar site this controller is responsible for. Must be the same site name configured in dovecot proxies with cluster_local_site.

CONTROLLER_API_URL

Default"http://localhost:8000"
ValuePython String

URL controller API runs on. The server will bind to this address and the admin UI uses this address to send the HTTP requests.

DRY_RUN

Default200
ValuePython Integer
Changes
  • Deprecated: 3.0.2

    Use feature state 'dryrun'.

Whether to enable DRY_RUN mode to log but not perform controller worker actions, such as: set_host_offline, set_host_online and move users.

GROUP_MOVE_FINISH_TIMEOUT_SECS

Default600
ValuePython Integer
Changes
  • Added: 3.0.1
  • Deprecated: 3.1.0

Maximum time for a group move to finish in seconds. Controller tries to calculate the finish time based on the trend of moved users so far. If it seems that backends won't be able to finish the move in time, it will be forced. A forced move is done by directly setting group's backend ID in GeoDB.

GROUP_MOVE_START_TIMEOUT_SECS

Default180
ValuePython Integer
Changes
  • Added: 3.0.1
  • Deprecated: 3.1.0

Maximum allowed time of a group move to start in seconds. If backends don't start moving group after this time, a force move will be done. A forced move is done by directly setting group's backend ID in GeoDB.

HOST_FAILURE_BACKEND_NUM_THRESHOLD

Default0.3
ValuePython Float

Percentage of backends in a site that are allowed to become offline before stopping backend evacuations within the site.

HOST_FAILURE_COOL_TIME_SECS

Default3600
ValuePython Integer

Minimum time in seconds a user will not be moved to a new backend because of backend health decisions. The users' move timestamps are tracked by backends, so users that have been moved for any reason by either Controller or doveadm commands will not be moved again until this many seconds have passed.

HOST_FAILURE_FORCE_MOVE_PERCENTAGE_INCREASE_INTERVAL_SECONDS

Default60
ValuePython Integer
Changes
  • Added: 3.1.0

Time interval between increases in percentage of users when backend is being evacuated in a force-move operation. If a backend is slow in moving users to another backend (due to admin's decision to set load factor to 0 or for health handling by controller) a force-move is started in which proxies are instructed to move a portion of users away to other healthy backends. The amount of users being moved to other backends starts at 10% then after a duration of time, configurable by this setting, it is increased to 40% then 70% and finally 100%. In all these percentage increases the time interval applies as well.

HOST_FAILURE_MIN_LOGINS

Default10
ValuePython Integer

Minimum number of logins needed in past 5 minutes to start processing host's health (i.e. change backend status if necessary or move users from it if there is high failure rate).

HOST_FAILURE_RATIO

Default0.1
ValuePython Float

Ratio of failed logins or mail deliveries to trigger user moves. Must be in (0, 1) range exclusive.

HOST_LOAD_BALANCE_GROUP_MIN_COOL_TIME_SECS

Default3600
ValuePython Integer
Changes

Minimum time in seconds a group will not be moved to a new backend. If a group needs to be moved for load balancing, this period is honored and groups that have been moved recently will not be moved again. Must be larger than 0.

HOST_LOAD_BALANCE_MIN_COOL_TIME_SECS

Default3600
ValuePython Integer

Used to determine if a user or a backend has been subject to user moves recently and should be skipped for load balancing.

For users, it determines the minimum time in seconds a user will not be moved to a new backend because of load balancing decisions. The users' move timestamps are tracked by backends, so users that have been moved for any reason by either Controller or doveadm commands will not be moved again until this many seconds have passed.

For backends, it determines the minimum time in seconds no move will be done from or to the backend. The timestamp of last user move from or to the backend is tracked by Controller and at each load balancing iteration, backends that have had a user move within this period will be skipped.

HOST_LOAD_BALANCE_MIN_SAMPLES

Default3000
ValuePython Integer

Number of samples over the last 24 hours needed for all the Z-scores for a host to do load balancing.

USER_MOVE_FINISH_TIMEOUT_SECS

Default600
ValuePython Integer
See Also
Changes
  • Added: 3.1.0

Maximum time for non load-balancing user move operations to finish in seconds. Controller tries to calculate the finish time based on the trend of moved users so far. If it seems that backends won't be able to finish the move in time, the operation will be retried once and if still not successful, it will be forced. A forced move is done by writing to force_move_percentage column in backends table.

USER_MOVE_START_TIMEOUT_SECS

Default180
ValuePython Integer
See Also
Changes
  • Added: 3.1.0

Maximum allowed time of a non load-balancing user move operation to start in seconds. If backends don't start moving user after this time, the operation will be retried once. If the move is still not successful on the second try, a force move will be triggered. A forced move is done by populating force_move_percentage on backend's table in GeoDB.

acl_defaults_from_inbox

Defaultno
Valueboolean
Pluginacl plugin

If enabled, the default ACLs for private and shared namespaces (but not public namespaces) are taken from the INBOX. This means that giving somebody access to your INBOX will give them access to all your other mailboxes as well, unless the specific mailboxes' ACLs override the INBOX's.

acl_dict_index

Defaultyes
Valueboolean
Pluginacl plugin
Changes
  • Added: 3.1.0

Should ACL dict updates assume that there is a reverse lookup index. This should be used with SQL/CQL based dicts.

acl_driver

Default[None]
Valuestring
Pluginacl plugin
Changes
  • Added: 3.1.0

The ACL driver to use. This setting is REQUIRED - if empty, the acl plugin is disabled.

Currently, there is a single driver available: vfile. This driver supports two ways of defining the ACL configuration:

  • global: ACL rules are applied to all users.

  • per-mailbox: Each mailbox has separate ACL rules. They are stored in a dovecot-acl file in each mailbox (or mail_control_path) directory. This is the default.

acl_global_path

Default[None]
Valuestring
See Also
Pluginacl plugin
Changes
  • Added: 3.1.0

Location of global ACL configuration file. This option is deprecated, you should use acl instead.

acl_globals_only

Defaultno
Valueboolean
Pluginacl plugin

If enabled, don't try to find dovecot-acl files from mailbox directories. This reduces unnecessary disk I/O when only global ACLs are used.

acl_groups

Default[None]
Valuestring
Pluginacl plugin

A comma-separated string which contains all the groups the user belongs to.

A user's UNIX groups have no effect on ACLs (you can enable them by using a special post-login scripting.

The default ACL for mailboxes is to give the mailbox owner all permissions and other users none. Mailboxes in public namespaces don't have owners, so by default no one can access them.

acl_ignore

Defaultno
Valueboolean
Pluginacl plugin
Changes
  • Added: 3.1.0

Can be used in global config, namespace, or mailbox level to ignore ACLs.

namespace ignore {
  acl_ignore = yes
}

acl_sharing_map

ValueNamed Filter
See Also
Pluginacl plugin
Changes
  • Added: 3.1.0

A shared mailbox dictionary that defines which users may LIST mailboxes shared by other users.

See shared mailbox listing for further details on the contents of the dictionary entries.

Example:

acl_sharing_map {
  dict file {
    path = /var/lib/dovecot/shared-mailboxes
  }
}

apparmor_hats

Default[None]
ValueBoolean List
Pluginapparmor plugin

List of AppArmor "hats" to change to when a user is loaded.

Example:

apparmor_hats {
  hat_name = yes
  another_hat = yes
}

auth_allow_cleartext

Defaultno
Valueboolean
Changes
  • Added: 3.0.0

If no, disables the LOGIN command and all other cleartext authentication unless SSL/TLS is used (LOGINDISABLED capability) or the connection is secured (see ssl).

See SSL configuration for more detailed explanation of how this setting interacts with the ssl setting.

This setting replaces the disable_plaintext_auth setting.

auth_allow_weak_schemes

Defaultno
Valueboolean
Changes
  • Added: 3.0.0

Controls whether password schemes marked as weak are allowed to be used. See Password Schemes for disabled by default schemes.

If enabled, will emit warning to logs. If a disabled scheme is used, an error is logged.

Notably, any explicitly cleartext schemes (such as PLAIN), CRAM-MD5, and DIGEST-MD5 are not affected by this setting.

auth_anonymous_username

Defaultanonymous
Valuestring

This specifies the username to be used for users logging in with the ANONYMOUS SASL mechanism.

auth_cache_negative_ttl

Default1hour
Valuetime

This sets the time to live for negative hits to passdb or userdb (i.e., when the user is not found or there is a password mismatch).

The value 0 completely disables caching of these hits.

auth_cache_size

Default[None]
Valuesize

The authentication cache size (e.g., 10M).

auth_cache_size = 0 disables use of the authentication cache.

A typical passdb cache entry is around 50 bytes and a typical userdb cache entry is around 100-200 bytes, depending on the amount of information your user and password database lookups return.

auth_cache_ttl

Default1hour
Valuetime

Time to live for cache entries.

After the TTL expires, the cached record is no longer used, unless the main database look-up returns internal failure.

Entries are removed from the cache only when the cache is full and a new entry is to be added.

auth_cache_verify_password_with_worker

Defaultno
Valueboolean

The auth master process by default is responsible for the hash verifications. Setting this to yes moves the verification to auth-worker processes. This allows distributing the hash calculations to multiple CPU cores, which could make sense if strong hashes are used.

auth_debug

Defaultno
Valueboolean
Changes

Enables all authentication debug logging (also enables auth_verbose).

Passwords are logged as <hidden>.

auth_debug_passwords

Defaultno
Valueboolean

This setting adjusts log verbosity. In the event of password mismatches, the passwords and the scheme used are logged so that the problem can be debugged.

Note: You also need to enable log_debug = category=auth.

auth_default_domain

Defaultno
Valueboolean
Changes
  • Added: 3.0.0

This setting indicates the default realm/domain to use if none has been specified. The setting is used for both SASL realms and appending an @domain element to the username in cleartext logins.

auth_failure_delay

Default2secs
Valuetime
See Also

This is the delay before replying to failed authentication attempts. Using passdb: nodelay Extra Field bypasses this setting.

This setting defines the interval for which the authentication process flushes all auth failures. Thus, this is the maximum interval a user may encounter. However, there can be additional delays added by authentication penalty.

This setting doesn't affect internal failures. See auth_internal_failure_delay.

auth_internal_failure_delay

Default2secs
Valuetime (milliseconds)
See Also
Changes
  • Added: 3.0.0

The delay before replying to client when authentication fails with internal failure. An additional 0..50% delay is added on top of this to prevent thundering herd issues.

This setting is intended to prevent clients from hammering the server with immediate retries.

auth_master_user_separator

Default[None]
Valuestring

The separator to use to enable master users to login by specifying the master username within the normal username string (i.e., not using the SASL mechanism's master support).

Example:

# Allows master login of the format <username>*<masteruser>
# E.g. if user = foo, and master_user = muser,
#	login username = foo*muser
auth_master_user_separator = *

auth_mechanisms

Defaultplain
ValueBoolean List
See Also

Here you can supply a space-separated list of the authentication mechanisms you wish to use.

Example:

auth_mechanisms = plain login

auth_policy_hash_mech

Defaultsha256
Valuestring
Allowed Valuesmd4md5sha1sha256sha512
See Also

Hash mechanism to use for password.

auth_policy_hash_nonce

Default[None]
Valuestring
See Also

Cluster-wide nonce to add to hash.

This should contain a secret randomly generated string, which is the same for each Dovecot server within the cluster.

REQUIRED configuration when you want to use authentication policy.

Example:

auth_policy_hash_nonce = <localized_random_string>

auth_policy_log_only

Defaultno
Valueboolean
See Also

Only log what the policy server response would do?

If yes, no request is made to the policy server.

auth_policy_report_after_auth

Defaultyes
Valueboolean

Report authentication result?

If no, there will be no report for the authentication result.

auth_policy_request_attributes

Defaultlogin=%{requested_username} pwhash=%{hashed_password} remote=%{remote_ip} device_id=%{client_id} protocol=%{protocol} session_id=%{session} fail_type=%{fail_type}
ValueString List
See Also
Changes
  • Changed: 3.0.0

    Default has changed.

Request attributes specification.

See Auth Policy Variables for variables that can be used for this setting.

auth_policy_server_api_header

Default[None]
Valuestring
See Also

Header and value to add to request (for API authentication).

Note: See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

This can be used when you are using the weakforced policy server and the web listener password is "super":

$ echo -n wforce:super | base64
d2ZvcmNlOnN1cGVy

Then the correct value for this setting is:

auth_policy_server_api_header = Authorization: Basic d2ZvcmNlOnN1cGVy

auth_policy_server_url

Default[None]
ValueURL

URL of the policy server.

URL is appended with ?command=allow/report. If URL ends with &, the ? is not appended.

REQUIRED configuration when you want to use authentication policy.

Example:

auth_policy_server_url = http://example.com:4001/

auth_realms

Default[None]
ValueBoolean List

This setting supplies a list of realms for those SASL authentication mechanisms that need them. Realms are an integral part of Digest-MD5.

You will need to specify realms you want to advertise to the client in the config file:

Example:

auth_realms = example.com another.example.com foo

auth_ssl_username_from_cert

Defaultno
Valueboolean
See Also

Setting to yes indicates that the username should be taken from the client's SSL certificate.

Generally, this will be either commonName or x500UniqueIdentifier.

The text is looked up from subject DN's specified field using OpenSSL's X509_NAME_get_text_by_NID() function. By default the CommonName field is used. You can change the field with ssl_server_cert_username_field = name setting (parsed using OpenSSL's OBJ_txt2nid() function).

x500UniqueIdentifier is a common choice.

auth_username_chars

DefaultabcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@
Valuestring

The list of the characters allowed in a username.

If the user-supplied username contains a character not listed here, login automatically fails.

This is an additional check to make sure the user can't exploit any quote-escaping vulnerabilities that may be connected with SQL/LDAP databases.

If you want to allow all characters, leave the value empty.

auth_username_format

Default%{user | lower}
Valuestring

When this setting is used globally, it changes the username, including %{user} variable, for all passdb and userdb lookups.

This setting can also be used in passdb/userdb passwd_file { auth_username_format } to change the username for the duration of the lookup. The %{user} variable is not changed. If used inside other passdbs/userdbs the setting is ignored.

You can use the standard variables here.

Examples:

  • %{user | lower}: Lowercases the username
  • %{user | username}: Drops the domain if one was supplied
  • %{user | username}-AT-%{user | domain}: Changes the "@" symbol into "-AT-" before lookup

This translation is done after the changes specified with the auth_username_translation setting.

auth_verbose

Defaultno
Valueboolean

Adjust log verbosity.

If yes, log unsuccessful authentication attempts and why they failed.

auth_verbose_passwords

Defaultno
Valuestring
Allowed Valuesnoyesplainsha1

In case of password mismatches, log the attempted password. You can also truncate the logged password to n chars by appending :n (e.g. sha1:6).

Available transformations:

  • plain, yes: Output cleartext password (NOT RECOMMENDED)
  • sha1: Output SHA1 hashed password

auth_worker_max_count

Default30
Valueunsigned integer

Maximum number of dovecot-auth worker processes active.

The auth workers are used to execute blocking passdb and userdb queries (e.g., MySQL and PAM). They are automatically created and destroyed as necessary.

cassandra_debug_queries

Defaultno
Valueboolean

Whether to log CQL queries.

cassandra_delete_fallback_consistency

Defaultlocal-quorum
Valuestring
Allowed Valuesanylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall
See Also

Write consistency when deleting from the database fails with primary consistency.

cassandra_execution_retry_interval

Default[None]
Valuetime (milliseconds)

If the driver supports speculative execution policy, configures constant speculative execution policy. See https://docs.datastax.com/en/developer/java-driver/latest/manual/core/speculative_execution/index.html

WARNING

If Cassandra is completely unavailable and speculative execution is used, Cassandra cpp-driver library starts hanging all queries due to a bug. This may cause problems in the dict process even after Cassandra is back online. When this happens, "Dict server timeout" errors are being logged.

cassandra_execution_retry_times

Default[None]
Valuetime (milliseconds)

If the driver supports speculative execution policy, configures constant speculative execution policy. See https://docs.datastax.com/en/developer/java-driver/latest/manual/core/speculative_execution/index.html

WARNING

If Cassandra is completely unavailable and speculative execution is used, Cassandra cpp-driver library starts hanging all queries due to a bug. This may cause problems in the dict process even after Cassandra is back online. When this happens, "Dict server timeout" errors are being logged.

cassandra_heartbeat_interval

Default30s
Valuetime

How often to send keepalive packets to cassandra nodes.

cassandra_hosts

Default[None]
ValueBoolean List

List of hosts or IP addresses to connect.

cassandra_io_thread_count

Default[driver dependent]
Valueunsigned integer

Set number of IO threads to handle query requests.

cassandra_keyspace

Default[None]
Valuestring

Specifies the keyspace name to use.

cassandra_latency_aware_routing

Defaultno
Valueboolean

When turned on, latency-aware routing tracks the latency of queries to avoid sending new queries to poorly performing Cassandra nodes.

cassandra_log_level

Defaultwarn
Valuestring
Allowed Valuescriticalerrorwarninfodebugtrace

Driver log level.

cassandra_log_retries

Defaultno
Valueboolean

Whether to log about failed requests that are retried (which may or may not succeed after the retry).

cassandra_page_size

Default[None]
Valueunsigned integer

When a query returns many rows, it can be sometimes inefficient to return them as a single response message. Instead, the driver can break the results into pages which get returned as they are needed.

This setting controls the size of each page.

Set to 0 to disable.

cassandra_password

Default[None]
Valuestring

Password for authentication.

cassandra_port

Default9042
ValuePort Number

CQL port to use.

cassandra_protocol_version

Defaultdepends on driver version
Valuestring
Allowed Values345

Cassandra protocol version to use. It is good idea to specify this to avoid warnings about version handshake if the driver supports a higher protocol version than the server.

INFO

If you want to use server-side prepared statements, you need to use at least 4.

cassandra_read_consistency

Defaultlocal-quorum
Valuestring
Allowed Valuesanylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall
See Also

Read consistency.

cassandra_read_fallback_consistency

Defaultlocal-quorum
Valuestring
Allowed Valuesanylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall
See Also

Read consistency if primary consistency fails.

cassandra_request_timeout

Default60s
Valuetime (milliseconds)

How long to wait for a query to finish.

cassandra_ssl

Defaultno
Valuestring
Allowed Valuesnocert-onlycert-ip
See Also

Whether to use SSL when connecting to Cassandra, and how to verify the certificate:

no
Don't use SSL
cert-only
Verify the certificate, but not the IP address or host name.
cert-ip
Verify the certificate, and require IP address to match the certificate's common name or one of its subject alternative names.

You can also skip certificate validation by setting ssl_client_require_valid_cert = yes. The cassandra_ssl setting value must something else than no.

Configure SSL certificates using the ssl_client_* settings. See SSL configuration.

cassandra_user

Default[None]
Valuestring

Username for authentication.

cassandra_warn_timeout

Default5s
Valuetime (milliseconds)

Emit warning if query takes longer than this.

cassandra_write_consistency

Defaultlocal-quorum
Valuestring
Allowed Valuesanylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall
See Also

Write consistency when updating or inserting to the database.

cassandra_write_fallback_consistency

Defaultlocal-quorum
Valuestring
Allowed Valuesanylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall
See Also

Write consistency when updating or inserting to the database fails with primary consistency.

charset_aliases

Default[None]
ValueString List
Plugincharset-alias plugin

List of <from>=<to> charsets. The "from" charsets will be treated as "to" charsets when decoding to UTF-8.

Example:

charset_aliases {
  shift_jis = sjis-win
  euc-jp = eucjp-win
  iso-2022-jp = iso-2022-jp-3
}

cluster_backend_name

Default[None]
Valuestring

Host name of the backend. This must be the same name as used by doveadm cluster-backend commands.

Cluster: Applies only to Backend.

cluster_backend_test_username

Default[None]
Valuestring
See Also

This setting is used for two purposes:

  1. Username used by proxy for logging into backends to see if it's up or down. %{backend_host} variable expands to the hostname of the backend.
  2. Backends skip this username when doing batch user moves.

Cluster: Applies to both Proxy and Backend.

cluster_director_transition_config

Default[None]
ValueFile

Path to configuration file for director to cluster transition.

The configuration file has to be created by the migrate_start.py script, which is to be used as described in Transition from OX Dovecot Pro 2.3.x Architecture.

If this file is set, the cluster will perform an additional lookup for the user's backend in the current site, using information from the transition configuration. This lookup is only performed if the user does not already have a backend assigned.

This way, users are assigned the same backend at login as they had in the director setup they are being transitioned from. For more information please refer to Transition from OX Dovecot Pro 2.3.x Architecture.

cluster_geodb

Default[None]
Valuestring

Configuration for the globally shared GeoDB dict. This typically points to Cassandra.

Cluster: Applies to both Proxy and Backend.

cluster_local_site

Default[None]
Valuestring

Name of the local site. This must be the same name as used by doveadm cluster-site commands.

Cluster: Applies to both Proxy and Backend.

cluster_proxy_check_backends

Defaultyes
Valuestring
See Also

If enabled, this proxy runs checks on backends that are offline to see whether they have come back online. This only updates statistics to allow controller to set the backends online. Backends that are online are not checked, except once at startup.

Cluster: Applies only to Proxy.

cluster_user_move_timeout

Default31secs
Valuetime

If user moving hasn't finished by this timeout, just assume it finished and continue to the next user.

Cluster: Applies only to Proxy.

crypt_acl_require_secure_key_sharing

Defaultno
Valueboolean
Pluginmail-crypt plugin

If enabled, you cannot share a key to groups or someone without a public key.

crypt_global_public_key_file

Default[None]
ValueFile
Pluginmail-crypt plugin

Public key to encrypt files. Key must be in PEM pkey format. The PEM key may additionally be base64-encoded into a single line, which can make it easier to store into userdb extra fields.

crypt_user_key_curve

Default[None]
Valuestring
Pluginmail-crypt plugin

Defines the elliptic curve to use for key generation.

Any valid curve supported by the underlying cryptographic library is allowed.

Example:

crypt_user_key_curve = secp521r1

This must be set if you wish to use folder keys rather than global keys.

With global keys (either RSA or EC keys), all keying material is taken from the setting and no key generation is performed.

In folder-keys mode, a key pair is generated for the user, and a folder-specific key pair is generated. The latter is encrypted by means of the user's key pair.

For EdDSA, you need to use X448 or X25519, case sensitive.

crypt_user_key_password

Default[None]
Valuestring
Pluginmail-crypt plugin

Password to decrypt user's master private key.

crypt_write_algorithm

Defaultaes-256-gcm-sha256
Valuestring
Pluginmail-crypt plugin

Set the encryption algorithm. If empty new mails are not encrypted, but existing mails can still be decrypted.

default_internal_user

Defaultdovecot
Valuestring
See Also

Define the default internal user.

Unprivileged processes run under the ID of the internal user. This user should be distinct from the login user, to prevent login processes from disturbing other processes.

default_login_user

Defaultdovenull
Valuestring

The user the login process should run as.

This is the least trusted user in Dovecot: this user should not have access to anything at all.

default_vsz_limit

Default1 G
Valuesize

Default value for service_vsz_limit, if not overridden by service-specific configuration.

deliver_log_format

Defaultmsgid=%{msgid}: %{message}
ValueString without variables

The format to use for logging mail deliveries.

Variables that can be used for this setting (see Global variables):

Variable Name Description
%{message} Delivery status message (e.g., saved to INBOX)
%{msgid}
%{subject} Subject
%{from} From address
%{from_envelope} SMTP FROM envelope
%{size} Physical size
%{vsize} Virtual size
%{to_envelope} RCPT TO envelope
%{delivery_time} How many milliseconds to deliver the mail
%{session_time} LMTP session duration, not including %{delivery_time}
%{storage_id} Backend-specific ID for mail, e.g. Maildir filename

Example:

deliver_log_format = stime=%{session_time} msgid=%{msgid}: %{message}

dict_driver

Default<dict_name>
Valuestring

The dict driver to use. Defaults to dict_name.

dict_file_path

Default[None]
Valuestring

Path for the dictionary file.

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_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.

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.

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.

dict_server

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
    # ...
  }
}

dotlock_use_excl

Defaultyes
Valueboolean

If yes, rely on O_EXCL to work when creating dotlock files.

NFS has supported O_EXCL since version 3, so yes should be safe to use by default.

doveadm_allowed_commands

DefaultALL
ValueBoolean List

Lists the commands that the client may use with the doveadm server.

The setting ALL allows all commands.

doveadm_api_key

Default[None]
Valuestring

Set an API key for use of the HTTP API for the doveadm server.

If set, the key must be included in the HTTP request (via X-API-Key header) base64 encoded.

doveadm_password

Default[None]
Valuestring

The doveadm client and server must have a shared secret. This setting configures the doveadm server's password, used for client authentication.

Because it grants access to users' mailboxes, it must be kept secret.

doveadm_port

Default[None]
ValuePort Number

The destination port to be used for the next doveadm proxying hop. This implicitly enables doing a passdb lookup for finding the proxy settings.

A value of 0 means that proxying is not in use. This also means no passdb lookup is done - only userdb lookup.

This setting is required with Palomar cluster configuration even in backends, because the backend may still ask proxy to reject the connection and proxy the user to another backend.

doveadm_server

ValueNamed Filter

Filter for doveadm server specific settings.

doveadm_socket_path

Defaultdoveadm-server
Valuestring

The UNIX socket or host (host:port syntax is allowed) for connecting to the doveadm server.

doveadm_ssl

Defaultno
Valuestring
Allowed Valuesnosslstarttls

TODO

doveadm_username

Defaultdoveadm
Valuestring

The username for authentication to the doveadm service.

doveadm_worker_count

Default[None]
Valueunsigned integer

If the worker count set here is non-zero, mail commands are run via this many connections to the doveadm service.

If 0, commands are run directly in the same process.

dovecot_config_version

Default[None]
Valuestring
Changes
  • Added: 3.0.0

Dovecot configuration version. It uses the same versioning as Dovecot in general, e.g. 3.0.5. This must be the first setting in the configuration file. It specifies the configuration syntax, the used setting names and the expected default values.

When there are default configuration changes in newer Dovecot versions, the existing installations will continue to work the same as before with the same default settings until this version number is increased. If there are other configuration changes, the old configuration will either keep working or there will be a clear failure at startup.

dovecot_storage_version

Default[None]
Valuestring
Changes
  • Added: 3.0.0

Dovecot storage file format version. It uses the same versioning as Dovecot in general, e.g. 3.0.5. It specifies the oldest Dovecot version that must be able to read files written by this Dovecot instance. The intention is that when upgrading Dovecot cluster, this setting is first kept as the old Dovecot version. Once the cluster is fully upgraded to a new version and there is no intention to rollback to the old version anymore, this version number can be increased.

dsync_alt_char

Default_
Valuestring

When the source and destination mailbox formats are different, it's possible for a mailbox name to exist on one source that isn't valid for the destination. Any invalid characters are replaced with the character indicated here.

dsync_commit_msgs_interval

Default100
Valueunsigned integer

Dsync will commit this number of messages incrementally, to avoid huge transactions that fail.

dsync_features

Default[None]
Valuestring

This setting specifies features and workarounds that can be used with dsync. Options are specified in this setting via a space-separated list.

Available options:

empty-header-workaround
Workaround for servers (e.g. Zimbra) that sometimes send FETCH replies containing no headers.
no-header-hashes
When this setting is enabled and one dsync side doesn't support mail GUIDs (i.e. imapc), there is no fallback to using header hashes. Instead, dsync assumes that all mails with identical IMAP UIDs contain the same mail contents. This can significantly improve dsync performance with some IMAP servers that don't support caching Date/Message-ID headers.

event_exporter_driver

Defaultlog
Valuestring
Allowed Valueslogfileunixhttp-postdrop
See Also

The event exporter driver to use.

event_exporter_time_format

Defaultrfc3339
Valuestring
Allowed Valuesrfc3339unix
See Also
rfc3339
Serialize timestamps as strings using the RFC 3339 format (YYYY-MM-DDTHH:MM:SS.uuuuuuZ).
unix
Serialize timestamps as a floating point number of seconds since the Unix epoch.

execute

Default[None]
ValueNamed List Filter
See Also

Configure external execution script. Used by various different features, such as welcome. Currently only a single execute block (per feature) is allowed.

execute_args

Default[None]
Valuestring

External execution script arguments. The parameters are split by space characters. Currently escape characters are not supported.

fifo_listener_group

Default[None]
Valuestring

Group of the listener file. Empty (default) means GID 0 (root/wheel).

fifo_listener_mode

Default0600
Valueoctal unsigned integer

Mode of the file. Note that 0600 is an octal value, while 600 is a different decimal value. Setting mode to 0 disables the listener.

fifo_listener_type

Default[None]
Valuestring
Changes
  • Added: 3.1.0

Listener type. This string value has service-specific meaning and is used to distinguish different listener types that one service may employ.

fifo_listener_user

Default[None]
Valuestring

Owner of the listener file. Empty (default) means UID 0 (root).

first_valid_gid

Default1
Valueunsigned integer
See Also

This setting and last_valid_gid specify the valid GID range for users.

A user whose primary GID is outside this range is not allowed to log in.

If the user belongs to any supplementary groups, the corresponding IDs are not set.

fs_auth_cache

ValueNamed Filter
Pluginobox plugin

Named filter for fs-auth service. Used for configuring dictionary for authentication cache. This allows sharing the cache between multiple servers.

fs_auth_request_max_retries

Default1
Valueunsigned integer
Pluginobox plugin

If fs-auth fails to perform authentication lookup, retry the HTTP request this many times.

fs_azure_bulk_delete_limit

Default256
Valueunsigned integer
Pluginobox plugin

Number of deletes supported within the same bulk delete request. 0 disables bulk deletes.

fs_azure_container_name

Default[None]
Valuestring
Pluginobox plugin

Azure container name.

fs_compress_read_plain_fallback

Defaultno
Valueboolean
See Also

By default fs-compress plugin fails if the file wasn't compressed. If this setting is enabled the file is returned as-is (i.e. allows reading plaintext files).

fs_crypt_read_plain_fallback

Defaultno
Valueboolean

If enabled files that are not encrypted are returned as-is. By default it results in a read error.

fs_dict_value_encoding

Defaultraw
Valuestring
Allowed Valuesrawhexbase64

How to encode file contents into the dict value.

fs_dictmap_bucket_cache_path

Default[None]
obox { "%{home}/buckets.cache" }
Valuestring
See Also
Pluginobox plugin

Required when fs_dictmap_bucket_size is set. Bucket counters are cached in this file. This path should be located under the obox indexes directory (on the SSD backed cache mount point; e.g. %{home}/buckets.cache).

fs_dictmap_bucket_deleted_days

Default0obox { 11 }
Valueunsigned integer
See Also
Pluginobox plugin

Track Cassandra's tombstones in buckets.cache file to avoid creating excessively large buckets when a lot of mails are saved and deleted in a folder. The value should be one day longer than gc_grace_seconds for the user_mailbox_objects table. By default this is 10 days, so in that case fs_dictmap_bucket_deleted_days = 11 should be used. When determining whether fs_dictmap_bucket_size is reached and a new one needs to be created, with this setting the tombstones are also taken into account. This tracking is preserved only as long as the buckets.cache exists.

fs_dictmap_cleanup_uncertain

Defaultyes
Valueboolean
See Also
Pluginobox plugin

If a write to Cassandra fails with uncertainty and this setting is enabled Dovecot attempts to clean it up.

fs_dictmap_delete_timestamp

Default10s
Valuetime (milliseconds)
Pluginobox plugin

Increase Cassandra's DELETE timestamp by this value. This is useful to make sure the DELETE isn't ignored because Dovecot backends' times are slightly different.

WARNING

If the same key is intentionally attempted to be written again soon afterwards, the write becomes ignored. Dovecot doesn't normally do this, but this can happen if the user is deleted with doveadm obox user delete and the same user is recreated. This can also happen with doveadm backup that reverts changes by deleting a mailbox; running the doveadm backup again will recreate the mailbox with the same GUID.

fs_dictmap_dict_prefix

Default[None]
Valuestring
Pluginobox plugin

Prefix that is added to all dict keys.

For example fts-dovecot plugin writes everything to root. This setting is used in the defaults to make it write to the expected dict path prefix (%{user}/fts/), which is expected by the default dict maps.

fs_dictmap_lock_path

Default[None]
Valuestring
See Also
Pluginobox plugin

If fs_dictmap_refcounting_table is enabled, use this dictionary for creating lock files to objects while they're being copied or deleted. This attempts to prevent race conditions where an object copy and delete runs simultaneously and both succeed, but the copied object no longer exists. This can't be fully prevented if different servers do this concurrently. If lazy-expunge plugin is used this setting isn't really needed, because such race conditions are practically nonexistent. Not using the setting will improve performance by avoiding a Cassandra SELECT when copying mails.

fs_dictmap_max_parallel_iter

Default10
Valueunsigned integer
Pluginobox plugin
Changes
  • Changed: 3.1.0

    Increased default from 1 to 10

Describes how many parallel dict iterations can be created internally. The default value is 10. Parallel iterations can especially help speed up reading huge folders.

Default0obox { 3 }
Valueunsigned integer
Pluginobox plugin

Defines the maximum number of results returned from a dictionary iteration lookup (i.e. Cassandra CQL query) when checking the number of links to an object. Limiting this may improve performance. Currently Dovecot only cares whether the link count is 0, 1 or "more than 1" so for a bit of extra safety we recommend setting it to 3.

fs_dictmap_refcounting_table

Defaultno
obox { yes }
Valueboolean
See Also
Pluginobox plugin

Enable reference counted objects. Reference counting allows a single mail object to be stored in multiple mailboxes, without the need to create a new copy of the message data in object storage.

fs_dictmap_storage_objectid_migrate

Defaultno
Valueboolean
Pluginobox plugin

This is expected to be used with storage-objectid-prefix when adding fs-dictmap for an existing installation. The newly created object IDs have <storage-objectid-prefix>/<object-id> path while the migrated object IDs have <user>/mailboxes/<mailbox-guid>/<oid> path. The newly created object IDs can be detected from the 0x80 bit in the object ID's extra-data. Migrated object IDs can't be copied directly within dict - they'll be first copied to a new object ID using the parent fs.

fs_dictmap_storage_objectid_prefix

Default[None]
Valuestring
See Also
Pluginobox plugin

Use fake object IDs with object storage that internally uses paths. This makes their performance much better, since it allows caching object IDs in Dovecot index files and copying them via dict. This works by storing object in <prefix>/<objectid>. This setting should be used inside obox plugin named filter for storing mails under <prefix> (but not for metacache or fts).

For example:

fs_dictmap_storage_objectid_prefix = %{user}/mails/

fs_dictmap_storage_passthrough_paths

Defaultnone
Valuestring
Allowed Valuesnonefullread-only
See Also
Pluginobox plugin

Use fake object IDs with object storage that internally uses path. Assume that object ID is the same as the path. Objects can't be copied within the dict. This setting should be used inside metacache and fts_dovecot named filters, because they don't need to support copying objects. For mails, use fs_dictmap_storage_objectid_prefix instead.

Value Description
none Don't use fake object IDs.
full The object ID is written to dict as an empty value, because it's not used.
read-only Useful for backwards compatibility. The path is written to the dict as the object ID even though it is not used (except potentially by an older Dovecot version).

fs_fscache_size

Default[None]
Valuesize
Pluginobox plugin

Size of the fscache.

fs_http_log_headers

Default[None]
ValueBoolean List
Pluginobox plugin

Headers with the given name in HTTP responses are logged as part of any error, debug or warning messages related to the HTTP request. These headers are also included in the http_request_finished event as fields prefixed with http_hdr_.

fs_http_log_trace_headers

Defaultyes
Valueboolean
Pluginobox plugin

If yes add X-Dovecot-User: and X-Dovecot-Session: headers to HTTP request. The session header is useful to correlate object storage requests to AppSuite/Dovecot sessions.

fs_http_reason_header_max_length

Default[None]
Valueunsigned integer
Pluginobox plugin

If non-zero add X-Dovecot-Reason: header to the HTTP request. The value contains a human-readable string why the request is being sent.

fs_http_url_suffix

Default[None]
Valuestring
See Also
Pluginobox plugin

Setting to append a suffix to fs-http based fs drivers url.

For example fts-dovecot plugin writes everything to root. This setting is used in the defaults to make it write to the expected path suffix in storage (%{user}/fts/).

fs_posix_fsync

Defaultyes
Valueboolean

Configure whether fsync() is called after writes to guarantee that the file is written to disk.

fs_posix_prefix

Default[None]
Valuestring

Directory prefix where files are read from/written to.

INFO

The trailing / is not automatically added, so using e.g. /tmp/foo as prefix will cause /tmp/foofilename to be created.

fs_s3_access_key

Default[None]
Valuestring
Pluginobox plugin

S3 access key. Not needed when AWS IAM is used.

fs_s3_bucket

Default[None]
Valuestring
Pluginobox plugin

S3 bucket name added to the request path.

fs_s3_bulk_delete_limit

Default1000
Valueunsigned integer
Pluginobox plugin

Number of deletes supported within the same bulk delete request. 0 disables bulk deletes.

fs_s3_secret

Default[None]
Valuestring
Pluginobox plugin

S3 secret. Not needed when AWS IAM is used.

fs_s3_url

Default[None]
Valuestring
Pluginobox plugin

URL for accessing the S3 storage. For example: https://BUCKETNAME.s3.example.com

fs_sproxyd_class

Default2
Valueunsigned integer
Pluginobox plugin

Scality Class of Service. 2 means that the objects are written to the Scality RING 3 times in total. This is generally the minimum allowable redundancy for mail and index objects.

FTS data is more easily reproducible, so losing those indexes is not as critical; Class of Service 1 may be appropriate based on customer requirements.

fts_autoindex

Defaultno
Valueboolean
See Also
Pluginfts plugin

If enabled, index mail as it is delivered or appended.

It can be overridden at the mailbox level, e.g. you can disable autoindexing for selected mailboxes using this setting:

Example:

fts_autoindex = yes

# ...

mailbox trash {
  special_use = Trash
  fts_autoindex = no
}

mailbox spam {
  special_use = Junk
  fts_autoindex = no
}

mailbox storage/* {
  fts_autoindex = no
}

fts_autoindex_max_recent_msgs

Default[None]
Valueunsigned integer
See Also
Pluginfts plugin

To exclude infrequently accessed mailboxes from automatic indexing, set this value to the maximum number of Recent flagged messages that exist in the mailbox.

A value of 0 means to ignore this setting.

Mailboxes with more flagged Recent messages than this value will not be autoindexed, even though they get deliveries or appends. This is useful for, e.g., inactive Junk folders.

Any folders excluded from automatic indexing will still be indexed, if a search on them is performed.

Example:

fts_autoindex_max_recent_msgs = 999

fts_decoder_driver

Default[None]
Valuestring
Allowed Valuesscripttika
Pluginfts plugin

Optional setting. If set, decode attachments to plaintext using the selected service and index the resulting plaintext.

fts_decoder_script_socket_path

Default[None]
Valuestring
Pluginfts plugin
Changes
  • Changed: 3.1.0

    Renamed from fts_decoder.

Name of the script service used to decode the attachments.

See the decode2text.sh script included in Dovecot for how to use this.

Example:

fts_decoder_driver = script
fts_decoder_script_socket_path = decode2text

service decode2text {
  executable = script /usr/lib/dovecot/decode2text.sh
  user = vmail
  unix_listener decode2text {
	mode = 0666
  }
}

fts_decoder_tika_url

Default[None]
Valuestring
See Also
Pluginfts plugin
Changes
  • Added: 3.0.0

    Basic authentication support (via URL) is added.

  • Changed: 3.1.0

    Renamed from fts_tika.

URL for Apache Tika decoder for attachments.

Example:

fts_decoder_driver = tika
fts_decoder_tika_url = http://tikahost:9998/tika/

fts_dovecot_prefix

Defaultno
Valuestring
Pluginfts-dovecot plugin

Specifies how prefix search should be invoked. May not work with some filters.

Options:

Value Description
yes Equivalent to 0-255
<num>-[<num>] Search strings with that length will be treated as prefixes (e.g. 4-, 3-10)
no No prefix searching is performed

fts_driver

Default[None]
Valuestring
Allowed Valuesdovecotsolrflatcurve
Pluginfts plugin

Configures the used fts driver to perform fts plugin indexing. The fts filter name refers to this setting.

fts_header_excludes

Default[None]
ValueBoolean List
Pluginfts plugin

The list of headers to include or exclude.

  • The default is the preexisting behavior, i.e. index all headers.
  • includes take precedence over excludes: if a header matches both, it is indexed.
  • The terms are case insensitive.
  • An asterisk * at the end of a header name matches anything starting with that header name.
  • The asterisk can only be used at the end of the header name. Prefix and infix usage of asterisk are not supported.

Example:

fts_header_excludes {
  Received = yes
  DKIM-* = yes
  X-* = yes
  Comments = yes
}

fts_header_includes {
  X-Spam-Status = yes
  Comments = yes
}

  • Received headers, all DKIM- headers and all X- experimental headers are excluded, with the following exceptions:

    • Comments and X-Spam-Status are indexed anyway, as they match both excludes and includes lists.
    • All other headers are indexed.

Example:

fts_header_excludes {
  * = yes
}

fts_header_includes {
  From = yes
  To = yes
  Cc = yes
  Bcc = yes
  Subject = yes
  Message-ID = yes
  In-* = yes
  X-CustomApp-* = yes
}
  • No headers are indexed, except those specified in the includes.

fts_message_max_size

Default[None]
Valuesize
Pluginfts plugin
Changes
  • Added: 3.0.0

Maximum body size that is processed by fts. 0 means unlimited.

fts_search_add_missing

Defaultbody-search-only
Valuestring
Allowed Valuesbody-search-onlyyes
Pluginfts plugin

Should missing mails be added to FTS indexes before search?

With body-search-only this is done only when the search query requests searching message bodies, i.e. header searches are not updating the FTS index.

The unindexed mails are searched without FTS, i.e. either getting the headers from dovecot.index.cache or by opening the emails if the headers aren't in cache. This may be a useful optimization if the user's client only uses header searches.

INFO

Only the yes option guarantees consistent search results. Otherwise it's possible that the search results will be different depending on whether the search was performed via FTS index or not.

fts_search_read_fallback

Defaultyes
Valueboolean
Pluginfts plugin

If FTS lookup or indexing fails, fall back to searching without FTS (i.e. possibly opening all emails). This may timeout for large mailboxes and/or slow storage.

fts_search_timeout

Default30s
Valuetime
Pluginfts plugin

When the full text search driver detects that the index isn't up-to-date, the indexer is told to index the messages and is given this much time to do so. If this time limit is reached, an error is returned, indicating that the search timed out during waiting for the indexing to complete: NO [INUSE] Timeout while waiting for indexing to finish.

A value of 0 means no timeout.

fts_solr_batch_size

Default1000
Valueunsigned integer
Pluginfts-solr plugin

Configures the number of mails sent to Solr in a single request.

  • With fts_autoindex = yes each new mail gets separately indexed on arrival, so fts_solr_batch_size only matters during the initial indexing of a mailbox.
  • With fts_autoindex = no new mails don't get indexed on arrival, so fts_solr_batch_size is used when indexing is triggered.

fts_solr_url

Default[None]
Valuestring
Pluginfts-solr plugin

Required base URL for Solr.

INFO

Remember to add your core name if using solr 7+: /solr/dovecot.

Example:

fts_solr_url = http://solr.example.org:8983/solr/dovecot/
fts_solr_batch_size = 1000

haproxy_timeout

Default3secs
Valuetime

When to abort the HAProxy connection when no complete header has been received.

haproxy_trusted_networks

Default[None]
Valuestring

A space-separated list of trusted network ranges for HAProxy connections.

Connections from networks outside these ranges to ports that are configured for HAProxy are aborted immediately.

hostname

Default<system's real hostname@domain.tld>
Valuestring

The hostname to be used in email messages sent out by the local delivery agent (such as the Message-ID: header), in LMTP replies, and as the hostname advertised by submission SMTP service.

http_client_max_connect_attempts

Default[None]
Valueunsigned integer
Changes
  • Added: 3.1.0

Maximum number of connection attempts to a host before all associated requests fail.

If non-zero, the maximum will be enforced across all IPs for that host, meaning that IPs may be tried more than once eventually if the number of IPs is smaller than the specified maximum attempts. If the number of IPs is higher than the maximum attempts not all IPs are tried.

If 0, all IPs are tried at most once.

http_client_max_idle_time

Default[None]
Valuetime (milliseconds)
Changes
  • Added: 3.1.0

Maximum time a connection will idle. If parallel connections are idle, the duplicates will end earlier based on how many idle connections exist to that same service.

http_client_max_parallel_connections

Default1
Valueunsigned integer
Changes
  • Added: 3.1.0

Maximum number of parallel connections per peer.

http_client_max_pipelined_requests

Default1
Valueunsigned integer
Changes
  • Added: 3.1.0

Maximum number of pipelined requests per connection.

http_client_proxy_password

Default[None]
Valuestring
Changes
  • Added: 3.1.0

Password for HTTP proxy.

http_client_proxy_ssl_tunnel

Defaultyes
Valueboolean
Changes
  • Added: 3.1.0

If no the HTTP proxy delegates SSL negotiation to proxy, rather than creating a CONNECT tunnel through the proxy for the SSL link.

http_client_proxy_username

Default[None]
Valuestring
Changes
  • Added: 3.1.0

Username for HTTP proxy.

http_client_rawlog_dir

Default[None]
Valuestring
Changes
  • Added: 3.1.0

Directory for writing raw log data for debugging purposes.

WARNING

Must be writable by the process creating this log.

http_client_request_absolute_timeout

Default[None]
Valuetime (milliseconds)
Changes
  • Added: 3.1.0

Max total time to wait for HTTP request to finish, including all retries. 0 means no limit.

http_client_request_max_attempts

Default1
Valueunsigned integer
Changes
  • Added: 3.1.0

Maximum number of attempts for a request.

http_client_request_max_redirects

Default[None]
Valueunsigned integer
Changes
  • Added: 3.1.0

Maximum number of redirects for a request. 0 = redirects refused.

http_client_request_timeout

Default1 min
Valuetime (milliseconds)
Changes
  • Added: 3.1.0

Max time to wait for HTTP requests to finish before retrying.

http_server_max_idle_time

Default[None]
Valuetime (milliseconds)

Maximum time a connection will idle.

http_server_max_pipelined_requests

Default1
Valueunsigned integer

Maximum number of pipelined requests per connection.

http_server_rawlog_dir

Default[None]
Valuestring

Directory for writing raw log data for debugging purposes.

imap_acl_allow_anyone

Defaultno
Valueboolean
Pluginimap-acl plugin

By default Dovecot doesn't allow using the IMAP anyone or authenticated identifier, because it would be an easy way to spam other users in the system.

If mail-crypt plugin is used, users who have different set of encryption keys cannot share mails, but sharing is possible within the scope of a key.

imap_capability

Default[None]
ValueBoolean List

Override the IMAP CAPABILITY response.

Example of modifying capability banner by adding QUOTA and ACL, and removing IDLE:

imap_capability {
  QUOTA = yes
  ACL = yes
  IDLE = no
}

Example of setting capability banner to exactly IMAP4rev1 SASL-IR IDLE:

imap_capability = IMAP4rev1 SASL-IR IDLE

imap_client_workarounds

Default[None]
ValueBoolean List

Workarounds for various IMAP client bugs can be enabled here.

The following values are currently supported:

delay-newmail
EXISTS/RECENT new-mail notifications are sent only in replies to NOOP and CHECK commands. Some clients, such as pre-2.1 versions of Mac OS X Mail, ignore them otherwise, and, worse, Outlook Express may report that the message is no longer on the server (note that the workaround does not help for OE6 if synchronization is set to Headers Only).
tb-extra-mailbox-sep
Because mailbox_list_layout = fs (mbox and dbox) confuses Thunderbird, causing extra / suffixes to mailbox names, Dovecot can be told to ignore the superfluous character instead of judging the mailbox name to be invalid.
tb-lsub-flags
Without this workaround, Thunderbird doesn't immediately recognize that LSUB replies with mailbox_list_layout = fs aren't selectable, and users may receive pop-ups with not selectable errors. Showing \Noselect flags for these replies (e.g., in mbox use) causes them to be grayed out.

imap_fetch_failure

Defaultdisconnect-immediately
Valuestring
Allowed Valuesdisconnect-afterdisconnect-immediatelyno-after

Behavior when IMAP FETCH fails due to some internal error. Options:

disconnect-immediately

The FETCH is aborted immediately and the IMAP client is disconnected.

disconnect-after

The FETCH runs for all the requested mails returning as much data as possible. The client is finally disconnected without a tagged reply.

no-after

Same as disconnect-after, but tagged NO reply is sent instead of disconnecting the client.

If the client attempts to FETCH the same failed mail more than once, the client is disconnected.

This is to avoid clients from going into infinite loops trying to FETCH a broken mail.

imap_hibernate_timeout

Default30secs
Valuetime

How long to wait while the client is in IDLE state before moving the connection to the hibernate process, to save on memory use, and close the existing IMAP process.

If nothing happens for this long while client is IDLEing, move the connection to imap-hibernate process and close the old imap process. This saves memory, because connections use very little memory in imap-hibernate process. The downside is that recreating the imap process back uses some additional system resources.

imap_id_retain

Defaultno
Valueboolean

When proxying IMAP connections to other hosts, this variable must be enabled to forward the IMAP ID command provided by the client.

This setting enables the %{client_id} variable for auth processes. See Authentication variables.

imap_id_send

Defaultname=%{dovecot:name}
ValueString List

Which ID field names and values to send to clients.

You can access the default values by using Distribution Variables.

imap_id_send {
  name = %{dovecot:name}
  version = %{dovecot:version}
  support-url = http://example.com/
}

imap_intercept_disconnect_after

Defaultinfinite
Valuetime
Pluginimap-intercept plugin

The IMAP client is disconnected after this amount of time, and interception is discontinued.

This timeout prevents repeated interception of a very long session (disconnection is performed for all users, so that interception-specific behavior isn't obvious to the user).

imap_literal_minus

Defaultno
Valueboolean

Enable IMAP LITERAL- (RFC 7888) extension (replaces LITERAL+)?

imap_logout_format

Defaultin=%{input} out=%{output} deleted=%{deleted} expunged=%{expunged} trashed=%{trashed} hdr_count=%{fetch_hdr_count} hdr_bytes=%{fetch_hdr_bytes} body_count=%{fetch_body_count} body_bytes=%{fetch_body_bytes}
ValueString without variables

This setting specifies the IMAP logout format string. Supported variables, in addition to Mail user variables are:

Variable Name Description
%{input} Total number of bytes read from client
%{output} Total number of bytes sent to client
%{fetch_hdr_count} Number of mails with mail header data sent to client
%{fetch_hdr_bytes} Number of bytes with mail header data sent to client
%{fetch_body_count} Number of mails with mail body data sent to client
%{fetch_body_bytes} Number of bytes with mail body data sent to client
%{deleted} Number of mails where client added Deleted flag
%{expunged} Number of mails that client expunged, which does not include automatically expunged mails
%{autoexpunged} Number of mails that were automatically expunged after client disconnected
%{trashed} Number of mails that client copied/moved to the special_use=Trash mailbox.
%{appended} Number of mails saved during the session

imap_metadata

Defaultno
Valueboolean

Dovecot supports the IMAP METADATA extension (RFC 5464), which allows per-mailbox, per-user data to be stored and accessed via IMAP commands. Set this parameter's value to yes if you wish to activate the IMAP METADATA commands.

Note: If activated, a dictionary needs to be configured, via the mail_attribute setting.

Example:

# Store METADATA information within user's Maildir directory
mail_attribute {
  dict file {
    path = %{home}/Maildir/dovecot-attributes
  }
}

protocol imap {
  imap_metadata = yes
}

imap_urlauth_host

Default[None]
ValueURL

Specifies the host used for URLAUTH URLs. Only this host is accepted in the client-provided URLs. Using * value (not recommended) allows all hosts and the generated URLs use hostname as the host.

An empty value disables the URLAUTH extension entirely.

WARNING

URLAUTH in current versions of Dovecot is broken in several ways. This will be fixed in the future, but activating URLAUTH support on production systems is not recommended.

INFO

This setting is REQUIRED for the URLAUTH (RFC 4467) extension to be active.

imap_urlauth_logout_format

Defaultin=%{input} out=%{output}
ValueString without variables
See Also

Specifies the logout format used with the URLAUTH extension in IMAP operation.

WARNING

This setting is currently not used.

Variables allowed:

Name Description
%{input} Total number of bytes read from the client
%{output} Total number of bytes sent to the client

imapc_cmd_timeout

Default5 mins
Valuetime

How long to wait for a reply to an IMAP command sent to the remote IMAP server before disconnecting and retrying.

imapc_connection_retry_count

Default1
Valueunsigned integer

How many times to retry connection against a remote IMAP server?

imapc_connection_retry_interval

Default1 secs
Valuetime (milliseconds)

How long to wait between retries against a remote IMAP server?

imapc_connection_timeout_interval

Default30secs
Valuetime (milliseconds)

How long to wait before considering a connection attempt as timed out.

imapc_features

Default[None]
ValueBoolean List
Changes
  • Changed: 3.0.0

    Several features are now automatically enabled and the respective flags dropped. In their place new flags to disable these features were added.

List of features, optimizations, and workarounds that can be enabled.

Features
no-acl

If the imap-acl plugin is loaded, the imapc acl feature is automatically enabled. With it IMAP ACL commands (MYRIGHTS, GETACL, SETACL, DELETEACL) are proxied to the imapc remote location. Note that currently these commands are attempted to be used even if the remote IMAP server doesn't advertise the ACL capability.

To disable this feature either unload the imap-acl plugin or provide this feature.

Changed: 3.0.0

Earlier versions had an "acl" feature, which is now enabled by default.

no-delay-login

Immediately connect to the remote server. By default this is delayed until a command requires a connection.

Changed: 3.0.0

Earlier versions had a "delay-login" feature, which is now enabled by default.

gmail-migration
Enable GMail-specific migration. Use IMAP X-GM-MSGID as POP3 UIDL. Add $GMailHaveLabels keyword to mails that have X-GM-LABELS except for Muted keyword (to be used for migrating only archived emails in All Mails). Add pop3_deleted_flag to mails that don't exist in POP3 server.
no-modseq

Disable access to MODSEQ and HIGHESTMODSEQ fields. By default these fields are available if the remote server advertises the CONDSTORE or the QRESYNC capability. If modseqs are disabled, or not supported by the new server, they can still be used if imapc is configured to have local index files.

Changed: 3.0.0

Earlier versions had a "modseq" feature, which is now enabled by default.

proxyauth
Use Sun/Oracle IMAP-server specific PROXYAUTH command to do master user authentication. Normally this would be done using the SASL PLAIN authentication.
send-id
Send session ID with the IMAP ID x-session-ext-id parameter. If login_trusted_networks on the target host is configured to trust the connecting imapc IP, the session ID is preserved as the new imapc connection's session ID prefix.
throttle:<INIT>:<MAX>:<SHRINK>

When receiving [THROTTLED] response (from GMail), throttling is applied.

INIT = initial throttling msecs (default: 50 ms), afterwards each subsequent [THROTTLED] doubles the throttling until MAX is reached (default: 16000 ms). When [THROTTLED] is not received for a while, it's shrunk again. The initial shrinking is done after SHRINK (default: 500 ms). If [THROTTLED] is received again within this timeout, it's doubled, otherwise both throttling and the next shrinking timeout is shrank to 3/4 the previous value.

Optimizations
no-fetch-bodystructure

Disable fetching of IMAP BODY and BODYSTRUCTURE from the remote server. Instead, the whole message body is fetched to regenerate them.

Changed: 3.0.0

Earlier versions had a "fetch-bodystructure" feature, which is now enabled by default.

no-fetch-headers

Disable fetching of specific message headers from the remote server using the IMAP FETCH BODY.PEEK[HEADER.FIELDS(...)] command. Instead, the whole header is fetched and the wanted headers are parsed from it.

Changed: 3.0.0

Earlier versions had a "fetch-headers" feature, which is now enabled by default.

no-fetch-size

Disable fetching of message sizes from the remote server using the IMAP FETCH RFC822.SIZE command. Instead, the whole message body is fetched to calculate the size.

Changed: 3.0.0

Earlier versions had a "rfc822.size" feature, which is now enabled by default.

no-metadata
Disable the detection of the METADATA capability from the remote server. The client will receive a NO [UNAVAILABLE] response for any request that requires access to metadata on the remote server (the same happens if the server does not announce the capability at all).
no-search

Disable searching messages using the IMAP SEARCH command. Instead, all the message headers/bodies are fetched to perform the search locally.

Changed: 3.0.0

Earlier versions had a "search" feature, which is now enabled by default.

Workarounds
fetch-fix-broken-mails

If a FETCH returns NO (but not NO [LIMIT] or NO [SERVERBUG]), assume the mail is broken in server and just treat it as if it were an empty email.

DANGER

This is often a dangerous option! It's not safe to assume that NO means a permanent error rather than a temporary error. This feature should be enabled only for specific users who have been determined to be broken.

fetch-msn-workarounds
Try to ignore wrong message sequence numbers in FETCH replies whenever possible, preferring to use the returned UID number instead.
no-examine
Use SELECT instead of EXAMINE even when we don't want to modify anything in the mailbox. This is a Courier-workaround where it didn't permanently assign UIDVALIDITY to an EXAMINEd mailbox, but assigned it for SELECTed mailbox.
no-qresync Added: 3.0.0
This can be used to work around a Zimbra bug where it doesn't send untagged "OK [CLOSED]" imap-resp-code when selecting a folder.
zimbra-workarounds
Fetch full message using BODY.PEEK[HEADER] BODY.PEEK[TEXT] instead of just BODY.PEEK[] because the header differs between these two when there are illegal control chars or 8bit chars. This mainly caused problems with dsync, but this should no longer be a problem and there's probably no need to enable this workaround.

imapc_host

Default[None]
Valuestring

The remote IMAP host to connect to.

imapc_list_prefix

Default[None]
Valuestring

Access only mailboxes under this prefix.

Example, for a source IMAP server that uses an INBOX namespace prefix:

imapc_list_prefix = INBOX

imapc_master_user

Default[None]
Valuestring
See Also

The master username to authenticate as on the remote IMAP host.

To authenticate as a master user but use a separate login user, the following configuration should be employed, where the credentials are represented by masteruser and masteruser-secret:

imapc_user = %{user}
imapc_master_user = masteruser
imapc_password = masteruser-secret

Mail user variables can be used.

imapc_max_idle_time

Default29 mins
Valuetime

Send a command to the source IMAP server as a keepalive after no other command has been sent for this amount of time.

Dovecot will send either NOOP or DONE to the source IMAP server.

imapc_max_line_length

Defaultunlimited
Valuesize

The maximum line length to accept from the remote IMAP server.

This setting is used to limit maximum memory usage.

imapc_port

Default143
ValuePort Number

The port on the remote IMAP host to connect to.

imapc_rawlog_dir

Default[None]
Valuestring
See Also

Log all IMAP traffic input/output to this directory.

imapc_sasl_mechanisms

Defaultplain
ValueBoolean List

The SASL mechanisms to use for authentication when connection to a remote IMAP server.

The first one advertised by the remote IMAP sever is used.

imapc_sasl_mechanisms {
  external = yes
  plain = yes
  login = yes
}

Supported mechanisms are:

  • ANONYMOUS
  • EXTERNAL
  • LOGIN
  • OAUTHBEARER
  • PLAIN
  • SCRAM-SHA-1
  • SCRAM-SHA-1-PLUS
  • SCRAM-SHA-256
  • SCRAM-SHA-256-PLUS
  • XOAUTH2

Note that imapc_password is ignored for ANONYMOUS and EXTERNAL mechanisms. For OAUTHBEARER and XOAUTH2 imapc_password should be bearer token.

imapc_ssl

Defaultno
Valuestring
Allowed Valuesnoimapsstarttls

Use TLS to connect to the remote IMAP server.

Value Description
no No TLS
imaps Explicitly connect to remote IMAP port using TLS
starttls Use IMAP STARTTLS command to switch to TLS connection

imapc_ssl_verify

Defaultyes
Valueboolean
See Also
Changes

Verify remote IMAP TLS certificate?

Verification may be disabled during testing, but should be enabled during production use.

Only used if imapc_ssl is enabled.

imapsieve_expunge_discarded

Defaultno
Valueboolean
See Also
Pluginimap-sieve plugin

This setting determines whether de IMAPSieve plugin implicitly also expunges messages that were discarded by the executed Sieve script sequence; i.e., Sieve yielded no (implicit) keep.

imapsieve_url

Default[None]
ValueURL
See Also
Pluginimap-sieve plugin

If set, support for user Sieve scripts in IMAP is enabled.

The value is an URL pointing to the ManageSieve server that users must use to upload their Sieve scripts.

Leave this setting empty if you don't want users to have the ability to associate Sieve scripts with mailboxes.

This has no effect on the administrator-controlled Sieve scripts.

imapsieve_url = sieve://sieve.example.com

import_environment

Default TZ=%{env:TZ} CORE_OUTOFMEM=%{env:CORE_OUTOFMEM} CORE_ERROR=%{env:CORE_ERROR} PATH=%{env:PATH} MALLOC_MMAP_THRESHOLD_=131072

Also systemd environments: LISTEN_PID=%{env:LISTEN_PID} LISTEN_FDS=%{env:LISTEN_FDS} NOTIFY_SOCKET=%{env:NOTIFY_SOCKET}
ValueString List

A list of environment key=value pairs, that are preserved and passed to all child processes.

The value can be determined from the existing environment upon Dovecot startup or directly specified.

Example:

import_environment {
  TZ = :/etc/localtime
  TMPDIR = /dovecot-tmp
}

inet_listener_address

Default[None]
ValueIP addresses

Overrides the listen setting for this listener.

inet_listener_haproxy

Defaultno
Valueboolean

If yes, this listener is configured for use with HAProxy. It expects a Proxy Protocol header right after accepting the connection. Connections are aborted immediately if this protocol is violated.

inet_listener_port

Default[None]
ValuePort Number

Port number where to listen. 0 disables the listener.

inet_listener_ssl

Defaultno
Valueboolean
See Also

If yes, the listener does an immediate SSL/TLS handshake after accepting a connection. This is needed for e.g. the imaps and pop3s ports.

INFO

All listeners with ssl=yes will be removed if the global ssl setting is no.

Regardless of the value for listener's ssl setting, some services will still try to initialize encryption if the global ssl is yes. This is for example done to accommodate STARTTLS commands for IMAP/SUBMISSION/LMTP protocols. In other words, SSL is truly disabled only when the global ssl is no.

inet_listener_type

Default[None]
Valuestring
Changes
  • Added: 3.1.0

Listener type. This string value has service-specific meaning and is used to distinguish different listener types that one service may employ.

info_log_path

Defaultlog_path
Valuestring

The log file to use for informational messages.

instance_name

Defaultdovecot
Valuestring

For multi-instance setups, supply the unique name of this Dovecot instance.

This simplifies use of commands such as doveadm: rather than using -c and the config path, you can use the -i flag with the relevant instance name.

intercept_box_path

Default[None]
Valuestring
Pluginintercept-box plugin

Path to save the mail intercepted via the intercept-box plugin.

For example:

intercept_box_path = %{crypted_user}/%{timestamp}.%{generate:guid128}.SMTP.%{type}.eml

Variable substitutions supported:

Variable Description
user user@domain (based on the folder name)
crypted_user user@domain encrypted via intercept_crypted_user
timestamp timestamp (based on the folder name)
type type (based on the folder name)

Mail User Variables can also be used.

intercept_buffer_max_size

Default0
Valuesize

Write intercept buffers larger than this into temporary files in intercept_buffer_dir.

If 0, buffers are always kept in memory.

intercept_crypted_user

Default[None]
Valuestring

Value for the %{crypted_user} variable. The most secure way to generate this is to generate a unique identifier for each intercept request's intercept_id and use that as the salt:

intercept_crypted_user = %{user | encrypt(key='secret',salt=userdb:intercept_id,raw=1)}

For backwards compatibility with old intercept_crypt_* settings, use:

intercept_crypted_user = %{user | encrypt(hash='sha1',rounds=16,key='intercept_crypt_key',salt='intercept_crypt_key',algorithm='intercept_crypt_cipher',raw=1)}

intercept_debug

Defaultno
Valueboolean

Normally, the intercept plugins don't log much of anything, even in error situations, because we want to avoid making visible which users are being intercepted.

Set this value to true to output additional debugging information.

intercept_driver

Default[None]
Valuestring

The intercept driver to use. Configure this via the intercept_driver setting instead.

intercept_fs

ValueNamed Filter

Named filter for intercept FS driver settings.

intercept_fs_header_line

Default[None]
Valuestring

Add a header to the log.

See variables for supported variable substitutions.

intercept_fs_rotate_at_midnight

Defaultno
Valueboolean

Rotate the log at midnight (server's local timezone).

intercept_fs_rotate_interval

Default5min
Valuetime

Flush log and create a new one this often.

intercept_fs_rotate_size

Default[None]
Valuesize

Rotate the log when it reaches this size.

If 0, never rotate.

intercept_id

Default[None]
Valuestring

If set, intercept is activated for this user.

Additionally, this value is passed to the intercept-proxy as an intercept-ID in the interception session.

Note

This is intended to be set in a user's session by userdb lookup.

It is documented here for completion's sake.

Note

The login-intercept plugin uses passdb: Extra Fields instead of this value.

intercept_pine

ValueNamed Filter

Named filter for intercept Pine driver settings.

intercept_pine_host

Default[None]
Valuestring

PineApp server's hostname.

intercept_pine_port

Default[None]
ValuePort Number

PineApp server's port.

WARNING

This value must be set if using PineApp, or else Dovecot will not start.

intercept_tz

Default<system time zone>
Valuestring

Allows choosing a time zone for the proxy that is different than the default system time zone. This is useful for some backends (Utimaco) that use timestamps without time zone field and expect a specific time zone.

The syntax is identical to the TZ environment variable.

intercept_utimaco

ValueNamed Filter

Named filter for intercept Utimaco driver settings.

intercept_utimaco_x3_kafka_brokers

Default[None]
Valuestring

A list of brokers that are used to establish an initial connection to the Kafka cluster. At least one is required when Kafka is used. It is not required to list all brokers in the cluster; the full list is established during protocol initialization.

Separate brokers with spaces, , or ; in the setting.

intercept_utimaco_x3_kafka_consume_interval

Default[None]
Valuetime

The maximum time a broker is requested to wait before responding to a consumer. If there are no messages queued, the broker will respond with an empty list of messages. Use this to keep the connection with the broker active.

intercept_utimaco_x3_kafka_topic

Default[None]
Valuestring

The name of the Kafka topic the event messages are submitted to. This setting determines whether kafka is used; if this is not configured, the system will attempt direct submission to the X3 endpoint through HTTP.

intercept_utimaco_x3_url

Default[None]
ValueURL

The HTTP URL of the Utimaco X3 receiver.

language

Default<textcat dir>
ValueNamed List Filter
Dependencies
See Also
Pluginfts plugin

Defines a language to be used in tokenization.

At least one language must be specified and one single language must be flagged as the default language using language_default = yes.

The language listed first is the default and is used when language recognition fails.

The filters used for stemming and stopwords are language dependent.

TIP

For better performance it's recommended to synchronize this setting with the textcat configuration file; see textcat_config_path.

Example:

language en {
  default = yes
}
language de {
}

language_default

Defaultno
Valueboolean
Dependencies
See Also
Pluginfts plugin

The language marked as default will be used when language detection cannot identify the proper language of the text being processed.

Exactly one language must be marked with this flag.

language_filter_normalizer_icu_id

DefaultAny-Lower; NFKD; [: Nonspacing Mark :] Remove; [\x20] Remove
Valuestring
Pluginfts plugin

Description of the normalizing/transliterating rules to use.

See Normalizer Format for syntax.

language_tokenizer_generic_algorithm

Defaultsimple
Valuestring
Allowed Valuessimpletr29
See Also
Pluginfts plugin

Defines the method for finding word boundaries.

Value Description
simple Faster algorithm that works for many texts, especially using the latin alphabets, but leaves corner cases.
tr29 Implements a version of Unicode technical report 29 word boundary lookup. It might work better with texts containing e.g. Katakana or Hebrew characters, but it is not possible to use a single algorithm for all existing languages.

language_tokenizer_generic_wb5a

Defaultno
Valueboolean
See Also
Pluginfts plugin

Unicode TR29 rule WB5a setting to the tr29 tokenizer. Splits prefixing contracted words from base word. E.g. l'homme -> l and homme. Together with a language specific stopword list unnecessary contractions can thus be filtered away. This is disabled by default and only works with the TR29 algorithm.

Enable by declaring:

language_tokenizer_kuromoji_icu_id

DefaultAny-NFKC
Valuestring
See Also
Pluginfts plugin

Description of the normalizing/transliterating rules to use. See Normalizer Format for syntax.

Defaults to Any-NFKC which is quite good for CJK text mixed with latin alphabet languages. It transforms CJK characters to full-width encoding and transforms latin ones to half-width. The NFKC transformation is described above.

WARNING

If this setting is changed, existing FTS indexes will produce unexpected results. The FTS indexes should be recreated in this case.

last_login

ValueNamed Filter
Pluginlast-login plugin

Named filter for initializing dictionary used to store last login information.

Example:

redis_host = 127.0.0.1
redis_port = 6379
last_login {
  dict redis {
  }
}

last_login_key

Defaultlast-login/%{user}
Valuestring
Pluginlast-login plugin

The key that is updated in the dictionary with the last login information.

last_login_precision

Defaults
Valuestring
Allowed Valuessmsusns
Pluginlast-login plugin

Precision for last login timestamp.

last_valid_gid

Default[None]
Valueunsigned integer
See Also

This setting and first_valid_gid specify the valid GID range for users.

A user whose primary GID is outside this range is not allowed to log in.

0 means there is no explicit last GID.

If the user belongs to any supplementary groups, the corresponding IDs are not set.

last_valid_uid

Default[None]
Valueunsigned integer
See Also

This setting and first_valid_uid specify the valid UID range for users.

0 means there is no explicit last UID.

A user whose UID is outside this range is not allowed to log in.

lazy_expunge_mailbox

Default[None]
Valuestring
See Also
Pluginlazy-expunge plugin

The mailbox to move messages to when expunged. This setting MUST be defined or else lazy-expunge plugin will not be active.

lazy_expunge_mailbox = .EXPUNGED
namespace inbox {
  mailbox Drafts {
    lazy_expunge_mailbox =
  }
  namespace "External accounts" {
    lazy_expunge_mailbox =
  }
}

lazy_expunge_only_last_instance

Defaultno
Valueboolean
Pluginlazy-expunge plugin

If yes, only move to expunged storage if this is the last copy of the message in the user's account. This prevents the same mail from being duplicated in the lazy-expunge folder as the mail becomes expunged from all the folders it existed in.

This setting prevents copying mail to the lazy-expunge folder when using the IMAP MOVE command. When using COPY/EXPUNGE, this setting prevents duplicates only with the following mailbox formats:

lda_mailbox_autocreate

Defaultno
Valueboolean

Should LDA create a nonexistent mailbox automatically when attempting to save a mail message?

lda_mailbox_autosubscribe

Defaultno
Valueboolean

Should automatically created mailboxes be subscribed to?

lda_original_recipient_header

Default<lda/lmtp specific>
Valuestring

The header from which the original recipient address (used in the SMTP RCPT TO: address) is obtained if that address is not available elsewhere.

With LDA the default is based on the username in -d parameter. With LMTP Server the default is the same as RCPT TO.

Example:

lda_original_recipient_header = X-Original-To

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_auth_sasl_authz_id

Default[None]
Valuestring

SASL authorization ID, ie. the ldap_auth_dn_password is for this "master user", but the ldap_auth_dn is still the logged in user. Normally you want to keep this empty.

ldap_auth_sasl_mechanisms

Default[None]
ValueBoolean List

List of SASL mechanism names to use.

ldap_auth_sasl_realm

Default[None]
Valuestring

SASL realm to use.

ldap_base

Default[None]
Valuestring

LDAP base.

Settings variables can be used.

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

ldap_connection_group

Default[None]
Valuestring

Only databases with the same connection group share the ldap connections. By default all the databases have the same ""(empty string) default connection group, and as such share the connections.

ldap_debug_level

Default[None]
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_deref

Defaultnever
Valuestring
Allowed Valuesneversearchingfindingalways

Specify dereference which is set as an LDAP option.

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

ldap_version

Default3
Valueunsigned integer

LDAP protocol version to use. Likely 2 or 3.

listen

Default*, ::
ValueIP addresses

A comma-separated list of IP addresses or hostnames on which external network connections will be handled.

* listens at all IPv4 interfaces, and :: listens at all IPv6 interfaces.

Example:

listen = 127.0.0.1, 192.168.0.1

lmtp_add_received_header

Defaultyes
Valueboolean

Controls if "Received:" header should be added to delivered mails.

lmtp_client_workarounds

Default[None]
ValueBoolean List

Configures the list of active workarounds for LMTP client bugs. Supported workaround identifiers are:

whitespace-before-path
Allow one or more spaces or tabs between 'MAIL FROM:' and path and between 'RCPT TO:' and path.
mailbox-for-path
Allow using bare Mailbox syntax (i.e., without <...>) instead of full path syntax.

lmtp_hdr_delivery_address

Defaultfinal
Valuestring
Allowed Valuesalternativefinalnone

The recipient address to use for the "Delivered-To:" header and the relevant "Received:" header.

Options:

alternative
Address from the RCPT TO OCRPT parameter
final
Address from the RCPT TO command
none
No address (always used for messages with multiple recipients)

lmtp_proxy

Defaultno
Valueboolean
See Also

If yes, LMTP sessions perform a passdb lookup to see if the user should be proxied. The user is proxied only if the proxy extra field is returned. The proxy destination is determined via returned passdb extra fields.

This setting is required with Palomar cluster configuration even in backends, because the backend may still ask proxy to reject the connection and proxy the user to another backend.

lmtp_proxy_rawlog_dir

Default[None]
Valuestring
See Also

Directory location to store raw LMTP proxy protocol traffic logs.

Mail service user variables can be used. However, because LMTP session starts without a user, all user-specific variables expand to empty.

lmtp_rawlog_dir

Default[None]
Valuestring
See Also

Directory location to store raw LMTP protocol traffic logs.

Mail service user variables can be used. However, because LMTP session starts without a user, all user-specific variables expand to empty.

lmtp_rcpt_check_quota

Defaultno
Valueboolean

Should quota be verified before a reply to RCPT TO is issued?

If active, this creates a small amount of extra overhead so it is disabled by default.

lmtp_save_to_detail_mailbox

Defaultno
Valueboolean

If the recipient address includes a detail element / role (as in user+detail format), save the message to the detail mailbox.

lmtp_user_concurrency_limit

Default10
Valueunsigned integer
Changes
  • Changed: 3.1.0

    Changed from unlimited to 10.

Limit the number of concurrent deliveries to a single user to this maximum value.

It is useful if one user is receiving numerous mail messages and thereby causing delays to other deliveries.

To prevent limiting concurrent user deliveries set this to unlimited.

lock_method

Defaultfcntl
Valuestring
Allowed Valuesfcntlflockdotlock

Specify the locking method to use for index files.

Options:

dotlock
mailboxname.lock file created by almost all software when writing to mboxes. This grants the writer an exclusive lock over the mbox, so it's usually not used while reading the mbox so that other processes can also read it at the same time. So while using a dotlock typically prevents actual mailbox corruption, it doesn't protect against read errors if mailbox is modified while a process is reading.
flock
flock() system call is quite commonly used for both read and write locking. The read lock allows multiple processes to obtain a read lock for the mbox, so it works well for reading as well. The one downside to it is that it doesn't work if mailboxes are stored in NFS.
fcntl
Very similar to flock, also commonly used by software. In some systems this fcntl() system call is compatible with flock(), but in other systems it's not, so you shouldn't rely on it. fcntl works with NFS if you're using lockd daemon in both NFS server and client.

log_core_filter

Default[None]
Valuestring

Crash after logging a matching event. The syntax of the filter is described in Global Metric Filters.

For example:

log_core_filter = category=error

will crash any time an error is logged, which can be useful for debugging.

log_path

Defaultsyslog
Valuestring
See Also

Specify the log file to use for error messages.

Options:

  • syslog: Log to syslog
  • /dev/stderr: Log to stderr

If you don't want to use syslog, or if you just can't find the Dovecot's error logs, you can make Dovecot log elsewhere as well:

log_path = /var/log/dovecot.log

If you don't want errors, info, and debug logs all in one file, specify info_log_path or debug_log_path as well:

log_path = /var/log/dovecot.log
info_log_path = /var/log/dovecot-info.log

log_timestamp

Default%b %d %H:%M:%S
ValueString without variables

The prefix for each line written to the log file.

% variables are in strftime(3) format.

login_log_format_elements

Defaultuser=<%{user}> method=%{mechanism} rip=%{remote_ip} lip=%{local_ip} mpid=%{mail_pid} %{secured} session=<%{session}>
ValueString without variables

A space-separated list of elements of the login log formatting.

Elements that have a non-empty value are joined together to form a comma-separated string.

Login variables can be used.

login_plugin_dir

Default/usr/lib64/dovecot/login
Valuestring

Location of the login plugin directory.

login_plugins

Default[None]
ValueBoolean List

List of plugins to load for IMAP and POP3 login processes.

login_proxy_max_disconnect_delay

Default30 secs
Valuetime

Specify the delayed disconnection interval of clients when there is a server mass-disconnect.

For prevention of load spikes when a backend server fails or is restarted, disconnection is spread over the amount of time indicated.

0 disables the delay.

login_proxy_max_reconnects

Default3
Valueunsigned integer

How many times login proxy will attempt to reconnect to destination server on connection failures (3 reconnects = total 4 connection attempts).

Reconnecting is done for most types of failures, except for regular authentication failures.

There is a 1 second delay between each reconnection attempt.

If login_proxy_timeout is reached, further reconnects aren't attempted.

login_proxy_rawlog_dir

Default[None]
Valuestring
See Also

Login processes write rawlogs for proxied connections to this directory for debugging purposes. Note that login processes are usually chrooted, so the directory is relative to $base_dir/login/.

login_proxy_timeout

Default30 secs
Valuetime (milliseconds)

Timeout for login proxy failures.

The timeout covers everything from the time connection is started until a successful login reply is received.

This can be overwritten by proxy passdb passdb extra field.

This setting applies only to proxying via login processes, not to lmtp or doveadm processes.

login_source_ips

Default[None]
ValueIP addresses

Value Format: List of trusted network ranges, see Boolean List.

A list of hosts / IP addresses that are used in a round-robin manner for the source IP address when the proxy creates TCP connections.

Example:

login_source_ips {
  proxy-sources.example.com = yes
}

login_trusted_networks

Default[None]
ValueIP addresses

Value Format: List of trusted network ranges, see Boolean List.

This setting is used for a few different purposes, but most importantly it allows the client connection to tell the server what the original client's IP address was. This original client IP address is then used for logging and authentication checks.

Client connections from trusted networks are also treated as secured unless ssl = required. Plaintext authentication is always allowed for secured connections (auth_allow_cleartext is ignored).

Localhost connections are secured by default, but they are not trusted by default. If you want localhost to be trusted, it needs to be included in this setting.

The details of how this setting works depends on the used protocol:

IMAP

ID command can be used to override:

  • Session ID
  • Client IP and port (%{remote_ip}, %{remote_port})
  • Server IP and port (%{local_ip}, %{local_port})

forward_* fields can be sent to auth process's passdb lookup

The trust is always checked against the connecting IP address. Except if HAProxy is used, then the original client IP address is used.

POP3

XCLIENT command can be used to override:

  • Session ID
  • Client IP and port (%{remote_ip}, %{remote_port})

forward_* fields can be sent to auth process's passdb lookup

The trust is always checked against the connecting IP address. Except if HAProxy is used, then the original client IP address is used.

ManageSieve

XCLIENT command can be used to override:

  • Session ID
  • Client IP and port (%{remote_ip}, %{remote_port})

The trust is always checked against the connecting IP address. Except if HAProxy is used, then the original client IP address is used.

Submission

XCLIENT command can be used to override:

  • Session ID
  • Client IP and port (%{remote_ip}, %{remote_port})
  • HELO - Overrides what the client sent earlier in the EHLO command
  • LOGIN - Currently unused
  • PROTO - Currently unused

forward_* fields can be sent to auth process's passdb lookup

The trust is always checked against the connecting IP address. Except if HAProxy is used, then the original client IP address is used.

LMTP

XCLIENT command can be used to override:

  • Session ID
  • Client IP and port (%{remote_ip}, %{remote_port})
  • HELO - Overrides what the client sent earlier in the LHLO command
  • LOGIN - Currently unused
  • PROTO - Currently unused
  • TIMEOUT (overrides mail_max_lock_timeout)

The trust is always checked against the connecting IP address. Except if HAProxy is used, then the original client IP address is used.

lua_settings

Default[None]
ValueString List
See Also

Key-value pairs that are passed as a table to lua script_init() functions.

mail_access_groups

Default[None]
ValueBoolean List

Supplementary groups that are granted access for mail processes.

Typically, these are used to set up access to shared mailboxes.

WARNING

It may be dangerous to set these up if users can create symlinks.

Examples for if the "mail" group is chosen here:

  • ln -s /var/mail ~/mail/var could allow a user to delete others' mailboxes, or
  • ln -s /secret/shared/box ~/mail/mybox would allow reading others' mail.

mail_alt_check

Defaultyes
Valueboolean
See Also

Whether to perform a sanity check and warn if mail_alt_path changes from the last access. This can catch accidentally broken configurations before users start reporting missing mails. The downside to this check is some additional disk IO.

mail_always_cache_fields

Default flags hdr.date hdr.subject hdr.from hdr.sender hdr.reply-to hdr.to hdr.cc hdr.bcc hdr.in-reply-to hdr.message-id date.received size.virtual imap.bodystructure mime.parts hdr.references hdr.importance hdr.x-priority hdr.x-open-xchange-share-url pop3.uidl pop3.order

Changed: 3.1.0 The default fields were changed. They used to be empty.
ValueBoolean List
See Also

The fields specified here are always added to cache when saving mails, even if the client never accesses these fields.

See mail cache configuration for details and for the list of fields.

mail_attachment_detection_options

Default add-flags "content-type=!application/signature"

Changed: 3.1.0 The default value was added. It used to be empty.
ValueBoolean List

Settings to control adding $HasAttachment or $HasNoAttachment keywords. By default, all MIME parts with Content-Disposition=attachment or inlines with filename parameter are considered attachments.

To enable this feature, this setting needs at least one option specified. Multiple options can be added in a space-separated list.

Options:

add-flags
Attachments are detected and marked during save. Detection is done also during fetch if it can be done without extra disk IO and with minimal CPU cost. This means that either both mime.parts and imap.bodystructure has to be in cache already, or if mail body is opened in any case.
add-flags no-flags-on-fetch
Flags are added during save, but not during fetch. This option will likely be removed in a later release.
content-type=<type|!type>
Include or exclude given content type. Including will only negate an exclusion (e.g. content-type=!foo/* content-type=foo/bar).
exclude-inlined
Do not consider any attachment with disposition inlined.

mail_attribute

ValueNamed Filter
See Also

Named filter for initializing dict driver for server and mailbox attributes (key=value).

This is used by the URLAUTH and METADATA extensions, as well as various other features.

Example:

mail_attribute {
  dict file {
    path = %{home}/dovecot-attributes
  }
}

mail_cache_fields

Default flags hdr.date hdr.subject hdr.from hdr.sender hdr.reply-to hdr.to hdr.cc hdr.bcc hdr.in-reply-to hdr.message-id date.received size.virtual imap.bodystructure mime.parts hdr.references hdr.importance hdr.x-priority hdr.x-open-xchange-share-url pop3.uidl pop3.order

Changed: 3.1.0 The default fields were changed. They used to be just "flags".
ValueBoolean List
See Also

The default list of fields that are added to cache if no other caching decisions exist yet. This setting is used only when creating the initial INBOX for the user. Other folders get their defaults from the INBOX.

See mail cache configuration for details and for the list of fields.

mail_cache_path

Default<same as mail_index_path setting>
Valuestring

Place dovecot.index.cache files to this directory instead of among the other index files. This may be used as an optimization to split most index files to the fastest (smallest) storage while keeping cache files in a slightly slower (larger) storage.

mail_chroot

Default[None]
Valuestring

The default chroot directory for mail processes.

This chroots all users globally into the same directory.

Mail service user variables can be used.

mail_control_path

Default[None]
Valuestring

Location for (mailbox-format specific) control files.

mail_debug

Defaultno
Valueboolean

This setting adjusts log verbosity. It enables mail-process debugging. This can help you figure out the reason if Dovecot isn't finding certain mail messages.

mail_ext_attachment

ValueNamed Filter
See Also

Named filter for initializing FS Driver for external attachments.

Commonly used options:

posix

No single-instance storage (SIS) done (this option might simplify the filesystem's own de-duplication operations).

sis

SIS with immediate byte-by-byte comparison during saving.

SIS is deprecated and writing of SIS files is disabled. Reading is supported for now, any missing SIS attachments are replaced with files filled with spaces.

sis-queue

SIS with delayed comparison and de-duplication.

Changed: 3.1.0 SIS is deprecated and writing SIS files is disabled. Reading is supported for now. Any missing SIS attachments are replaced with files filled with spaces.

mail_ext_attachment_path

Default[None]
Valuestring

The directory in which to store mail attachments.

With sdbox and mdbox, mail attachments can be saved to external files, which also allows single-instance storage of them.

If no value is specified, attachment saving to external files is disabled.

Mail user variables can be used.

mail_fsync

Defaultnever for obox; optimized for others
Valuestring
Allowed Valuesalwaysoptimizednever

Specify when to use fsync() or fdatasync() calls.

Using fsync waits until the data is written to disk before it continues, which is used to prevent corruption or data loss in case of server crashes.

This setting applies to mail files and index files on the filesystem. This setting doesn't apply to object storage operations.

Options:

always

Use fsync after all disk writes.

Recommended for NFS to make sure there aren't any delayed write()s.

optimized

Use fsync after important disk writes.

For example cache file writes aren't fsynced, because they can be regenerated if necessary.

never

Never fsync any disk writes.

This provides the best performance, but risks losing recently saved emails in case of a crash with most mailbox formats.

mail_gid

Defaultvmail
Valuestringunsigned integer
See Also

The system group ID used for accessing mail messages.

Can be either a numeric ID or a group name.

This can be overridden via the gid userdb field.

mail_inbox_path

Default[None]
Valuestring
See Also

Path to the INBOX mailbox. The path doesn't have to be absolute - it is relative to the mail_path.

This is often used with mbox format where INBOX is in /var/mail/ while the rest of the folders are under the user's home directory.

This can also be used to specify a different INBOX path with Maildir:

 mail_driver = maildir
 mail_path = ~/Maildir
 mail_inbox_path = ~/Maildir/.INBOX

mail_index_private_path

Default[None]
Valuestring
See Also

The private index files are used with shared mailboxes to provide private (per-user) message flags.

mail_log_cached_only

Defaultno
Valueboolean
Pluginmail-log plugin

If enabled, everything except save event will log only the fields that can be looked up from cache. This improves performance if some of the fields aren't cached and it's not a strict requirement to log them.

mail_log_events

Default[None]
ValueBoolean List
Pluginmail-log plugin

List of events to log.

Available events:

  • delete
  • undelete
  • expunge
  • save
  • copy
  • mailbox_create
  • mailbox_delete
  • mailbox_rename
  • flag_change

mail_log_fields

Default[None]
ValueBoolean List
Pluginmail-log plugin

List of fields to log.

Field Restrictions
uid
box
msgid
size Only available for expunge and copy events.
vsize Only available for expunge and copy events.
vsize
flags
from
subject

mail_log_prefix

Default%{service}(%{user})<%{process:pid}><%{session}>:
Valuestring

You can specify a log prefix for mail processes here.

Mail service user variables can be used.

mail_max_lock_timeout

Default0
Valuetime

This value is used as a timeout for tempfailing mail connections. It can be set globally, for application to all Dovecot services, but is normally better to set it in only certain protocol blocks. You may wish to set a value for this for LMTP and LDA while leaving it at the global default of 0 for IMAP and POP3 connections, which tolerate tempfailing less well.

mail_max_userip_connections

Default10
Valueunsigned integer

The maximum number of IMAP connections allowed for a user from each IP address.

This setting is checked only by backends, not proxies.

Note that for this to work, any username changes must be done already by passdb lookup (not by userdb lookup).

Unique users are identified via case-sensitive comparison.

mail_nfs_storage

Defaultno
Valueboolean

Flush NFS caches whenever it is necessary to do so.

This setting should only be enabled if you are using multiple servers on NFS.

mail_path

Default<specific to mail_driver setting>
Valuestring
See Also

Path to a directory where the mail is stored. Mail User Variables are commonly used here.

Usually the mails should be stored in a sub-directory under the home directory, but not the home directory itself (see Home Directories for Virtual Users).

The path must be absolute, not a relative path. Even if relative paths appear to work, this usage is deprecated and will likely stop working at some point.

mail_plugin_dir

Default/usr/lib64/dovecot
Valuestring
See Also

The directory in which to search for Dovecot mail plugins.

mail_prefetch_count

Default10 for obox; 0 for others
Valueunsigned integer

The number of messages to try to prefetch whenever possible. 0 means that no prefetching is done. Depending on the (remote) storage latency, this may significantly speed up performance when reading many mails. The exact behavior depends on the mailbox format:

  • mbox, mdbox: No effect in behavior.

  • sdbox, Maildir: Call posix_fadvise(POSIX_FADV_WILLNEED) on mail files to instruct kernel to read the whole files into memory.

  • imapc: Combine multiple mail reads into the same remote imapc FETCH command. For example with mail_prefetch_count = 0 reading two mails would result in FETCH 1 BODY.PEEK[] and FETCH 2 BODY.PEEK[] commands, while with mail_prefetch_count = 1 they would be combined into a single FETCH 1:2 BODY.PEEK[] command. The downside is that each mail uses a file descriptor and disk space in mail_temp_dir. A good value is likely between 10..100.

  • obox: Number of mails to download concurrently from object storage.

mail_privileged_group

Default[None]
Valuestring

This group is enabled temporarily for privileged operations. Currently, this is used only with the INBOX when either its initial creation or dotlocking fails.

Typically, this is set to mail to give access to /var/mail.

You can give Dovecot access to mail group by setting mail_privileged_group = mail.

mail_server_admin

Default[None]
Valuestring
See Also

The method for contacting the server administrator.

Per the METADATA standard (RFC 5464), this value MUST be a URI (e.g., a mailto: or tel: URL), but that requirement is not enforced by Dovecot.

This value is accessible to authenticated users through the /shared/admin IMAP METADATA server entry.

Example:

mail_server_admin = mailto:admin@example.com

mail_server_comment

Default[None]
Valuestring
See Also

A comment or note that is associated with the server.

This value is accessible to authenticated users through the /shared/comment IMAP METADATA server entry.

mail_shared_explicit_inbox

Defaultno
Valueboolean

This setting determines whether a shared INBOX should be visible as "shared/user" or as "shared/user/INBOX" instead.

mail_sort_max_read_count

Default100 for obox; 0 for others
Valueunsigned integer

The number of slow mail accesses an IMAP SORT can perform before it returns failure to the client.

On failure, the untagged SORT reply is retuned, but it is likely not correct.

The IMAP reply returned to the client is:

NO [LIMIT] Requested sort would have taken too long.

mail_temp_dir

Default/dev/shm/dovecot
Valuestring

The directory in which LDA/LMTP will temporarily store incoming message data that is above 128kB in size.

Mail user variables can be used.

mail_temp_scan_interval

Default1week
Valuetime

How often Dovecot scans for and deletes stale temporary files. These files exist only if Dovecot crashes while saving a message. This is just to make sure such temporary files will eventually get deleted to avoid wasting disk space. This scan happens independently for each folder, and it's done at the time the folder is opened.

In order to prevent load spikes, the actual value of the setting is spread increasing it by 0..30%, based on a hash of the username.

The scanning is done only for these mailbox formats:

  • Maildir: Delete all files having ctime older than 36 hours from tmp/. The scan is done if tmp/ directory's atime older than this setting.
  • sdbox, mdbox: Delete .temp.* files having ctime older than 36 hours from dbox-Mails/. The scan is done if the last_temp_file_scan header field in dovecot.index is older than this setting.
  • mdbox: Delete .temp.* files having ctime older than 36 hours from storage/. The scan is done if storage/ directory's atime is older than this setting.

A value of 0 means this scan never occurs.

mail_uid

Defaultvmail
Valuestringunsigned integer
See Also

This setting indicates the system userid used for accessing mail messages.

Can be either a numeric ID or a username.

This can be overridden via the uid userdb field.

mail_utf8_extensions

Defaultno
Valueboolean

If Dovecot has been compiled with --enable-experimental-mail-utf8 configure option, this setting can be used to enable the feature. Settings this to yes will enable SMTPUTF8 for LMTP and Submission sessions, and UTF8=ACCEPT for IMAP sessions.

mail_volatile_path

Default[None]
Valuestring

Specifies the location of volatile files. This includes lock files and potentially other files that don't need to exist permanently, so it can point to an in-memory filesystem (tmpfs). This is especially useful to avoid creating lock files to NFS or other remote filesystems.

mail_vsize_bg_after_count

Default[None]
Valueunsigned integer
See Also

Controls transitioning mail size determination to the background instead of synchronously during the delivery process.

After this many messages have been opened, the system allows a background indexer-worker process to perform quota calculations in the background.

This may happen when mail messages do not have their virtual sizes cached.

When indexing is occurring in the background, explicit quota size queries return an internal error and mail deliveries are assumed to succeed.

This setting must not be set to indexer-worker process, or the background calculation isn't finished. The configuration should be like:

protocol !indexer-worker {
  mail_vsize_bg_after_count = 10
}

mailbox

Default[None]
ValueNamed List Filter

Create a new mailbox to the list of mailboxes. The filter name refers to the mailbox_name setting.

The mailbox name can contain ? and * wildcards. Settings are applied for all matching mailbox filters.

TIP

If the mailbox name has spaces, you can put it into quotes:

mailbox "Test Mailbox" {
  # ...
}

TIP

It's possible to rename the mailbox in userdb. For example:

mailbox junk {
  name = Junk
  special_use = \Junk
}

The userdb can then return mailbox/junk/name=Spam to rename the mailbox for a specific user.

mailbox_auto

Defaultno
Valuestring
Allowed Valuescreatenosubscribe

Autocreate and/or subscribe to the mailbox?

Value Description
create Autocreate but don't autosubscribe
no Don't autocreate or autosubscribe
subscribe Autocreate and autosubscribe

Autocreated mailboxes are created lazily to disk only when accessed for the first time. The autosubscribed mailboxes aren't written to subscriptions file, unless SUBSCRIBE command is explicitly used for them.

mailbox_autoexpunge

Default[None]
Valuetime
See Also

Expunge all mails in this mailbox whose saved-timestamp is older than this value.

For IMAP and POP3 this happens after the client is already disconnected.

For LMTP this happens when the user's mail delivery is finished. Note that in case there are multiple recipients, autoexpunging is done only for some of the recipients to prevent delays with the mail delivery: The last recipient user is autoexpunged first. Next, the first recipient user is autoexpunged (because the first user's mail was kept open in case it could be directly copied to the other users). None of the middle recipient users are autoexpunged.

mailbox_list_index = yes is highly recommended when using this setting, as it avoids actually opening the mailbox to see if anything needs to be expunged.

mail_always_cache_fields = date.save is also recommended when using this setting with sdbox or Maildir, as it avoids using stat() to find out the mail's saved-timestamp. With mdbox format this isn't necessary, since the saved-timestamp is always available.

mailbox_autoexpunge_max_mails

Default[None]
Valueunsigned integer

Mails are autoexpunged until mail count is at or below this number of messages.

Once this threshold has been reached, mailbox_autoexpunge processing is done.

mailbox_directory_name

Default<specific to mail_driver setting>
Valuestring
See Also

Specifies the directory name used for mailbox, index, and control directory paths. See the individual mailbox format pages for further information. For example dbox-Mails with dbox.

With mbox format this works differently. The user-provided mailbox name is the directory name, while mailbox_directory_name is the mbox file. For example with mailbox_directory_name=mbox, creating foo/bar mailbox name ends up creating .../foo/bar/mbox file.

mailbox_directory_name_legacy

Defaultno
Valueboolean
See Also

If no, mailbox_directory_name applies also to index and control directories. The only reason to set this to yes is if you already have an existing Dovecot installation with the legacy DIRNAME (rather than FULLDIRNAME) parameter and don't want to migrate the data.

mailbox_list_drop_noselect

Defaultyes
Valueboolean

Specifies whether to automatically delete NoSelect mailboxes that have no children. These mailboxes are sometimes confusing to users. Also if a NoSelect mailbox is attempted to be created with CREATE box/, it's created as selectable mailbox instead.

INFO

Maildir layout does not support NoSelect mailboxes, so this setting has no effect with it.

mailbox_list_index

Defaultyes
Valueboolean

Dovecot indexes live at the root of user's mailbox storage, and allows quick lookup of mailbox status instead of needing to open all mailbox indexes separately.

Enabling this optimizes the server reply to IMAP STATUS commands, which are commonly issued by clients. This also needs to be enabled if you wish to enable the IMAP NOTIFY extension.

mailbox_list_index_include_inbox

Defaultno
Valueboolean
See Also

Should INBOX be kept up-to-date in the mailbox list index?

Disabled by default as most mailbox accesses will open INBOX anyway.

mailbox_list_index_prefix

Defaultdovecot.list.index
Valuestring

Prefix for the mailbox list index filename. It may also optionally include a path (relative to mail_index_path) to place it in a different directory.

mailbox_list_index_very_dirty_syncs

Defaultno
Valueboolean

If enabled, assume that the mailbox list index is fully updated so that stat() will not be run for mailbox files/directories.

mailbox_list_iter_from_index_dir

Defaultno
Valueboolean

Perform mailbox listing using the mail_index_path directories instead of the mail_path directories. Mainly useful when the index file storage is on a faster storage.

mailbox_list_layout

Defaultfs
Valuestring
Allowed ValuesfsindexMaildir++
See Also

Directory layout to use.

Value Description
Maildir++ The default used by Maildir.
fs The default used by mbox and dbox.
index The default used by obox plugin. Uses mailbox GUIDs as the directory names. The mapping between mailbox names and GUIDs exists in dovecot.list.index* files.

INFO

The mail_driver setting provides the default value, that the mailbox_list_layout setting can override.

mailbox_list_storage_escape_char

DefaultThe default for imapc storage is %.
Valuestring
See Also

Specifies an escape character that it used for encoding special characters in the mailbox names in storage. This allows users to use characters in mailboxes names that would otherwise be illegal. For example:

  • Maildir layout disallows using the . character, since it's used internally as the folder hierarchy separator.
  • The ~ character at the beginning of the mailbox name is disallowed, because of the possibility that it gets expanded to user's home directory.
  • The / character can't be used on POSIX filesystems, since it's the directory separator.

The characters are escaped to the mailbox name as <mailbox_list_storage_escape_char><hex>.

INFO

It's possible to use the same character here as for mailbox_list_visible_escape_char.

mailbox_list_utf8

Defaultno
Valueboolean

Store mailbox names on disk using UTF-8 instead of modified UTF-7 (mUTF-7).

mailbox_list_validate_fs_names

Defaultyes
Valueboolean
See Also

Specifies whether to disallow mailbox names that might be unsafe to use in filesystems or potentially allow bypassing ACL checks:

  • / character anywhere in the name (except as a hierarchy separator), unless mailbox list isn't on a filesystem (e.g. index, imapc).
  • / as the first character.
  • ~ as the first character (so it's not confused as home directory).
  • No adjacent / characters.
  • No . or .. names between / characters.
  • No mailbox_directory_name between / characters.
  • No mailbox format-specific internal directories between / characters,
  • unless mailbox_directory_name is non-empty. This mainly means the Maildir new, cur and tmp directories in some configurations.

Enabling mail_full_filesystem_access enables also this setting.

mailbox_list_visible_escape_char

DefaultThe default for imapc storage is ~.
Valuestring
See Also

Specifies an escape character that is used for broken or otherwise inaccessible mailbox names. If mailbox name can't be changed reversibly to UTF-8 and back, encode the problematic parts using <mailbox_list_visible_escape_char><hex>in the user-visible UTF-8 name. The mailbox_list_visible_escape_char itself also has to be encoded the same way.

This can be useful with imapc to access mailbox names that aren't valid mUTF-7 charset from remote servers, or if the remote server uses a different hierarchy separator and has folder names containing the local separator.

INFO

It's possible to use the same character here as for mailbox_list_storage_escape_char.

mailbox_name

Default[None]
Valuestring

Name of the mailbox being configured. The mailbox filter name refers to this setting.

mailbox_notify_status

Defaultno
Valueboolean
Pluginnotify-status plugin

Whether notifications for a single mailbox or mailbox wildcards are enabled.

Example:

mailbox INBOX {
  notify_status = yes
}
mailbox Spam {
  notify_status = yes
}
mailbox *BOX {
  notify_status = yes
}

mailbox_root_directory_name

Defaultspecific to the mail_driver setting
Valuestring

Specifies directory name under which all mailbox directories are stored. For example mailboxes with dbox.

mailbox_special_use

Default[None]
ValueBoolean List
Changes
  • Changed: 3.1.0

    Using non-standard special-use flags will result in a warning message at startup.

List of SPECIAL-USE (RFC 6154) flags to broadcast for the mailbox.

There are no validity checks, so you could specify anything you want here, but it's not a good idea to use other than the standard ones specified in the RFC.

maildir_broken_filename_sizes

Defaultno
Valueboolean
See Also

If enabled, do not obtain a mail message's physical size from the S=<size> data in the Maildir filename except when recalculating the Maildir++ quota.

Defaultyes
Valueboolean
See Also

If enabled, copying of a message is done with hard links whenever possible.

This makes the performance much better, and it's unlikely to have any side effects. The only reason to disable this is if you're using a filesystem where hard links are slow (e.g. HFS+).

maildir_empty_new

Defaultno
Valueboolean
See Also

Should mail messages always be moved from the new/ directory to cur/, even when the Recent flags aren't being reset?

maildir_stat_dirs

Defaultno
Valueboolean
See Also

If enabled, don't include non-directory files in a LIST response that begin with a dot. Thus, if disabled, Dovecot assumes that all the files beginning with a dot in the Maildir are Maildirs.

You shouldn't have any non-directory files beginning with a dot in the Maildirs, but if you do you may need to set this to yes, in which case Dovecot needs to stat() each directory entry, which degrades the performance. Some filesystems (e.g. ext4) provide the directory/non-directory status for free without having to stat(). In those filesystems this setting is ignored.

maildir_very_dirty_syncs

Defaultno
Valueboolean
See Also

If enabled (yes), Dovecot is assumed to be the only MUA that accesses Maildir directly, so the cur/ directory is scanned only when its mtime changes unexpectedly or when the mail cannot otherwise be found.

If enabled and another process (or a Dovecot process which doesn't update index files) does changes to cur/ while the mailbox is simultaneously being modified by Dovecot, Dovecot may not notice those external changes.

It is still safe to deliver new mails to new/ using non-Dovecot software (except with mailbox_list_index = yes, changes aren't noticed outside INBOX).

managesieve_logout_format

Defaultbytes=%{input}/%{output}
ValueString without variables

Specifies the string pattern used to compose the logout message of an authenticated session. The following substitutions are available:

Variable Name Description
%{input} Total number of bytes read from client
%{output} Total number of bytes sent to client
%{put_count} Number of scripts uploaded by client using PUTSCRIPT command
%{put_bytes} Number of bytes with script data sent by client using PUTSCRIPT command
%{get_count} Number of scripts downloaded by client using GETSCRIPT command
%{get_bytes} Number of bytes with script data sent to client using GETSCRIPT command
%{check_count} Number of scripts checked by client using CHECKSCRIPT command
%{check_bytes} Number of bytes with script data sent by client using CHECKSCRIPT command
%{deleted_count} Number of scripts deleted by client using DELETESCRIPT command
%{renamed_count} Number of scripts renamed by client using RENAMESCRIPT command
%{session} The client session ID

mbox_dirty_syncs

Defaultyes
Valueboolean
See Also

Enable optimized mbox syncing?

For larger mbox files, it can take a long time to determine what has changed when the file is altered unexpectedly. Since the change in most cases consists solely of newly appended mail, Dovecot can operate more quickly if it starts off by simply reading the new messages, then falls back to reading the entire mbox file if something elsewhere in it isn't as expected.

Dovecot assumes that external mbox file changes only mean that new messages were appended to it. Without this setting Dovecot re-reads the whole mbox file whenever it changes. There are various safeguards in place to make this setting safe even when other changes than appends were done to the mbox. The downside to this setting is that external message flag modifications may not be visible immediately.

When this setting is enabled, Dovecot tries to avoid re-reading the mbox every time something changes. Whenever the mbox changes (i.e. timestamp or size), Dovecot first checks if the mailbox's size changed. If it didn't, it most likely meant that only message flags were changed so it does a full mbox read to find it. If the mailbox shrunk, it means that mails were expunged and again Dovecot does a full sync. Usually however the only thing besides Dovecot that modifies the mbox is the LDA which appends new mails to the mbox. So if the mbox size was grown, Dovecot first checks if the last known message is still where it was last time. If it is, Dovecot reads only the newly added messages and goes into "dirty mode". As long as Dovecot is in dirty mode, it can't be certain that mails are where it expects them to be, so whenever accessing some mail, it first verifies that it really is the correct mail by finding its X-UID header. If the X-UID header is different, it fallbacks to a full sync to find the mail's correct position. The dirty mode goes away after a full sync. If mbox_lazy_writes was enabled and the mail didn't yet have an X-UID header, Dovecot uses the MD5 sum of a couple of headers to compare the mails.

mbox_dotlock_change_timeout

Default2 mins
Valuetime
See Also

Override a lockfile after this amount of time if a dot-lock exists but the mailbox hasn't been modified in any way.

mbox_lazy_writes

Defaultyes
Valueboolean
See Also

If enabled, mbox headers (e.g., metadata updates, such as writing X-UID headers or flag changes) are not written until a full write sync is performed (triggered via IMAP EXPUNGE or CHECK commands and/or when the mailbox is closed). mbox rewrites can be costly, so this may avoid a lot of disk writes.

Enabling this setting is especially useful with POP3, in which clients often delete all mail messages.

One negative consequence of enabling this setting is that the changes aren't immediately visible to other MUAs.

C-Client works the same way. The upside of this is that it reduces writes because multiple flag updates to same message can be grouped, and sometimes the writes don't have to be done at all if the whole message is expunged. The downside is that other processes don't notice the changes immediately (but other Dovecot processes do notice because the changes are in index files).

mbox_lock_timeout

Default5 mins
Valuetime
See Also

The maximum time to wait for all locks to be released before aborting.

mbox_read_locks

Defaultfcntl
ValueBoolean List
Allowed Valuesdotlockdotlock_tryfcntlflocklockf
See Also

Specify which locking method(s) to use for locking the mbox files during reading.

Descriptions of the locking methods can be found at mbox locking.

mbox_write_locks

Defaultdotlock fcntl
ValueBoolean List
Allowed Valuesdotlockdotlock_tryfcntlflocklockf
See Also

Specify which locking method(s) to use for locking the mbox files during writing.

Descriptions of the locking methods can be found at mbox locking.

mdbox_preallocate_space

Defaultno
Valueboolean
See Also

mdbox only: If enabled, preallocate space for newly created files.

In creation of new mdbox files, their size is immediately preallocated as mdbox_rotate_size.

This setting currently works only in Linux with certain filesystems (ext4 and xfs).

mdbox_rotate_interval

Default[None]
Valuesize
See Also

mdbox only: The maximum age the dbox file may reach before it's rotated.

0 means there is no age-based rotation.

mdbox_rotate_size

Default10M
Valuesize
See Also

mdbox only: The maximum size the dbox file may reach before it is rotated.

message_hashing_min_attachment_size

Default1 B
Valuesize
Pluginmessage-hashing plugin

The minimum size of an attachment to be processed; attachments smaller than this will be skipped.

metacache_close_delay

Default2secs
Valuetime
Pluginobox plugin

If user was accessed this recently, assume the user's indexes are up-to-date. If not, list index bundles in object storage (or Cassandra) to see if they have changed. This typically matters only when user is being moved to another backend and soon back again, or if the user is simultaneously being accessed by multiple backends.

metacache_forced_refresh_interval

Default8 hours
Valuetime
Pluginobox plugin
Changes
  • Added: 3.0.0

If the user indexes haven't been refreshed for this long time, force the refresh. This is done by ignoring the metacache_close_delay setting (i.e. same as if it is 0).

This setting allows highly active users' indexes still to be refreshed once in a while. (Although if the user has an active session 100% of the time, the refresh cannot be done.)

metacache_max_space

Defaultunlimited
Valuesize
Pluginobox plugin

How much disk space metacache can use before old data is cleaned up.

Generally, this should be set at ~90% of the available disk space.

metacache_pull_enabled

Defaultyes
Valueboolean
See Also
Pluginobox plugin

By default metacache pulling is enabled.

The Palomar Proxy's cluster process looks up the metacache_last_host automatically from cluster_geodb and forwards it to the backend. If the looked up host differs from the current host (cluster_backend_name), metacache is pulled from the metacache_last_host backend.

metacache_refresh_index_once_after

Default[None]
Valueunsigned integer
Pluginobox plugin

This forces the next mailbox open after the specified UNIX timestamp to refresh locally cached indexes to see if other backends have modified the user's indexes simultaneously.

metacache_rescan_mails_once_after

Default[None]
Valueunsigned integer
Pluginobox plugin

This forces the next mailbox open after the specified UNIX timestamp to rescan the mails to make sure there aren't any unindexed mails.

metacache_upload_interval

Default5min
Valuetime
Pluginobox plugin

How often to upload important index changes to object storage?

This mainly means that if a backend crashes during this time, message flag changes within this time may be lost. A longer time can however reduce the number of index bundle uploads.

metric_description

Default[None]
Valuestring

Human-readable description of the metric. This is included in the HELP text sent to OpenMetrics.

metric_exporter_include

Defaultname hostname timestamps categories fields
ValueBoolean List

Specifies which parts of the event are exported to the serialized event:

Values Description
name The name of the event.
hostname The name of the host generating this event.
timestamps The event start and end timestamps.
categories A set of categories associated with this event.
fields The fields associated with this event. The fields that will be exported are defined by the metric_fields setting.

For example:

metric example {
  exporter_include = name hostname timestamps
}

includes just the 3 specified parts, while

metric another_example {
  exporter_include =
}

includes nothing and the exported event will be empty (i.e. {} in JSON).

metric_fields

Default[None]
ValueBoolean List
Changes
  • Changed: 3.1.0

    All listed fields are exported to OpenMetrics as well.

A list of fields included in the metric. All events have a default duration field that does not need to be listed explicitly.

metric_group_by_method_discrete_modifier

Default[None]
ValueString without variables
See Also

Configures a modifier string for values grouped by the discrete method. %variables and their functions can be used:

%{value}
The original value.
%{user | domain}
If the value is in user@domain format, this contains the domain text. Otherwise empty.

metric_name

Default[None]
Valuestring

Name of the metric. It is visible in statistics outputs. The metric filter name refers to this setting.

mmap_disable

Defaultno
Valueboolean

Disable mmap() usage?

This must be set to yes if you store indexes to shared filesystems (i.e., if you use NFS or a clustered filesystem).

mysql

Default[None]
ValueNamed List Filter
See Also

Creates a new MySQL connection. If more than one is specified, the connections are automatically used for load balancing and for failover. The filter name refers to the mysql_host setting.

mysql_connect_timeout

Default5s
Valuetime

How long to wait for connection.

mysql_connection_limit

Default5
Valueunsigned integer

Maximum number of parallel connections. Currently MySQL queries are blocking, so only a single connection can be used in parallel.

mysql_dbname

Default[None]
Valuestring

Database name to connect to.

mysql_host

Defaultlocalhost
Valuestring

Host or UNIX socket path to connect to. The mysql setting defaults to this.

INFO

MySQL drivers can default to using UNIX socket connection when host is localhost and port is 0 (default). To force it to use TCP connection, set mysql_host = 127.0.0.1 or set mysql_port explicitly.

mysql_option_file

Default[None]
Valuestring

File to read for client library specific configuration.

mysql_password

Default[None]
Valuestring

Password for authentication.

mysql_port

Default0 (defaults to 3306 for TCP connections)
ValuePort Number

Port to connect to.

mysql_read_timeout

Default30s
Valuetime

Timeout when reading data from server.

mysql_ssl

Defaultno
Valueboolean
See Also

Whether to use SSL when connecting to MySQL. Configure it using the ssl_client_* settings. See SSL.

mysql_user

Default[None]
Valuestring

Username for authentication.

mysql_write_timeout

Default30s
Valuetime

Timeout in seconds when writing data to server.

namespace

Default[None]
ValueNamed List Filter

Creates a new namespace to the list of namespaces. The filter name refers to the namespace_name setting.

Example:

namespace foo {
  [...]
}

namespace_alias_for

Default[None]
Valuestring

Refers to an alias namespace's namespace_name.

If multiple namespaces point to the same location, they should be marked as aliases against one primary namespace. This avoids duplicating work for some commands (listing the same mailbox multiple times).

Mail user variables can be used.

Note: Alias namespaces often have hidden=yes and list=no so they are not visible unless clients have specifically configured them, and they're typically used when migrating to a different namespace prefix for existing users.

Example:

namespace inbox {
  prefix =
  # ...
}
namespace alias {
  prefix = INBOX/
  alias_for = inbox
}

namespace_disabled

Defaultno
Valueboolean

If yes, namespace is disabled and cannot be accessed by user in any way.

Useful when returned by a userdb lookup to easily configure per-user namespaces.

namespace_hidden

Defaultno
Valueboolean

If yes, namespace will be hidden from IMAP NAMESPACE (RFC 2342) command.

namespace_ignore_on_failure

Defaultno
Valueboolean

If namespace's storage initialization fails, by default the entire session will fail to start. If this is set, this namespace will be ignored instead.

namespace_inbox

Defaultno
Valueboolean

If yes, this namespace will be considered the one holding the INBOX folder.

There can be only one namespace defined like this.

namespace_list

Defaultyes
Valuestring
Allowed Valuesyesnochildren
See Also

Include this namespace in LIST output when listing its parent's folders.

Options:

Value Description
children Namespace prefix list listed only if it has child mailboxes.
no Namespace and mailboxes not listed unless listing requests explicitly mailboxes under the namespace prefix.
yes Namespace and mailboxes are always listed.

It is still possible to list the namespace's folders by explicitly asking for them. For example, if this setting is no, using LIST "" * with namespace prefix "lazy-expunge/" won't list it, but using LIST "" lazy-expunge/* lists all folders under it.

namespace_name

Default[None]
Valuestring

Name of the namespace. This is used only in configurations - it's not visible to user. The namespace filter refers to this setting.

namespace_order

Default[None]
Valueunsigned integer

Sets display order in IMAP NAMESPACE (RFC 2342) command.

Namespaces are automatically numbered if this setting does not exist.

namespace_separator

Default"." for Maildir; "/" for other mbox formats
Valuestring
See Also

Specifies the hierarchy separator for the namespace.

The separator is a single character, which can't then otherwise be used in folder names.

The commonly used separators are . and /, but other separators can be used as well. For example ^ is less likely to be found in normal folder names.

Recommended value is to leave it empty and accept the default value.

namespace_subscriptions

Defaultyes
Valueboolean

Whether subscriptions are stored in this namespace.

This is usually no for shared namespaces so that the shared folders' subscriptions are stored in the user's primary subscriptions file. If no, the subscriptions are stored in the first parent namespace (based on the prefix) that has this setting enabled.

Example: If this setting is no for a namespace with prefix=foo/bar/, Dovecot first sees if there's a prefix=foo/ namespace with subscriptions=yes and then a namespace with an empty prefix. If neither is found, an error is given.

namespace_type

Defaultprivate
Valuestring
Allowed Valuesprivatesharedpublic

The namespace type. One of:

Type Description
public Contains public shared mailboxes.
private Typically contains only user's own private mailboxes.
shared Contains other users' user shared mailboxes.

notify_status

Default[None]
Valuestring
Dependencies
Pluginnotify-status plugin

The URI of the dictionary to use. This MUST be set for the plugin to be active.

See dictionary for how to configure dictionaries.

notify_status {
  dict proxy {
    name = notify_status
    socket_path = dict-async
  }
}

notify_status_value

Default{"messages":%{messages},"unseen":%{unseen}}
ValueString without variables
Pluginnotify-status plugin

A template of the string that will be written to the dictionary.

The template supports variable substitution of the form %{variable_name}.

Supported variable substitutions:

Field Value
first_recent_uid First recent UID
highest_modseq Highest modification sequence number
highest_pvt_modseq Highest private modification sequence number
mailbox Mailbox name
messages Number of messages
recent Number of recent messages (deprecated)
uidnext Predicted next UID value
uidvalidity Current UID validity
unseen Number of unseen messages
username Username (user@domain)

oauth2_active_attribute

Default[None]
Valuestring

Attribute name for (optional) checking whether account is disabled.

oauth2_active_value

Default[None]
Valuestring

Expected value in active_attribute. (empty = require present, but anything goes)

oauth2_fields

Default[None]
ValueString List

Key-value fields to include in successful authentication.

oauth2_force_introspection

Defaultno
Valueboolean

Force introspection even if tokeninfo contains wanted fields. Set this to yes if you are using oauth2_active_attribute.

oauth2_introspection_mode

Default[None]
Valuestring
Allowed Values<empty>authgetpostlocal
See Also

To enable oauth2 you must choose how to do token introspection. oauth2_introspection_url is not required if oauth2_tokeninfo_url already provides all the necessary fields, or if you are using local validation.

You can force introspection with oauth2_force_introspection, if you need to it every time.

With local validation, oauth2_tokeninfo_url is also ignored.

Value Description
auth GET request with Bearer authentication.
get GET request with token appended to URL.
post POST request with token=bearer_token as content.
local Attempt to locally validate and decode JWT token.

oauth2_introspection_url

Default[None]
Valuestring

URL for getting more information about token.

oauth2_issuers

Default[None]
ValueBoolean List

Valid issuer(s) for the token.

oauth2_local_validation

ValueNamed Filter
See Also

A dictionary for fetching validation keys.

Example:

oauth2_local_validation {
  dict fs {
    fs posix {
      prefix = /tmp/keys/
    }
  }
}

oauth2_openid_configuration_url

Default[None]
Valuestring

URL to RFC 7628 OpenID Provider Configuration Information schema.

oauth2_scope

Default[None]
ValueBoolean List

A list of valid scopes.

oauth2_send_auth_headers

Defaultno
Valueboolean

Whether to send special headers about authentication to remote server. If you enable this, the following headers will be sent:

X-Dovecot-Auth-Protocol
Requested protocol, such as imap or pop3.
X-Dovecot-Auth-Local
Local IP address where client connected to.
X-Dovecot-Auth-Remote
Remote IP address of the client connection.

oauth2_tokeninfo_url

Default[None]
Valuestring

URL for verifying token validity. Token is appended to the URL.

Example:

oauth2_tokeninfo_url = http://endpoint/oauth/tokeninfo?access_token=

oauth2_use_worker_with_mech

Defaultno
Valueboolean
See Also

Use worker process to verify token. This setting only applies to mechanism. If you want to use worker with passdb oauth2, use passdb_use_worker instead. Worker processes are mostly useful for distributing local token validation to multiple CPUs.

oauth2_username_attribute

Defaultemail
Valuestring

Username attribute in response.

oauth2_username_validation_format

Default%{user}
Valuestring
See Also

Normalization for oauth2 provided username, this setting is normally not needed. You only need this if the username that comes from authentication will not otherwise match with oauth2_username_attribute value.

obox_max_parallel_copies

Defaultmail_prefetch_count
Valueunsigned integer
Pluginobox plugin

Maximum number of email HTTP copy/link operations to do in parallel.

If the storage driver supports bulk-copy/link operation, this controls how many individual copy operations can be packed into a single bulk-copy/link HTTP request.

obox_max_parallel_deletes

Defaultmail_prefetch_count
Valueunsigned integer
Pluginobox plugin

Maximum number of email HTTP delete operations to do in parallel.

If the storage driver supports bulk-delete operation, this controls how many individual delete operations can be packed into a single bulk-delete HTTP request.

passdb_default_password_scheme

DefaultPLAIN
specific Passdb have different defaults
Valuestring

The scheme that passwords are in the passdb, unless overridden by the passdb entry (typically by prefixing with {SCHEME}).

passdb_deny

Defaultno
Valueboolean

If yes and the user is found from the denied user database the authentication will fail.

passdb_fields

Default[None]
ValueString List
See Also

Passdb fields (and passdb: Extra Fields). The values can contain %variables. All %variables used here reflect the state after the current passdb lookup, and can refer to fields returned by previous passdb lookups. Depending on the passdb driver, it can also refer to variable fields returned by it (e.g. %{ldap:fieldName}).

INFO

The LDAP driver provides additional specific variables, see LDAP authentication for more details.

For example:

passdb ldap {
  fields {
    user = %{ldap:userId}
    proxy = yes
    host = %{ldap:proxyHost}
  }
}

passdb_fields_import_all

Defaultyes
For passdb ldap the default is no.
Valueboolean
See Also

If yes, import all fields returned by the passdb lookup. If no, require passdb_fields to explicitly add wanted fields.

passdb_ldap_bind

Defaultno
Valueboolean

Set yes to use authentication binding for verifying password's validity.

This works by logging into LDAP server using the username and password given by client.

The passdb_ldap_filter is used to find the DN for the user. Note that the passdb_fields are still used, only the password field is ignored in it.

Before doing any search, the binding is switched back to the default DN.

If you use this setting, it's a good idea to use a different ldap_connection_group for userdb. That way one connection is used only for LDAP binds and another connection is used for user lookups. Otherwise the binding is changed to the default DN before each user lookup.

passdb_ldap_bind_userdn

Default[None]
Valuestring

If authentication binding is used, you can save one LDAP request per login if users' DN can be specified with a common template. The template can use the standard Settings variables.

Note that you can't use any passdb_fields declaration if you use this setting.

Example: passdb_ldap_bind_userdn = cn=%{user},ou=people,o=org

passdb_ldap_filter

Default[None]
Valuestring

Filter for passdb lookup.

Variables that can be used (see Settings variables for full list).

Example:

passdb ldap {
  filter = (&(objectClass=posixAccount)(uid=%{user}))
  #...
}

passdb_master

Defaultno
Valueboolean

If yes and the user is found from the Master Users the user is allowed to login as other users.

passdb_mechanisms_filter

Default[None]
ValueBoolean List
Changes
  • Added: 3.1.0

Skip the passdb if non-empty and the current auth mechanism is not listed here. If the value contains lookup, it matches for non-authenticating passdb lookups (e.g. lmtp/doveadm lookups).

Example:

passdb passwd-file {
  driver = passwd-file
  mechanisms_filter = PLAIN LOGIN
  # ...
}

passdb_name

Default[None]
Valuestring
See Also

Name of the passdb. The passdb filter name refers to this setting. If the passdb_driver setting is empty, the passdb_name is used as the driver. This allows doing e.g.:

passdb passwd-file {
  passwd_file_path = /etc/dovecot/passwd

passdb_pam_failure_show_msg

Defaultno
Valueboolean

Replace the default Authentication failed reply with PAM's failure.

passdb_pam_service_name

Defaultdovecot
Valuestring

The PAM service name to be used with the pam passdb.

passdb_pam_session

Defaultno
Valueboolean

Make Dovecot open a PAM session and close it immediately.

passdb_pam_setcred

Defaultno
Valueboolean

Make Dovecot create PAM credentials. The credentials are never deleted, which may cause problems with some PAM plugins.

passdb_result_failure

Defaultcontinue
Valuestring
Allowed Valuesreturn-okreturnreturn-failcontinuecontinue-okcontinue-fail
See Also

What to do after the passdb authentication failed. Possible values and their meaning are described fully at passdb: Result Values.

passdb_result_internalfail

Defaultcontinue
Valuestring
Allowed Valuesreturn-okreturnreturn-failcontinuecontinue-okcontinue-fail
See Also

What to do after the passdb authentication failed due to an internal error. Possible values and their meaning are described fully at passdb: Result Values. If any of the passdbs had an internal failure and the final passdb also returns continue the authentication will fail with internal error.

passdb_result_success

Defaultreturn-ok
Valuestring
Allowed Valuesreturn-okreturnreturn-failcontinuecontinue-okcontinue-fail
See Also

What to do after the passdb authentication succeeded. Possible values and their meaning are described fully at passdb: Result Values.

This is commonly used together with master passdb to specify that even after a successful master user authentication, the authentication should continue to the actual non-master passdb to lookup the user.

passdb_skip

Defaultnever
Valuestring
Allowed Valuesneverauthenticatedunauthenticated

Configures when passdbs should be skipped:

Value Description
never Never skip over this passdb.
authenticated Skip if an earlier passdb already authenticated the user successfully.
unauthenticated Skip if user hasn't yet been successfully authenticated by the previous passdbs.

passdb_sql_query

Default[None]
Valuestring

SQL query to lookup the passdb fields (password and other extra fields).

passdb_sql_update_query

Default[None]
Valuestring

SQL query to update the password. Currently used only by the OTP auth mechanism.

passdb_static_password

Default[None]
Valuestring
Changes
  • Added: 3.1.0

The static password to be used for all users authenticating using this passdb.

passdb_use_worker

Defaultno
specific Passdb have different defaults
Valueboolean

If yes, run the passdb lookup in auth-worker process instead of the main auth process. This setting is only used by some of the passdb drivers.

passdb_username_filter

Default[None]
Valuestring

Skip the passdb if non-empty and the username doesn't match the filter. This is mainly used to assign specific passdbs to specific domains. Space or comma-separated list of username filters that can have * or ? wildcards. If any of the filters matches, the filter succeeds. Define negative matches by preceding !. If any of the negative filter matches, the filter won't succeed.

Example:

  • Filter: *@example.com *@example2.com !user@example.com
  • Matches:
    • any@example.com
    • user@example2.com
  • Won't match:
    • user@example.com

passwd_file_path

Default[None]
Valuestring

Path to the passwd-file.

pgsql

Default[None]
ValueNamed List Filter
See Also

Creates a new PostgreSQL connection. If more than one is specified, the connections are automatically used for load balancing and for failover. The filter name refers to the pgsql_host setting.

pgsql_connection_limit

Default5
Valueunsigned integer

Maximum number of parallel connections.

pgsql_host

Default[None]
Valuestring
See Also

Host to connect to. The pgsql setting defaults to this.

pop3_client_workarounds

Default[None]
ValueBoolean List

Workarounds for various POP3 client bugs can be enabled here.

The following values are currently supported:

oe-ns-eoh
Because Outlook Express and Netscape Mail expect an end-of-headers line, this option sends one explicitly if none has been sent.
outlook-no-nuls
Because Outlook and Outlook Express hang if messages contain NUL characters, this setting replaces each of them with a 0x80 character.

pop3_delete_type

Defaultdefault
Valuestring
Allowed Valuesdefaultflagexpunge

Action to perform in POP3 when mails are deleted and pop3_deleted_flag is enabled.

pop3_deleted_flag

Default[None]
Valuestring
See Also

Change POP3 behavior so a user cannot permanently delete messages via POP3.

Instead, the messages are hidden from POP3 sessions by setting an IMAP flag, which Dovecot will filter out in future listings.

To enable this behavior, enter the name of the IMAP keyword to use.

INFO

This keyword will visible on IMAP clients for the message.

Example:

pop3_deleted_flag = $POP3Deleted

pop3_enable_last

Defaultno
Valueboolean

Enable support for the POP3 LAST command.

While this command has been removed from newer POP3 specs, some clients still attempt to use it. Enabling this causes the RSET command to clear all \Seen flags that messages may have.

pop3_fast_size_lookups

Defaultno
Valueboolean

If enabled, use the virtual message size of the message for POP3 replies if available.

POP3 requires message sizes to be listed as if they contain CR+LF line breaks; however, many POP3 servers instead return the sizes with pure line feeds (LFs), for the sake of speed.

If enabled, use the virtual message size if available, before falling back to the incorrect, physical size (used by many POP3 servers) if judging the correct size would have required opening the message to determine.

pop3_lock_session

Defaultno
Valueboolean

If enabled, only one POP3 session may exist for any single user.

pop3_logout_format

Defaulttop=%{top_count}/%{top_bytes}, retr=%{retr_count}/%{retr_bytes}, del=%{deleted_count}/%{deleted_bytes}, size=%{message_bytes}
ValueString without variables

The string to display to the client on POP3 logout (informational only).

Variables available (in addition to Mail user variables):

Variable Name Description
%{input} Bytes read from the client
%{output} Bytes sent to the client
%{top_count} Number of TOP commands run
%{top_bytes} Bytes sent to the client because of TOP commands
%{retr_count} Number of RETR commands run
%{retr_bytes} Bytes sent to the client because of RETR commands
%{deleted_count} Number of deleted messages
%{deleted_bytes} Number of bytes in deleted messages
%{message_count} Number of messages before deletion
%{message_bytes} Mailbox size, in bytes, before deletion
%{uidl_change} The old and the new UIDL hash (which can be useful for identifying unexpected changes in UIDLs)

pop3_migration_all_mailboxes

Defaultno
Valueboolean
Pluginpop3-migration plugin

By default it's assumed that POP3 contains the same messages as IMAP INBOX. If there are any unexpected mails, the migration fails. If the POP3 server includes other folders' contents in POP3 as well, this setting needs to be enabled. It causes Dovecot to try to match POP3 messages in all the migrated folders, not just INBOX. There is no warning logged if any POP3 UIDLs are missing or if POP3 has messages that aren't found from IMAP.

pop3_migration_ignore_extra_uidls

Defaultno
Valueboolean
Pluginpop3-migration plugin

If IMAP INBOX has all messages that exist in POP3, but POP3 still has some additional messages, the migration fails. Enable this setting to log it as a warning and continue anyway. This could happen if there's a race condition where a new mail is just delivered and it shows up in POP3 but not in IMAP.

pop3_migration_ignore_missing_uidls

Defaultno
Valueboolean
Pluginpop3-migration plugin

If POP3 has messages that aren't found from IMAP INBOX, and IMAP INBOX also has messages not found from POP3, the migration fails. Enable this setting to log it as a warning and continue anyway.

pop3_migration_mailbox

Defaultno
Valuestring
Pluginpop3-migration plugin

This setting points to the POP3 INBOX in the configured pop3c namespace. This setting is required for the plugin to be active.

pop3_migration_mailbox = POP3-MIGRATION-NS/INBOX

pop3_migration_skip_size_check

Defaultno
Valueboolean
Pluginpop3-migration plugin

IMAP and POP3 messages are attempted to be matched by the message sizes by default. This is the most efficient way of matching the messages, since both IMAP and POP3 listings can usually be looked up from indexes/caches. If the IMAP INBOX and POP3 listings don't match exactly, or if two adjacent messages have the same size, the rest of the messages are matched by reading their headers.

If this setting is enabled, the message size check is skipped entirely and only headers are matched. This may be necessary for reliability if it's known that the IMAP and POP3 messages cannot be matched by size anyway.

pop3_migration_skip_uidl_cache

Defaultno
Valueboolean
Pluginpop3-migration plugin

If imapc is configured with persistent indexes, the POP3 UIDLs are stored into the imapc mailbox's dovecot.index.cache files. Any following incremental migrations use these cached UIDLs if possible. This setting can be used to disable this in case there are any problems with the cache. This setting is unlikely to be ever needed.

pop3_no_flag_updates

Defaultno
Valueboolean

If enabled, do not attempt to mark mail messages as seen or non-recent when a POP3 session is involved.

pop3_reuse_xuidl

Defaultno
Valueboolean

If enabled, and the mail message has an X-UIDL header, use this as the mail's UIDL.

pop3_save_uidl

Defaultno
Valueboolean

Maildir only: If enabled, allow permanent saving of UIDLs sent to POP3 clients so that changes to pop3_uidl_format don't cause future changes to the corresponding UIDLs.

pop3_uidl_duplicates

Defaultallow
Valuestring
Allowed Valuesallowrename

How to handle any duplicate POP3 UIDLs that may exist.

Options:

allow
Show duplicates to clients.
rename
Append a temporary counter (such as -2 or -3) after the UIDL

pop3_uidl_format

Default%{uid | hex(8)}%{uidvalidity | hex(8)}
ValueString without variables

The POP3 unique mail identifier (UIDL) format to use.

The following variables can be used in combination with the standard variable filters (e.g., %{filename | upper} supplies the filename in uppercase) and with Global variables:

Variable Name Description
%{uidvalidity} Mailbox's IMAP UIDVALIDITY value
%{uid} IMAP UID associated with the message
%{md5} MD5 sum of the mailbox headers in hex (mbox only)
%{filename} Filename (Maildir only)
%{guid} Dovecot GUID for the message

pop3_uidl_migrate_format

Default[None]
Valuestring
Pluginpop3-uidl-migrate plugin

A template of the UIDL format to use when migrating messages.

The template supports variable substitution of the form %{variable_name}.

Variable substitutions available:

Field Value
owm OpenWave: If Message-ID header is valid POP3 UIDL, use it. Otherwise, use MD5 of the Message-ID header.
uid IMAP message UID
uidvalidity Current UID validity

pop3c_features

Default[None]
ValueBoolean List

List of features, optimizations, and workarounds that can be enabled.

Workarounds:

no-pipelining
Prevents use of the PIPELINING extension even when it is advertised.

pop3c_host

Default[None]
Valuestring

The remote POP3 host to connect to.

pop3c_master_user

Default[None]
Valuestring
See Also

The master username to authenticate as on the remote POP3 host.

To authenticate as a master user but use a separate login user, the following configuration should be employed, where the credentials are represented by masteruser and masteruser-secret:

pop3c_user = %{user}
pop3c_master_user = masteruser
pop3c_password = masteruser-secret

Mail user variables can be used.

pop3c_password

Default[None]
Valuestring
See Also

The authentication password for the remote POP3 server.

If using master users, this setting will be the password of the master user.

pop3c_port

Default110
ValuePort Number

The port on the remote POP3 host to connect to.

pop3c_quick_received_date

Defaultno
Valueboolean

If enabled, pop3c doesn't require calling TOP for each message in order to get the metadata.

pop3c_rawlog_dir

Default[None]
Valuestring
See Also

Log all POP3 traffic input/output to this directory.

pop3c_ssl

Defaultno
Valuestring
Allowed Valuesnopop3sstarttls

Use TLS to connect to the remote POP3 server.

Value Description
no No TLS
pop3s Explicitly connect to remote POP3 port using TLS
starttls Use POP3 STARTTLS command to switch to TLS connection

pop3c_ssl_verify

Defaultyes
Valueboolean
See Also

Verify remote POP3 TLS certificate?

Verification may be disabled during testing, but should be enabled during production use.

Only used if pop3c_ssl is enabled.

postmaster_address

Defaultpostmaster@%{user|domain|default(hostname)}
Valuestring

The From address from which email rejection messages (bounces) are sent.

As used here, %{user | domain} expands to the domain of the local user. Other Mail user variables can be used as well.

process_shutdown_filter

DefaultFor imap, pop3 and submission: event=mail_user_session_finished AND rss > 20MB
Valuestring

Filter to specify which events shutdown the process after finishing the current connections. This is mainly intended to save memory by preventing long-running imap processes that use a lot of memory (due to libc not freeing all of it to the OS). The syntax of the filter is described in Global Metric Filters.

For example:

process_shutdown_filter = "event=mail_user_session_finished AND rss > 20MB"

protocols

Default[None]
ValueBoolean List

The list of protocols to enable. By default all protocols are disabled.

For example:

# Only IMAP protocol enabled:
protocols = imap

# Enable also LMTP protocol (on top of IMAP):
protocols {
  lmtp = yes
}

quota

Default[None]
ValueNamed List Filter
See Also
Pluginquota plugin

Create a new quota root. The filter name refers to quota_name setting.

Globally configured quota roots are used only for private namespaces. To use quota for public namespaces, configure it inside the public namespace.

Example:

quota "User quota" {
  storage_size = 1G
}

quota_clone

ValueNamed Filter
See Also
Pluginquota-clone plugin
Changes
  • Added: 3.1.0

Named filter for initializing dictionary used to update with quota clone information.

redis_host = 127.0.0.1
redis_port = 6379
quota_clone {
  dict redis {
  }
}

quota_enforce

Defaultyes
quota_imapc { no }
Valueboolean
Pluginquota plugin

If disabled, the quota limit isn't actually enforced. The quota is still tracked and the current quota usage is visible to IMAP GETQUOTA commands.

quota_exceeded_message

DefaultQuota exceeded (mailbox for user is full)
Valuestring
Pluginquota plugin

The message specified here is passed on to a user who goes over quota. There are also other messages, which are currently hard coded:

quota_fs_message_limit

Defaultno
Valueboolean
Pluginquota plugin

If yes, use filesystem quota's inode limit as the message count limit. This can be useful with Maildir or sdbox. Used only with Quota Driver: Filesystem.

quota_fs_mount_path

Default[None]
Valuestring
Pluginquota plugin

If specified, enable FS quota for the specified mount path. Only mailboxes existing in this mount path have the quota enabled. Empty value looks up the mountpoint automatically. Used only with Quota Driver: Filesystem.

quota_fs_type

Defaultany
Valuestring
Allowed Valuesanyusergroup
Pluginquota plugin

Using any attempts to use the user quota first, with a fallback to group quota. Using user or group only attempts to use the user or the group quota, with a fallback to unlimited quota limit. Used only with Quota Driver: Filesystem.

quota_full_tempfail

Defaultno
Valueboolean
See Also

If enabled, return a temporary failure to the sending server if quota is exceeded. This allows the message to potentially be delivered later if the account moves under the quota limit at the time of redelivery.

If disabled, the message is bounced with a permanent error returned to the sending server.

quota_hidden

Defaultno
Valueboolean
Pluginquota plugin

If yes, hide the quota root from IMAP GETQUOTA commands.

quota_ignore

Defaultno
Valueboolean
Pluginquota plugin

If yes, don't include this mailbox or namespace in quota calculations.

Example:

namespace inbox {
  mailbox Trash {
    quota_ignore = yes
  }
}
namespace secondary {
  quota_ignore = yes
}

quota_ignore_unlimited

Defaultno
Valueboolean
Pluginquota plugin

If yes, ignore the quota root entirely if it has no quota limits. This means no tracking of the quota, and not making it visible to IMAP GETQUOTA commands.

quota_mailbox_count

Defaultunlimited
Valueunsigned integer
See Also
Pluginquota plugin
Changes
  • Added: 3.0.0

Maximum number of mailboxes that can be created. Each namespace is tracked separately, so e.g. shared mailboxes aren't counted towards the user's own limit.

quota_mailbox_message_count

Defaultunlimited
Valueunsigned integer
Pluginquota plugin
Changes
  • Added: 3.0.0

Maximum number of messages that can be created in a single mailbox.

quota_message_percentage

Default100
Valueunsigned integer
See Also
Pluginquota plugin

Multiplier for the quota_message_count setting (in this mailbox/namespace).

This may be useful to exceed the regular quota limit in some mailboxes, such as allowing clients that move messages with IMAP COPY+EXPUNGE to Trash folder to temporarily exceed the quota.

Example:

quota_message_count = 10000
namespace inbox {
  mailbox Trash {
    # 110% * 10000 = 11000 limit
    quota_message_percentage = 110
  }
}

quota_name

Default[None]
Valuestring
See Also
Pluginquota plugin

Name of the quota root. The quota filter name refers to this setting.

The quota root name is just an arbitrary string that is sent to IMAP clients, which in turn may show it to the user. The name has no meaning.

quota_over_status_current

Default[None]
Valuestring
See Also
Pluginquota plugin

An identifier that indicates whether the overquota-flag is active for a user.

This identifier is compared against quota_over_status_mask to determine if the overquota-flag should be set for the user.

Usually, this value will be loaded via userdb.

quota_over_status_lazy_check

Defaultno
Valueboolean
Pluginquota plugin

If enabled, overquota-flag is checked only when current quota usage is going to already be checked anyway. This prevents any additional storage I/O that would be caused by the overquota-flag check.

quota_storage_extra

Default0
Valuesize
See Also
Pluginquota plugin

If set, increase the quota_storage_size (for the mailbox/namespace) by this amount. This is an alternative to using quota_storage_percentage, although both can also be used.

This may be useful to exceed the regular quota limit in some mailboxes, such as allowing clients that move messages with IMAP COPY+EXPUNGE to Trash folder to temporarily exceed the quota.

Example:

quota_storage_size = 1G
namespace inbox {
  mailbox Trash {
    # 1G + 100M = 1100M
    quota_storage_extra = 100M
  }
}

quota_storage_grace

Default10 M
Valuesize
See Also
Pluginquota plugin

If set, allows message deliveries (LDA, LMTP) to exceed quota once by this amount. After the quota is already over the limit, the grace no longer applies. This prevents a situation where some smaller mails may still become delivered, but larger mail deliveries fail, and the user may not have received any warning about reaching the quota limit.

quota_storage_percentage

Default100
Valueunsigned integer
See Also
Pluginquota plugin

Multiplier for the quota_storage_size setting (in this mailbox/namespace). This is an alternative to using quota_storage_extra, although both can also be used.

This may be useful to exceed the regular quota limit in some mailboxes, such as allowing clients that move messages with IMAP COPY+EXPUNGE to Trash folder to temporarily exceed the quota.

Example:

quota_storage_size = 1G
namespace inbox {
  mailbox Trash {
    # 110% * 1G = 1100M
    quota_storage_percentage = 110
  }
}

quota_unified_dict_unset

Defaultno
Valueboolean
Pluginunified-quota plugin

When updating the unified quota dictionary, specifies whether the dict record is first "unset" before setting it again.

quota_warning_threshold

Defaultover
Valuestring
Allowed Valuesoverunder
See Also
Pluginquota plugin

Should the quota warning be executed when quota grows over the limit, or when it drops under the limit.

rawlog_dir

Default[None]
Valuestring
See Also

Directory where to create *.in and *.out rawlog files, one per TCP connection. The directory must already exist and be writable by the process. No error is logged if the directory doesn't exist.

Mail user variables can be used.

Example:

protocol imap {
  rawlog_dir = /tmp/rawlog/%{user}
  # if you want to put files into user's homedir, use this, do not use ~
  #rawlog_dir = %{home}/rawlog
}

recipient_delimiter

Default+
Valuestring

The separator between the :user and :detail address parts.

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

Default6379
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.

rejection_reason

DefaultYour message to <%{to}> was automatically rejected:%{literal('\r\n')}%{reason}
ValueString without variables

A human-readable message for the recipients of bounce messages.

The following variables are allowed, including Global variables:

Variable Name Description
%{reason} Reason for rejection
%{subject} Original subject line
%{to} Recipient address

The variable values are obtained from the mail being delivered or the delivery protocol.

sendmail_path

Default/usr/sbin/sendmail
Valuestring

The binary to use for sending email.

Used only if submission_host is not set.

service_chroot

Default[None]
Valuestring
See Also

The processes are chrooted to this directory at startup. Relative to base_dir.

service_client_limit

Defaultdefault_client_limit
Valueunsigned integer

Maximum number of simultaneous client connections per process. Once this number of connections is received, the next incoming connection will prompt Dovecot to spawn another process.

service_drop_priv_before_exec

Defaultno
Valueboolean

Drop all privileges after forking, but before executing the binary. This is mainly useful for dumping core files on non-Linux OSes, since the processes are no longer in "setuid" mode. This setting can't be used with non-empty chroot.

service_executable

Default[None]
Valuestring
See Also

The binary path to execute and its parameters. If the path doesn't begin with /, it's relative to base_dir.

service_extra_groups

Default[None]
Valuestring

Secondary UNIX groups that this process belongs to.

service_group

Default[None]
Valuestring

The primary UNIX group (GID) which runs this process.

service_idle_kill_interval

Defaultdefault_idle_kill_interval
Valuetime

Time interval between killing extra idling processes. During the interval the master process tracks the lowest number of idling processes for the service. Afterwards it sends SIGINT notification to that many idling processes. If the processes are still idling when receiving the signal, they shut down themselves.

Using infinite disables the idle-killing.

service_name

Default[None]
Valuestring
See Also

Name of the service. The service filter name refers to this setting.

service_process_min_avail

Default[None]
Valueunsigned integer
See Also

Minimum number of processes that always should be available to accept more client connections.

Note that if service_client_limit = 1, this means there are always that many processes that are not doing anything. When a new process launches, one of the idling processes will accept the connection and a new idling process is launched.

  • For service_restart_request_count = 1 processes this decreases the latency for handling new connections, because there's no need to wait for processes to fork. This is usually not necessary to to be set. Large service_process_min_avail values might be useful in some special cases, like if there are a lot of POP3 users logging in exactly at the same time to check mails.
  • For service_restart_request_count to a value !=1 and service_client_limit to a value >1 processes it could be set to the number of CPU cores (you can use %{system:cpu_count}) on the system to balance the load among them. This is commonly used with *-login processes.
  • For service_restart_request_count with a value of !=1 and service_client_limit = 1 processes it is likely not useful to use this, because generally there are already some idling processes waiting to accept new connections. However, it's not harmful either, since service_process_min_avail includes the existing idling processes when counting how many new idling processes are needed.

service_protocol

Default[None]
Valuestring
See Also

If non-empty, this service is enabled only when the protocol name is listed in protocols setting.

service_restart_request_count

Defaultunlimited
Valueunsigned integer

Number of client connections to handle until the process kills itself. Use unlimited to keep the process alive. 1 means only a single connection is handled until the process is stopped - this is the most secure choice since there's no way for one connection's state to leak to the next one. For better performance this can be set higher, but ideally not unlimited since more complex services can have small memory leaks and/or memory fragmentation and the process should get restarted eventually. For example 100 or 1000 can be good values.

service_type

Default[None]
Valuestring
See Also

Type of this service:

Value Description
<empty> The default.
login Used by login services. The login processes have "all processes full" notification fd. It's used by the processes to figure out when no more client connections can be accepted because client and process limits have been reached. The login processes can then kill some of their oldest connections that haven't logged in yet.
worker Used by various worker services. It's normal for worker processes to fill up to service_process_limit, and there shouldn't be a warning logged about it.
startup Creates one process at startup.
log
config
anvil		 Treated specially by these specific services.

service_vsz_limit

Defaultdefault_vsz_limit
Valuesize

Limit the process's address space (both RLIMIT_DATA and RLIMIT_AS if available). When the space is reached, some memory allocations may start failing with "Out of memory", or the kernel may kill the process with signal 9. This setting is mainly intended to prevent memory leaks from eating up all of the memory, but there can be also legitimate reasons why the process reaches this limit. For example a huge mailbox may not be accessed if this limit is too low. Use unlimited to disable this entirely.

shutdown_clients

Defaultyes
Valueboolean

If enabled, all processes are killed when the master process is shutdown.

Otherwise, existing processes will continue to run. This may be useful to not interrupt earlier sessions, but may not be desirable if restarting Dovecot to apply a security update, for example.

sieve_editheader_header_forbid_add

Default[None]
Valuestring
See Also
Pluginsieve plugin

A space-separated list of headers that cannot be added to the message header.

Addition of the Subject: header cannot be prohibited, as required by the RFC specification. Therefore, adding this header to this setting has no effect.

sieve_editheader_header_forbid_delete

Default[None]
Valuestring
See Also
Pluginsieve plugin

A space-separated list of headers that cannot be deleted from the message header.

Deleting the Received: and Auto-Submitted: fields is always forbidden, while removing the Subject: header cannot be prohibited, as required by the RFC specification. Therefore, adding one of these headers to this setting has no effect.

sieve_editheader_max_header_size

Default2k
Valuesize
See Also
Pluginsieve plugin

The maximum size in bytes of a header field value passed to the addheader command.

The minimum value for this setting is 1024 bytes.

sieve_execute_bin_dir

Default[None]
Valuestring
Pluginsieve-extprograms plugin

Points to a directory where the plugin looks for programs (shell scripts) to execute directly for the vnd.dovecot.execute extension.

sieve_execute_exec_timeout

Default10s
Valuetime
Pluginsieve-extprograms plugin

Configures the maximum execution time after which the program run by the vnd.dovecot.execute extension is forcibly terminated.

sieve_execute_input_eol

Defaultcrlf
Valuestring
Allowed Valuescrlflf
Pluginsieve-extprograms plugin

Determines the end-of-line character sequence used for the data piped to external programs run by the vnd.dovecot.execute extension. The default is currently "crlf", which represents a sequence of the carriage return (CR) and line feed (LF) characters. This matches the Internet Message Format (RFC 5322) and what Sieve itself uses as a line ending. Set this setting to "lf" to use a single LF character instead.

sieve_execute_socket_dir

Default[None]
Valuestring
Pluginsieve-extprograms plugin

Points to a directory relative to the base_dir where the plugin looks for script service sockets for the vnd.dovecot.execute extension.

sieve_extensions

Default<see description>
ValueBoolean List
Pluginsieve plugin

The Sieve language extensions available to users.

By default, all supported extensions are available, except for deprecated extensions, extensions that add the ability to change messages, extensions that require explicit configuration, or extensions that are still under development.

Some system administrators may want to disable certain Sieve extensions or enable those that are not available by default.

Supported extensions are listed at Sieve extensions.

Example:

# Enable the vacation-seconds extension in addition to all
# extensions enabled by default.
sieve_extensions {
  vacation-seconds = yes
}

sieve_filter_bin_dir

Default[None]
Valuestring
Pluginsieve-extprograms plugin

Points to a directory where the plugin looks for programs (shell scripts) to execute directly and filter messages through for the vnd.dovecot.filter extension.

sieve_filter_exec_timeout

Default10s
Valuetime
Pluginsieve-extprograms plugin

Configures the maximum execution time after which the program run by the vnd.dovecot.filter extension is forcibly terminated.

sieve_filter_input_eol

Defaultcrlf
Valuestring
Allowed Valuescrlflf
Pluginsieve-extprograms plugin

Determines the end-of-line character sequence used for the data piped to external programs run by the vnd.dovecot.filter extension. The default is currently "crlf", which represents a sequence of the carriage return (CR) and line feed (LF) characters. This matches the Internet Message Format (RFC 5322) and what Sieve itself uses as a line ending. Set this setting to "lf" to use a single LF character instead.

sieve_filter_socket_dir

Default[None]
Valuestring
Pluginsieve-extprograms plugin

Points to a directory relative to the base_dir where the plugin looks for script service sockets for the vnd.dovecot.filter extension.

sieve_global_extensions

Defaultsieve_extensions
ValueBoolean List
Pluginsieve plugin

Which Sieve language extensions are only available in global scripts.

This can be used to restrict the use of certain Sieve extensions to administrator control, for instance when these extensions can cause security concerns.

This setting has higher precedence than sieve_extensions, meaning that the extensions enabled with this setting are never available to the user's personal script no matter what is specified for the sieve_extensions setting.

The syntax of this setting is identical to sieve_extensions, with the difference that extensions are enabled or disabled for exclusive use in global scripts.

Currently, no extensions are marked as such by default.

sieve_implicit_extensions

Default[None]
Valuestring
Pluginsieve plugin

WARNING

Do not use this setting unless you really need to!

The Sieve language extensions implicitly available to users.

The extensions listed in this setting do not need to be enabled explicitly using the Sieve "require" command.

This behavior directly violates the Sieve standard, but can be necessary for compatibility with some existing implementations of Sieve (notably jSieve).

The syntax and semantics of this setting are otherwise identical to sieve_extensions.

sieve_max_actions

Default32
Valueunsigned integer
Pluginsieve plugin

The maximum number of actions that can be performed during a single script execution.

If set to 0, no limit on the total number of actions is enforced.

sieve_max_cpu_time

Default30s
Valuetime
Pluginsieve plugin

The maximum amount of CPU time that a Sieve script is allowed to use while executing. If the execution exceeds this resource limit, the script ends with an error, causing the implicit "keep" action to be executed.

This limit is not only enforced for a single script execution, but also cumulatively for the last executions within a configurable timeout (see sieve_resource_usage_timeout).

sieve_max_redirects

Default4
Valueunsigned integer
Pluginsieve plugin

The maximum number of redirect actions that can be performed during a single script execution.

0 means redirect is prohibited.

sieve_pipe_bin_dir

Default[None]
Valuestring
Pluginsieve-extprograms plugin

Points to a directory where the plugin looks for programs (shell scripts) to execute directly and pipe messages to for the vnd.dovecot.pipe extension.

sieve_pipe_exec_timeout

Default10s
Valuetime
Pluginsieve-extprograms plugin

Configures the maximum execution time after which the program run by the vnd.dovecot.pipe extension is forcibly terminated.

sieve_pipe_input_eol

Defaultcrlf
Valuestring
Allowed Valuescrlflf
Pluginsieve-extprograms plugin

Determines the end-of-line character sequence used for the data piped to external programs run by the vnd.dovecot.pipe extension. The default is currently "crlf", which represents a sequence of the carriage return (CR) and line feed (LF) characters. This matches the Internet Message Format (RFC 5322) and what Sieve itself uses as a line ending. Set this setting to "lf" to use a single LF character instead.

sieve_pipe_socket_dir

Default[None]
Valuestring
Pluginsieve-extprograms plugin

Points to a directory relative to the base_dir where the plugin looks for script service sockets for the vnd.dovecot.pipe extension.

sieve_plugins

Default[None]
ValueBoolean List
Pluginsieve plugin

The Pigeonhole Sieve interpreter can have plugins of its own.

Using this setting, the used plugins can be specified.

Check Sieve plugins for available plugins.

sieve_quota_script_count

Default[None]
Valueunsigned integer
Pluginsieve plugin

The maximum number of personal Sieve scripts a single user can have.

Default is 0, which is unlimited.

sieve_quota_storage_size

Default[None]
Valueunsigned integer
Pluginsieve plugin

The maximum amount of disk storage a single user's scripts may occupy.

Default is 0, which is unlimited.

sieve_redirect_envelope_from

Defaultsender
Valuestring
Pluginsieve plugin

Specifies what envelope sender address is used for redirected messages.

Normally, the Sieve redirect command copies the sender address for the redirected message from the processed message So, the redirected message appears to originate from the original sender.

The following options are supported for this setting:

Option Description
sender The sender address is used
recipient The final recipient address is used
orig_recipient The original recipient is used
user_email The user's primary address is used. This is configured with the sieve_user_email setting. If that setting is not configured, user_email is equal to sender.
postmaster The postmaster_address configured for LDA/LMTP.
<user@domain> Redirected messages are always sent from user@domain. The angle brackets are mandatory. The null <> address is also supported.

When the envelope sender of the processed message is the null address <>, the envelope sender of the redirected message is also always <>, irrespective of what is configured for this setting.

sieve_resource_usage_timeout

Default1h
Valuetime
Pluginsieve plugin

To prevent abuse, the Sieve interpreter can record resource usage of a Sieve script execution in the compiled binary if it is significant. Currently, this happens when CPU system + user time exceeds 1.5 seconds for one execution. Such high resource usage is summed over time in the binary and once that cumulative resource usage exceeds the limits (sieve_max_cpu_time), the Sieve script is disabled in the binary for future execution, even if an individual execution exceeded no limits.

If the last time high resource usage was recorded is older than sieve_resource_usage_timeout, the resource usage in the binary is reset. This means that the Sieve script is only disabled when the limits are cumulatively exceeded within this timeout. With the default configuration this means that the Sieve script is only disabled when the total CPU time of Sieve executions that lasted more than 1.5 seconds exceeds 30 seconds in the last hour.

A disabled Sieve script can be reactivated by the user by uploading a new version of the Sieve script after the excessive resource usage times out. An administrator can force reactivation by forcing a script compile (e.g. using the sievec command line tool).

sieve_script_active_path

Default~/.dovecot.sieve
Valuestring
See Also
Pluginsieve plugin

When ManageSieve server is used, one script in the storage can be active; i.e., evaluated at delivery.

This setting only applies when sieve_script_driver = file. For that storage driver, the active script in the storage directory is pointed to by a symbolic link.

This setting configures where this symbolic link is located. If the sieve_script_path setting points to a regular file, this setting has no effect (and ManageSieve cannot be used).

sieve_script_bin_path

Defaultpersonal
Valuestring
See Also
Pluginsieve plugin

Points to the directory where the compiled binaries for this script location are stored. This directory is created automatically if possible.

If this setting is not configured, the behavior depends on the storage driver. For the file storage driver, the binaries are for example stored in the same directory as the corresponding sieve scripts.

Don't specify the same directory for multiple script storages (e.g. with different types), as this will result in undefined behavior. For one, the same script name could point to different scripts for different storages, leading to a conflict, because the storages will try to use the same binary file. Multiple mail users can share a single script directory if the associated script storage configuration is identical between users and all users share the same system credentials (uid, gid). All users will then use the same scripts for that storage type.

sieve_script_cause

Defaultdelivery
ValueBoolean List
See Also
Pluginsieve plugin

The causes for executing Sieve scripts from this storage. This is currently only relevant for the IMAPSieve plugin. For standard Sieve execution at message delivery the cause is "delivery". Other causes can be append, copy and flag.

sieve_script_ldap_filter

Default[None]
Valuestring
See Also
Pluginsieve plugin

The LDAP search filter that is used to find the entry containing the Sieve script.

These variables can be used:

Variable Description
%{user} username
%{user | username} user part in user@domain, same as %{user} if there's no domain
%{user | domain} domain part in user@domain, empty if user there's no domain
%{home} user's home directory
%{name} name of the Sieve script

sieve_script_name

Defaultpersonal
Valuestring
See Also
Pluginsieve plugin

The (default) name of a Sieve script retrieved from this storage. If the name of the Sieve script cannot be derived somehow from the storage (e.g. from a file name) and the storage for a single script is specified, this option is required (e.g. for dict locations that must point to a particular script).

If the name of the script is derived from the storage, the value of the sieve_script_name setting overrides that name. If the Sieve interpreter explicitly queries for a specific name (e.g. to let the Sieve Sieve include extension retrieve a script from the global script storage), this setting has no effect.

For the Sieve script storage with type default, the name is required to make the default script visible in ManageSieve. See 'Sieve visible default script'

sieve_script_precedence

Defaultinfinite
Valueunsigned integer
See Also
Pluginsieve plugin

The precedence of this Sieve storage in the configuration. Normally, script storages with matching type and cause are accessed in the order these are specified in the configuration. This setting can be used to configure an explicit order. Storages will be accessed with lower precedence first.

sieve_script_storage

Default[None]
Valuestring
See Also
Pluginsieve plugin

The identifier of the Sieve script storage. This is used only in configurations and by command line tools - it's not visible to the user. The sieve_script filter refers to this setting.

sieve_spamtest_score_max_header

Default[None]
Valuestring
See Also
Pluginsieve plugin

Value format: <header-field> [ ":" <regexp> ]

Some spam scanners include the maximum score value in one of their status headers. Using this setting, this maximum can be extracted from the message itself instead of specifying the maximum manually using the setting sieve_spamtest_score_max_value.

The syntax is identical to the sieve_spamtest_status_header setting. This setting cannot be used together with sieve_spamtest_score_max_value.

sieve_spamtest_status_header

Default[None]
Valuestring
See Also
Pluginsieve plugin

Value format: <header-field> [ ":" <regexp> ]

This specifies the header field that contains the result information of the spam scanner and it may express the syntax of the content of the header.

If no matching header is found in the message, the spamtest command will match against 0.

This is a structured setting. The first part specifies the header field name. Optionally, a POSIX regular expression follows the header field name, separated by a colon. Any white space directly following the colon is not part of the regular expression. If the regular expression is omitted, any header content is accepted and the full header value is used. When a regular expression is used, it must specify one match value (inside brackets) that yields the desired spam scanner result.

If the header does not match the regular expression or if no value match is found, the spamtest test will match against 0 during Sieve script execution.

sieve_spamtest_status_type

Default[None]
Valuestring
Allowed Valuesscorestrlentext
See Also
Pluginsieve plugin

This specifies the type of status result that the spam/virus scanner produces.

This can either be a numeric score (score), a string of identical characters (strlen), e.g. '*******', or a textual description (text), e.g. 'Spam' or 'Not Spam' (see sieve_spamtest_text_value).

sieve_spamtest_text_value

Default[None]
ValueString List
See Also
Pluginsieve plugin

When the sieve_spamtest_status_type setting is set to text, this setting specifies what values the spamtest test will match against to obtain the score value. For each recognized numeric score value this string list setting yields the text to match against. Score values between 0 and 10 are recognized.

Example:

sieve_spamtest_status_header = X-Spam-Verdict
sieve_spamtest_status_type = text
sieve_spamtest_text_value {
  1 = Not Spam
  10 = Spam
}

sieve_trace_dir

Default[None]
Valuestring
See Also
Pluginsieve plugin

The directory where trace files are written.

Trace debugging is disabled if this setting is not configured or if the directory does not exist.

If the path is relative or it starts with ~/ it is interpreted relative to the current user's home directory.

sieve_trace_level

Default[None]
Valuestring
See Also
Pluginsieve plugin

The verbosity level of the trace messages. Trace debugging is disabled if this setting is not configured. Options are:

Option Description
actions Only print executed action commands, like keep, fileinto, reject, and redirect.
commands Print any executed command, excluding test commands.
tests Print all executed commands and performed tests.
matching Print all executed commands, performed tests and the values matched in those tests.

sieve_user_email

Default[None]
Valuestring
Pluginsieve plugin

The primary e-mail address for the user.

This is used as a default when no other appropriate address is available for sending messages.

If this setting is not configured, either the postmaster or null <> address is used as a sender, depending on the action involved.

This setting is important when there is no message envelope to extract addresses from, such as when the script is executed in IMAP.

sieve_user_log_path

Default[None]
Valuestring
Pluginsieve plugin

The path to the file where the user log file is written.

A default location is used if this setting is not explicitly configured:

  • If the main user's personal Sieve script storage (as configured with sieve_script uses the File storage driver, the logfile is set to <filename>.log by default.

  • If the script is not stored as a file, the default user log file is ~/.dovecot.sieve.log.

sieve_vacation_check_recipient

Defaultyes
Valueboolean
See Also
Pluginsieve plugin

This setting determines whether the checks for implicit delivery are performed. If this is skipped, this means that the vacation command does not verify that the message is explicitly addressed at the recipient.

Use this option with caution. Specifying no will violate the Sieve standards and can cause vacation replies to be sent for messages not directly addressed at the recipient.

sieve_vacation_max_period

Default60d
Valuetime
See Also
Pluginsieve plugin

Specifies the maximum period that can be specified for the :days tag of the vacation command.

The configured value must be larger than sieve_vacation_min_period.

A value of 0 has a special meaning: it indicates that there is no upper limit.

sieve_vacation_min_period

Default1d
Valuetime
See Also
Pluginsieve plugin

Specifies the minimum period that can be specified for the :days and :seconds tags of the vacation command.

A minimum of 0 indicates that users are allowed to make the Sieve interpreter send a vacation response message for every incoming message that meets the other reply criteria (refer to RFC 5230). A value of zero is not recommended.

sieve_vacation_send_from_recipient

Defaultno
Valueboolean
See Also
Pluginsieve plugin

This setting determines whether vacation messages are sent with the SMTP MAIL FROM envelope address set to the recipient address of the Sieve script owner.

Normally this is set to <>, which is the default as recommended in the specification. This is meant to prevent mail loops. However, there are situations for which a valid sender address is required and this setting can be used to accommodate for those.

sieve_vacation_use_original_recipient

Defaultno
Valueboolean
See Also
Pluginsieve plugin

This specifies whether the original envelope recipient should be used in the check for implicit delivery.

The vacation command checks headers of the incoming message, such as To: and Cc: for the address of the recipient, to verify that the message is explicitly addressed at the recipient. If the recipient address is not found, the vacation action will not trigger a response to prevent sending a reply when it is not appropriate.

Normally only the final recipient address is used in this check. This setting allows including the original recipient specified in the SMTP session if available.

This is useful to handle mail accounts with aliases. Use this option with caution: if you are using aliases that point to more than a single account, as senders can get multiple vacation responses for a single message.

Use the LDA -a option or the LMTP/LDA lda_original_recipient_header setting to make the original SMTP recipient available to Sieve.

sieve_virustest_score_max_header

Default[None]
Valuestring
See Also
Pluginsieve plugin

Value Format: <header-field> [ ":" <regexp> ]

Some spam scanners include the maximum score value in one of their status headers. Using this setting, this maximum can be extracted from the message itself instead of specifying the maximum manually using the setting sieve_virustest_score_max_value.

The syntax is identical to sieve_virustest_status_header. This setting cannot be used together with sieve_virustest_score_max_value.

sieve_virustest_status_header

Default[None]
Valuestring
See Also
Pluginsieve plugin

Value Format: <header-field> [ ":" <regexp> ]

This specifies the header field that contains the result information of the spam scanner and it may express the syntax of the content of the header.

If no matching header is found in the message, the spamtest command will match against 0.

This is a structured setting. The first part specifies the header field name. Optionally, a POSIX regular expression follows the header field name, separated by a colon. Any white space directly following the colon is not part of the regular expression. If the regular expression is omitted, any header content is accepted and the full header value is used. When a regular expression is used, it must specify one match value (inside brackets) that yields the desired spam scanner result.

If the header does not match the regular expression or if no value match is found, the spamtest test will match against 0 during Sieve script execution.

sieve_virustest_status_type

Default[None]
Valuestring
Allowed Valuesscorestrlentext
See Also
Pluginsieve plugin

This specifies the type of status result that the spam/virus scanner produces.

This can either be a numeric score (score), a string of identical characters (strlen), e.g. '*******', or a textual description (text), e.g. 'Spam' or 'Not Spam' (see sieve_virustest_text_value).

sieve_virustest_text_value

Default[None]
ValueString List
See Also
Pluginsieve plugin

When the sieve_virustest_status_type setting is set to text, this setting specifies what values the spamtest test will match against to obtain the score value. For each recognized numeric score value this string list setting yields the text to match against. Score values between 0 and 10 are recognized.

Example:

sieve_virustest_status_header = X-VirusCheck
sieve_virustest_status_type = text
sieve_virustest_text_value {
  1 = Clean
  2 = Presumed Clean
  3 = Not sure
  4 = Almost Certain
  5 = Definitely
}

sieve_zimbra_addressbook_dict

Default[None]
Valuestring
Pluginsieve-zimbra-compat plugin

Configuration for the dict lookup. This should normally point to the dict proxy, so that asynchronous batch lookups are possible.

sieve_zimbra_bare_extensions

Default[None]
Valuestring
Pluginsieve-zimbra-compat plugin

A space-separated list of all the Zimbra extensions that are made available without the prefix.

Note that this hides any standard extension with the same name as one of Zimbra extensions; e.g., the "date" extension will become the Zimbra version once the "date" extension is listed in this setting.

sieve_zimbra_notify_envelope_from

Defaultsieve_notify_mailto_envelope_from or postmaster
Valuestring
Pluginsieve-zimbra-compat plugin

Specifies what envelope sender address is used for notification emails. The following values are supported for this setting:

Value Description
sender The sender address is used.
recipient The final recipient address is used.
orig_recipient The original recipient is used.
user_email The user's primary address is used. This is configured with sieve_user_email. If that setting is not configured, user_mail is equal to recipient.
postmaster The postmaster_address configured for the LDA.
<user@domain> Notifications are always sent from user@domain. The angle brackets are mandatory. The null ("<>") address is also supported.

The "From" header is based on this setting as well. When the envelope sender of the processed message is the null address "<>", the envelope sender of the notification is also always "<>", irrespective of what is configured for this setting.

sql_driver

Default[None]
Valuestring

SQL driver to use for any SQL database accesses.

sqlite_journal_mode

Defaultwal
Valuestring
Allowed Valuesdeletewal

Allows using write-ahead logging mode for database.

sqlite_path

Default[None]
Valuestring

Path to the sqlite database.

sqlite_readonly

Defaultno
Valueboolean

Specifies that this database is read-only and should not be attempted to be created or written to.

ssl

Defaultyes
Valuestring
Allowed Valuesyesnorequired
See Also

The level of SSL support. This setting affects both the implicit SSL ports and the STARTTLS commands.

Options:

no
SSL/TLS is completely disabled.
yes
SSL/TLS is enabled, but not necessarily required for clients.
required
SSL/TLS is required for all imap, pop3, managesieve and submission protocol client connections. This differs from auth_allow_cleartext in that even non-cleartext authentication mechanisms aren't allowed without SSL/TLS.

This setting affects the secured state of connections. See secured connections.

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_crypto_device

Default[None]
Valuestring
See Also

Available Values: <Obtain by running openssl engine command>

Which SSL crypto device to use.

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.

ssl_options

Default[None]
Valuestring
Allowed Valuescompressionno_ticket
See Also

Additional options for SSL.

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

Currently supported options are:

compression
Enable compression.
no_ticket
Disable SSL session tickets.

ssl_server_alt_cert_file

Default[None]
ValueFile
See Also

Alternative SSL certificate that will be used if the algorithm differs from the primary certificate.

This is useful when migrating to e.g. an ECDSA certificate.

Example:

ssl_server_alt_cert_file = /path/to/alternative/cert.pem

ssl_server_ca_file

Default[None]
ValueFile
See Also

List of SSL CA certificates that are used to validate whether SSL certificates presented by incoming imap/pop3/etc. client connections are valid.

Example:

ssl_server_ca_file = /etc/dovecot/ca.crt
ssl_server_request_client_cert = yes
auth_ssl_require_client_cert = yes

ssl_server_cert_file

Default[None]
ValueFile
See Also

Path to the PEM-encoded X.509 SSL/TLS certificate presented for incoming imap/pop3/etc. client connections.

The ssl_server_key_file is also needed for the private certificate.

Example:

ssl_server_cert_file = /etc/ssl/private/dovecot.crt
ssl_server_key_file = /etc/ssl/private/dovecot.key

ssl_server_dh_file

Default[None]
ValueFile
See Also

Path to the Diffie-Hellman parameters file. This setting isn't needed if using only ECDSA certificates.

You can generate a new parameters file by, for example, running openssl dhparam -out dh.pem 4096 on a machine with sufficient entropy (this may take some time).

Example:

ssl_server_dh_file = /path/to/dh.pem

ssl_server_key_password

Default[None]
Valuestring
See Also

The password to use if ssl_server_key_file is password-protected.

Since this file is often world-readable, you may wish to specify the path to a file containing the password, rather than the password itself, by using the format ssl_server_key_password = <path here. The path should be to a root-owned file with mode 0600.

Alternatively, you can supply the password via the -p parameter at startup.

ssl_server_prefer_ciphers

Defaultclient
Valuestring
Allowed Valuesclientserver
See Also

Whether to give preference to the server's cipher list over a client's list.

stats_server

ValueNamed Filter

Filter for stats server specific settings.

stats_writer_socket_path

Defaultstats-writer
Valuestring

The path to the stats-writer socket.

submission_add_received_header

Defaultyes
Valueboolean
Changes
  • Added: 3.0.0

Controls if "Received:" header should be added to mails by the submission backend.

submission_client_workarounds

Default[None]
ValueBoolean List

Configures the list of active workarounds for Submission client bugs.

Supported workaround identifiers are:

implicit-auth-external
Implicitly login using the EXTERNAL SASL mechanism upon the first MAIL command, provided that the client provides a valid TLS client certificate. This is helpful for clients that omit explicit SASL authentication when configured for authentication using a TLS certificate (Thunderbird for example).
mailbox-for-path
Allow using bare Mailbox syntax (i.e., without <...>) instead of full path syntax.
whitespace-before-path
Allow one or more spaces or tabs between 'MAIL FROM:' and path and between 'RCPT TO:' and path.

submission_host

Default[None]
ValueURL

Use this SMTP submission host to send messages.

Overrides sendmail_path value, if set.

submission_logout_format

Defaultin=%{input} out=%{output}
ValueString without variables

The SMTP Submission logout format string.

Variables supported, including Mail user variables:

Variable Name Description
%{input} Bytes read from client
%{output} Bytes sent to client
%{command_count} Number of commands received from client
%{reply_count} Number of replies sent to client
%{transaction_id} ID of the current transaction, if any

submission_max_mail_size

Default40M
Valuesize

The maximum message size accepted for relay.

This value is announced in the SMTP SIZE capability.

If empty, this value is either determined from the relay server or left unlimited if no limit is known; the relay MTA will reply with error if some unknown limit exists there, which will be passed back to the client.

submission_max_recipients

Default[None]
Valueunsigned integer

Maximum number of recipients accepted per connection.

0 means unlimited.

submission_relay_command_timeout

Default5mins
Valuetime (milliseconds)

Timeout for SMTP commands issued to the submission service's relay server.

The timeout is reset every time more data is being sent or received.

submission_relay_connect_timeout

Default30secs
Valuetime (milliseconds)

Timeout for connecting to and logging into the submission service's relay server.

submission_relay_host

Default[None]
Valuestring

Host of the relay server (REQUIRED to provide the submission service).

submission_relay_master_user

Default[None]
Valuestring

Master user name for authentication to the relay MTA if authentication is required.

submission_relay_max_idle_time

Default29mins
Valuetime

Submission relay max idle time for connection to relay MTA.

submission_relay_password

Default[None]
Valuestring

Password for authentication to the relay MTA if authentication is required.

submission_relay_port

Default25
ValuePort Number

Port for the submission relay server.

submission_relay_rawlog_dir

Default[None]
Valuestring
See Also

Write protocol logs for relay connection to this directory for debugging.

Mail user variables can be used.

submission_relay_ssl

Defaultno
Valuestring
Allowed Valuesnosmtpsstarttls

If enabled, SSL/TLS is used for the connection to the relay server.

Available values:

no
No SSL connection is used.
smtps
An SMTPS connection (immediate SSL) is used.
starttls
The STARTTLS command is used to establish the TLS layer.

submission_relay_ssl_verify

Defaultyes
Valueboolean

If enabled, TLS certificate of the relay server must be verified.

submission_relay_trusted

Defaultno
Valueboolean

If enabled, the relay server is trusted.

Determines whether we try to send (Postfix-specific) XCLIENT data to the relay server (only if enabled).

submission_relay_user

Default[None]
Valuestring

User name for authentication to the relay MTA if authentication is required.

submission_ssl

Defaultno
Valuestring
Allowed Valuesnosmtpsstarttls
See Also

If enabled, use SSL/TLS to connect to submission_host.

Available values:

no
No SSL connection is used.
smtps
An SMTPS connection (immediate SSL) is used.
starttls
The STARTTLS command is used to establish the TLS layer.

submission_timeout

Default30secs
Valuetime
See Also

Timeout for submitting outgoing messages.

syslog_facility

Defaultmail
Valuestring

The syslog facility used if you're logging to syslog.

textcat_config_path

Default<textcat dir>
Valuestring
See Also
Pluginfts plugin

Path to the textcat/exttextcat configuration file, which lists the supported languages.

This is recommended to be changed to point to a minimal version of a configuration that supports only the languages listed in language.

Doing this improves language detection performance during indexing and also makes the detection more accurate.

Example:

textcat_config_path = /usr/share/libexttextcat/fpdb.conf

trash_priority

Default[None]
Valueunsigned integer
Plugintrash plugin

If non-zero, enables the trash plugin for the mailbox with the specified priority. Mailboxes with smaller priority number are emptied before mailboxes with a larger priority number. If there are multiple mailboxes with the same priority, expunge the oldest mail from them first.

Example where Trash is emptied before Spam:

namespace inbox {
  mailbox Trash {
    trash_priority = 1
  }
  mailbox Spam {
    trash_priority = 2
  }
}

unix_listener_group

Default[None]
Valuestring

Group of the listener file. Empty (default) means GID 0 (root/wheel).

unix_listener_mode

Default0600
Valueoctal unsigned integer

Mode of the file. Note that 0600 is an octal value, while 600 is a different decimal value. Setting mode to 0 disables the listener.

unix_listener_type

Default[None]
Valuestring
Changes
  • Added: 3.1.0

Listener type. This string value has service-specific meaning and is used to distinguish different listener types that one service may employ.

unix_listener_user

Default[None]
Valuestring

Owner of the listener file. Empty (default) means UID 0 (root).

userdb_fields

Default[None]
ValueString List
See Also

Userdb fields (and userdb: Extra Fields). The values can contain %variables. All %variables used here reflect the state after the current userdb lookup, and can refer to fields returned by previous userdb lookups. Depending on the userdb driver, it can also refer to variable fields returned by it (e.g. %{ldap:fieldName}).

INFO

The LDAP driver provides additional specific variables, see LDAP authentication for more details.

For example:

userdb ldap {
  fields {
    user = %{ldap:userId}
    home = /home/%{ldap:mailboxPath}
    uid = vmail
    gid = vmail
  }
}

userdb_fields_import_all

Defaultyes
For userdb ldap the default is no.
Valueboolean
See Also

If yes, import all fields returned by the userdb lookup. If no, require userdb_fields to explicitly add wanted fields.

userdb_ldap_filter

Default[None]
Valuestring

Filter for userdb lookup.

Variables that can be used (see Settings variables for full list).

Example:

userdb ldap {
  filter = (&(objectClass=posixAccount)(uid=%{user}))
  #...
}

userdb_ldap_iterate_fields

Default[None]
ValueString List

Attributes to get a list of all users. Currently only the attribute user is supported.

Example:

userdb ldap {
  iterate_filter = (objectClass=smiMessageRecipient)
  iterate_attrs {
    user = %{ldap:mailRoutingAddress}
  }
}

userdb_ldap_iterate_filter

Default[None]
Valuestring

Filter to get a list of all users.

userdb ldap {
  iterate_filter = (objectClass=smiMessageRecipient)
  iterate_attrs {
    user = %{ldap:mailRoutingAddress}
  }
}

userdb_name

Default[None]
Valuestring
See Also

Name of the userdb. The userdb filter name refers to this setting. If the userdb_driver setting is empty, the userdb_name is used as the driver. This allows doing e.g.:

userdb passwd-file {
  passwd_file_path = /etc/dovecot/passwd

userdb_result_failure

Defaultcontinue
Valuestring
Allowed Valuesreturn-okreturnreturn-failcontinuecontinue-okcontinue-fail
See Also

What to do if the user was not found from the userdb. Possible values and their meaning are described fully at userdb: Result Values.

userdb_result_internalfail

Defaultcontinue
Valuestring
Allowed Valuesreturn-okreturnreturn-failcontinuecontinue-okcontinue-fail
See Also

What to do after the userdb failed due to an internal error. Possible values and their meaning are described fully at userdb: Result Values. If any of the userdbs had an internal failure and the final userdb also returns continue the authentication will fail with internal error.

userdb_result_success

Defaultreturn-ok
Valuestring
Allowed Valuesreturn-okreturnreturn-failcontinuecontinue-okcontinue-fail
See Also

What to do if the user was successfully found from the userdb. Possible values and their meaning are described fully at userdb: Result Values.

userdb_skip

Defaultnever
Valuestring
Allowed Valuesneverfoundnotfound

Configures when userdbs should be skipped:

Value Description
never Never skip over this userdb.
found Skip if an earlier userdbs already found the user.
notfound Skip if previous userdbs haven't yet found the user.

userdb_sql_iterate_query

Default[None]
Valuestring

SQL query to list all available usernames.

userdb_sql_query

Default[None]
Valuestring

SQL query to lookup the userdb fields.

userdb_static_allow_all_users

Defaultno
Valueboolean
Changes
  • Added: 3.1.0

Skip user existence verification via passdb lookup.

userdb_use_worker

Defaultno
specific userdb have different defaults
Valueboolean

If yes, run the userdb lookup in auth-worker process instead of the main auth process. This setting is only used by some of the userdb drivers.

valid_chroot_dirs

Default[None]
ValueBoolean List

List of directories under which chrooting is allowed for mail processes.

Addresses the risk of root exploits enabled by incorrect use of chrooting.

Interpretation is recursive, so including /var/mail allows chrooting to subdirectories such as /var/mail/foo/bar.

vault_mailbox

Default[None]
Valuestring
Pluginvault plugin

This setting enables the vault plugin and identifies where to store a copy of the message.

verbose_proctitle

Defaultyes
Valueboolean

If enabled, the ps command shows more verbose process details, including the username and IP address of the connected client.

This aids in seeing who is actually using the server, as well as helps debugging in case there are any problems. See process titles.

version_ignore

Defaultno
Valueboolean

If enabled, ignore version mismatches between different Dovecot versions.

welcome_wait

Defaultno
Valueboolean
Pluginwelcome plugin

If enabled, wait for the script to finish. By default, the welcome script is run asynchronously.

Advanced Settings ​

DANGER

These settings should not normally be changed.

auth_gssapi_hostname

Default<name returned by gethostname()>
Valuestring
Advanced Setting; this should not normally be changed.

This supplies the hostname to use in Generic Security Services API (GSSAPI) principal names.

Use "$ALL" (with the quotation marks) to allow all keytab entries.

auth_krb5_keytab

Default<system default (e.g. /etc/krb5.keytab)>
Valuestring
Advanced Setting; this should not normally be changed.

This specifies the Kerberos keytab to use for the GSSAPI mechanism.

Note: You may need to set the auth service to run as root in order for this file to be readable.

auth_master_socket_path

Defaultauth-master
Valuestring
Advanced Setting; this should not normally be changed.

The UNIX socket path to the master authentication server for finishing user logins.

It is usually neither necessary nor advisable to change the default.

auth_policy_hash_truncate

Default12
Valueunsigned integer
See Also
Advanced Setting; this should not normally be changed.

How many bits to use from password hash when reporting to policy server.

auth_proxy_self

Default[None]
Valuestring
Advanced Setting; this should not normally be changed.

If the destination for proxying matches any of the IP addresses listed here, proxying is not performed when proxy_maybe=yes is returned.

This parameter isn't normally needed; its main use is if the destination IP address belongs to, for instance, a load-balancer rather than the server itself.

auth_socket_path

Defaultauth-userdb
Valuestring
Advanced Setting; this should not normally be changed.

The UNIX socket path to the master authentication server for finding users.

This must be set to cluster-userdb in Palomar cluster configurations, for both proxies and backends.

auth_use_winbind

Defaultno
Valueboolean
Advanced Setting; this should not normally be changed.

By default, the NTLM mechanism is handled internally.

If yes, perform NTLM and GSS-SPNEGO authentication with Samba's winbind daemon and ntlm_auth helper.

This option is useful when you need to authenticate users against a Windows domain (either AD or NT).

auth_username_translation

Default[None]
Valuestring
Advanced Setting; this should not normally be changed.

If set, performs username character translations before querying the auth database.

The value is a string formed of sets of from and to characters alternating.

A value of #@/@ means that # and / will both be translated to the @ character.

auth_winbind_helper_path

Default[None]
Valuestring
Advanced Setting; this should not normally be changed.

This setting tells the system the path for Samba's ntlm_auth helper binary.

Example:

auth_winbind_helper_path = /usr/bin/ntlm_auth

base_dir

Default/var/run/dovecot/
Valuestring
Advanced Setting; this should not normally be changed.

The base directory in which Dovecot should store runtime data.

This can be used to override the base directory determined at compile time.

cluster_localdb

Default[None]
Valuestring
Advanced Setting; this should not normally be changed.

Configuration for the backend-specific local database. This is expected to point to metacache-users socket.

Cluster: Applies only to Backend.

dns_client_socket_path

Defaultdns-client
Valuestring
Advanced Setting; this should not normally be changed.

UNIX socket path to the dns-client service.

dsync_hashed_headers

DefaultDate Message-ID
Valuestring
Advanced Setting; this should not normally be changed.

Which email headers are used in incremental syncing for checking whether the local email matches the remote email?

Format: a space-separated list of headers.

This list should only include headers that can be efficiently downloaded from the remote server.

fs_azure_url

Defaulthttps://blob.core.windows.net
Valuestring
Pluginobox plugin
Advanced Setting; this should not normally be changed.

URL for accessing the Azure storage. It is not intended to be changed, unless testing some other Azure-compatible storage.

fs_posix_accurate_mtime

Defaultno
Valueboolean
Advanced Setting; this should not normally be changed.

Configure whether utimes() is called after writes to guarantee microsecond precision timestamps for files. By default Linux updates the mtime only on timer interrupts, which is not remotely close to microsecond precision.

fs_posix_autodelete_empty_directories

Defaultno
Valueboolean
Advanced Setting; this should not normally be changed.

If the last file in a directory is deleted, should the parent directory be automatically deleted?

INFO

Using this setting makes the POSIX filesystem behave more like an object storage would.

WARNING

This setting can cause the POSIX filesystem to also delete the parent directory hierarchy farther up than anticipated.

fs_posix_lock_method

Defaultflock
Valuestring
Allowed Valuesflockdotlock
Advanced Setting; this should not normally be changed.

Lock method to use for locking files. Currently nothing uses lib-fs locking.

fs_s3_auth_host

Default169.254.169.254
Valuestring
Pluginobox plugin
Advanced Setting; this should not normally be changed.

AWS IAM hostname. Normally there is no reason to change this. This is mainly intended for testing.

fs_s3_auth_port

Default80
ValuePort Number
Pluginobox plugin
Advanced Setting; this should not normally be changed.

AWS IAM port. Normally there is no reason to change this. This is mainly intended for testing.

fs_sproxyd_access_by_path

Defaultno
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Objects are accessed by the path instead of by the object ID. Scality sproxyd internally converts the paths into object IDs.

fs_sproxyd_avoid_423_timeout

Default[None]
Valueunsigned integer
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Delay DELETE requests if the same object ID has been GET/HEAD/PUT by the same process within Millisecond Time. This is intended to reduce 423 Locked sent by Scality.

When 0, no delay is added. Only use this setting, if it can be seen to bring a benefit. Careful investigation of current error-rates and consideration of the overall throughput of the platform are recommended before using it.

fts_dovecot_mail_flush_interval

Default10
Valueunsigned integer
Pluginfts-dovecot plugin
Changes
  • Changed: 3.0.0

    Default changed from 0 to 10

Advanced Setting; this should not normally be changed.

Upload locally cached FTS indexes to object storage every N new emails. This reduces the number of emails that have to be read after backend failure to update the FTS indexes, but at the cost of doing more writes to object storage.

fts_dovecot_max_triplets

Default200
Valueunsigned integer
Pluginfts-dovecot plugin
Changes
  • Changed: 3.0.0

    Default changed from 0 to 200

Advanced Setting; this should not normally be changed.

FTS lookups will fail and error message will be logged, when the number of triplets exceeds the threshold specified in the setting. 0 means there is no maximum number of triplets to be exceeded.

fts_dovecot_min_merge_l_file_size

Default128 kB
Valuesize
Pluginfts-dovecot plugin
Advanced Setting; this should not normally be changed.

The smallest FTS triplet is getting recreated whenever indexing new mails until it reaches this size. Then the triplet becomes merged with the next largest triplet.

When fts-cache is used, this effectively controls how large the fts.L file can become in metacache until the FTS triplet is uploaded to object storage.

http_client_auto_redirect

Defaultyes
Valueboolean
See Also
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

If this setting is yes redirects are handled as long as http_client_request_max_redirects isn't reached. If no the redirect responses are handled as regular failure responses.

WARNING

This setting should likely be changed only in the code, never in configuration.

http_client_auto_retry

Defaultyes
Valueboolean
See Also
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

If this setting is no requests are not automatically retried by the generic HTTP client code. It's still possible to retry the requests with explicit http_client_request_try_retry() calls as long as http_client_request_max_attempts isn't reached.

WARNING

This setting should likely be changed only in the code, never in configuration.

http_client_connect_backoff_max_time

Default1 min
Valuetime (milliseconds)
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

Maximum backoff time for retries.

http_client_connect_backoff_time

Default100 ms
Valuetime (milliseconds)
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

Initial backoff time for retries. It's doubled at each connection failure.

http_client_dns_ttl

Default30 mins
Valuetime (milliseconds)
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

How long to cache DNS entries.

http_client_max_auto_retry_delay

Default[None]
Valuetime
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

Maximum acceptable delay for automatically retrying/redirecting requests. If a server sends a response with a Retry-After header that causes a delay longer than this, the request is not automatically retried and the response is returned.

http_client_response_hdr_max_field_size

Default8k
Valuesize
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

Response header limit: Max size for an individual field.

http_client_response_hdr_max_fields

Default50
Valueunsigned integer
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

Response header limit: Max number of fields.

http_client_response_hdr_max_size

Default200k
Valuesize
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

Response header limit: Max size for the entire response header.

http_client_socket_recv_buffer_size

Default[None]
Valuesize
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

The kernel receive buffer size for the connection sockets. 0 = kernel defaults.

http_client_socket_send_buffer_size

Default[None]
Valuesize
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

The kernel send buffer size for the connection sockets. 0 = kernel defaults.

http_client_soft_connect_timeout

Default[None]
Valuetime (milliseconds)
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

Time to wait for TCP connect and SSL handshake to finish for the first connection before trying the next IP in parallel. 0 = wait until current connection attempt finishes.

http_client_user_agent

Default[None]
Valuestring
Changes
  • Added: 3.1.0
Advanced Setting; this should not normally be changed.

User-Agent: header to send.

http_server_default_host

Default[None]
Valuestring
Advanced Setting; this should not normally be changed.

Overwrite the local hostname with http_server_default_host.

http_server_max_payload_size

Default10G
Valuesize
Advanced Setting; this should not normally be changed.

Request payload limit: Max size for the request payload.

http_server_max_target_length

Default8k
Valuesize
Advanced Setting; this should not normally be changed.

Request target limit: Maximum length of the request target.

http_server_request_hdr_max_field_size

Default8k
Valuesize
Advanced Setting; this should not normally be changed.

Request header limit: Max size for an individual field.

http_server_request_hdr_max_fields

Default50
Valueunsigned integer
Advanced Setting; this should not normally be changed.

Request header limit: Max number of fields.

http_server_request_hdr_max_size

Default200k
Valuesize
Advanced Setting; this should not normally be changed.

Request header limit: Max size for the entire request header.

http_server_socket_recv_buffer_size

Default[None]
Valuesize
Advanced Setting; this should not normally be changed.

The kernel receive buffer size for the connection sockets. 0 = kernel defaults.

http_server_socket_send_buffer_size

Default0
Valuesize
Advanced Setting; this should not normally be changed.

The kernel send buffer size for the connection sockets. 0 = kernel defaults.

imap_idle_notify_interval

Default2mins
Valuetime
Advanced Setting; this should not normally be changed.

The amount of time to wait between "OK Still here" untagged IMAP responses when the client is in IDLE operation.

imap_max_line_length

Default64k
Valuesize
Advanced Setting; this should not normally be changed.

Maximum IMAP command line length. Some clients generate very long command lines with huge mailboxes, so you may need to raise this if you get Too long argument or IMAP command line too large errors often.

intercept_api_utimaco_sql_query_surveillance

Default SELECT uuid, UNIX_TIMESTAMP(created) AS created FROM targets WHERE userid_hash = '%{user | md5 | hexlify}'
Valuestring
Advanced Setting; this should not normally be changed.

The SQL query used to obtain surveillance information (from the Utimaco X1 service) about a particular e-mail address.

See intercept_utimaco_x1_sql_query_check_surveillance for variable substitution information.

intercept_utimaco_x1_sql_query_add_surveillance

Default INSERT INTO targets (userid_hash, uuid, address) VALUES ('%{userid | md5 | hexlify}', '%{uuid}', '%{address}')
Valuestring
Advanced Setting; this should not normally be changed.

The SQL query used to add a new target to the Utimaco X1 surveillance database.

See intercept_utimaco_x1_sql_query_check_surveillance for variable substitution information.

intercept_utimaco_x1_sql_query_cancel_surveillance

DefaultDELETE FROM targets WHERE uuid = '%{uuid}'
Valuestring
Advanced Setting; this should not normally be changed.

The SQL query used to remove a target from the Utimaco X1 surveillance database.

See intercept_utimaco_x1_sql_query_check_surveillance for variable substitution information.

intercept_utimaco_x1_sql_query_check_surveillance

Default SELECT uuid FROM targets WHERE userid_hash = '%{userid | md5 | hexlify}
Valuestring
Advanced Setting; this should not normally be changed.

The SQL query used to check (from Utimaco X1 service) whether an e-mail address is already surveilled.

Variable substitutions supported:

Variable Description
%{userid} User ID
%{uuid} UUID
%{address} Address

intercept_utimaco_x1_sql_query_get_surveillance_status

DefaultSELECT uuid FROM targets WHERE uuid = '%{uuid}'
Valuestring
Advanced Setting; this should not normally be changed.

The SQL query used to check (from the Utimaco X1 surveillance database) whether an UUID is currently surveilled.

See intercept_utimaco_x1_sql_query_check_surveillance for variable substitution information.

intercept_utimaco_x1_sql_query_get_user_data

DefaultSELECT userid_hash, address FROM targets WHERE uuid = '%{uuid}'
Valuestring
Advanced Setting; this should not normally be changed.

The SQL query used to get information (from the Utimaco X1 surveillance database) about a surveilled user.

See intercept_utimaco_x1_sql_query_check_surveillance for variable substitution information.

intercept_utimaco_x1_sql_query_list_surveillances

DefaultSELECT uuid FROM targets
Valuestring
Advanced Setting; this should not normally be changed.

The SQL query used to list all items from the Utimaco X1 surveillance database.

See intercept_utimaco_x1_sql_query_check_surveillance for variable substitution information.

intercept_utimaco_x1_testing

Defaultno
Valueboolean
Advanced Setting; this should not normally be changed.

Enable the Utimaco testing mode for the utimaco-x1 service, in which the use of TLS is not required.

intercept_utimaco_x3_debug

Defaultno
Valueboolean
Advanced Setting; this should not normally be changed.

Enable debug logging for utimaco-x3 service.

intercept_utimaco_x3_kafka_consume_max_size

Default10M
Valuesize
Advanced Setting; this should not normally be changed.

Limit a batch of consumed messages to approximately this size.

intercept_utimaco_x3_kafka_consume_min_size

Default[None]
Valuesize
Advanced Setting; this should not normally be changed.

The broker will respond to a consumer when a batch of messages with this cumulative size is available.

intercept_utimaco_x3_kafka_consumer_group

Defaultutimaco-x3-consumers
Valuestring
Advanced Setting; this should not normally be changed.

The name of the Kafka consumer group used by the utimaco-x3-kafka consumer service. This is currently only used to record the current consumption offset on the Kafka cluster; it is currently not possible to have more than a single consumer!

intercept_utimaco_x3_rawlog_dir

Default[None]
Valuestring
Advanced Setting; this should not normally be changed.

If this directory exists, and it is writable by the utimaco-x3 service, the messages exchanged between client and server are logged here. This is useful for debugging.

intercept_utimaco_x3_testing

Defaultno
Valueboolean
Advanced Setting; this should not normally be changed.

Enable the Utimaco testing mode for the utimaco-x3 service, in which the use of TLS is not required.

language_tokenizer_kuromoji_split_compounds

Defaultyes
Valueboolean
See Also
Pluginfts plugin
Advanced Setting; this should not normally be changed.

This setting enables search mode in the Atilika Kuromoji library. The setting defaults to enabled and should not be changed unless there is a compelling reason.

WARNING

If this setting is changed, existing FTS indexes will produce unexpected results. The FTS indexes should be recreated in this case.

libexec_dir

Default/usr/libexec/dovecot
Valuestring
Advanced Setting; this should not normally be changed.

The directory from which you execute commands via doveadm-exec.

lmtp_verbose_replies

Defaultno
Valueboolean
Advanced Setting; this should not normally be changed.

This setting makes the replies returned to the client much more verbose. Currently, this only applies when the LMTP proxy is involved, for which e.g. backend connection errors are returned in full detail.

Normally, these errors are replaced by a more generic error message to prevent leaking system details to the clients (e.g. IP addresses and ports). It is therefore not recommended to enable this setting beyond troubleshooting efforts.

login_proxy_notify_path

Defaultproxy-notify
Valuestring
Advanced Setting; this should not normally be changed.

Path to proxy-notify pipe.

Login Variables can be used.

login_socket_path

Default[None]
Valuestring
Changes
  • Added: 3.0.0
Advanced Setting; this should not normally be changed.

Default socket path for all services' login processes. Can be overridden by passing a parameter to the login executable.

This must be set to cluster in Palomar cluster configurations, for both proxies and backends.

mail_cache_max_header_name_length

Default100
Valueunsigned integer
Changes
  • Added: 3.0.0
Advanced Setting; this should not normally be changed.

Maximum header name length stored in the cache, where 0 stands for unlimited (which is also the former behavior).

When enabled, the cache truncates the names to this length in memory and on file. While the header name remains unchanged in the storage, all the headers sharing the first mail_cache_max_header_name_length prefix characters are de facto aliased and will be considered as the same header on cache fetch.

Also, attempting to fetch a specific aliased header will succeed even if the header does not actually exist (this does NOT happen when the feature is disable with explicitly with mail_cache_max_header_name_length = 0)

Example: (mail_cache_max_header_name_length = 5)

If the mail contains the header X-name: value, attempting to fetch X-nam or X-names will also produce X-name: value as a result (with the original header name, not the requested one).

Trying to fetch the mail text or the mail headers will properly return only X-name: value.

mail_cache_max_headers_count

Default100
Valueunsigned integer
Changes
  • Added: 3.0.0
Advanced Setting; this should not normally be changed.

Maximum number of headers in yes/temp cache decision before the cache refuses to promote more header decisions from no to temp, where 0 stands for unlimited (which is also the former behavior).

When entries are rejected, the event mail_cache_decision_rejected is emitted.

Also, while the cache's headers count is saturated, the effective value of mail_cache_unaccessed_field_drop is reduced to 1/4 of of the specified one, in order to aid the cache to return within the limits.

mail_cache_max_size

Default1G
Valuesize
Advanced Setting; this should not normally be changed.

If dovecot.index.cache becomes larger than this, it's truncated to empty size.

WARNING

The maximum value is 1 GB because the cache file format can't currently support larger sizes.

mail_cache_min_mail_count

Default[None]
Valueunsigned integer
Advanced Setting; this should not normally be changed.

Only update cache file when the mailbox contains at least this many messages.

With a setting other than 0, you can optimize behavior for fewer disk writes at the cost of more disk reads.

mail_cache_purge_continued_percentage

Default200
Valueunsigned integer
Advanced Setting; this should not normally be changed.

Compress the cache file when n% of records are deleted (by count, not by size).

For example 200 means that the record has 2 continued rows, i.e. it exists in 3 separate segments in the cache file.

mail_cache_purge_delete_percentage

Default20
Valueunsigned integer
Advanced Setting; this should not normally be changed.

Compress the cache file when n% of records are deleted (by count, not by size).

mail_cache_purge_header_continue_count

Default4
Valueunsigned integer
Advanced Setting; this should not normally be changed.

Compress the cache file when we need to follow more than n next_offsets to find the latest cache header.

mail_cache_purge_min_size

Default32k
Valuesize
Advanced Setting; this should not normally be changed.

Only compress cache file if it is larger than this size.

mail_cache_record_max_size

Default64k
Valuesize
Advanced Setting; this should not normally be changed.

If a cache record becomes larger than this, don't add it to the cache file.

mail_cache_unaccessed_field_drop

Default30days
Valuetime
See Also
Advanced Setting; this should not normally be changed.

Specifies when cache decisions are downgraded.

Change caching decision from YES to TEMP after this much time has passed. Drop the field entirely after twice this much time has passed, regardless of whether the cache decision was YES or TEMP previously.

If the cache header count is capped to mail_cache_max_headers_count then the effective value is reduced to 1/4 of the configured value until enough headers expire for the cache to fall back inside the limits.

mail_ext_attachment_hash

Default%{sha1}
Valuestring
Allowed Values%{md4}%{md5}%{sha1}%{sha256}%{sha512}%{size}
See Also
Advanced Setting; this should not normally be changed.

The hash format to use in attachment filenames when saving attachments externally.

Variables and additional text can be included in this string.

The syntax allows truncation of any variable. For example %{sha256:80} will return only the first 80 bits of the SHA256 output.

mail_full_filesystem_access

Defaultno
Valueboolean
See Also
Advanced Setting; this should not normally be changed.

Allow full filesystem access to clients?

If enabled, no access checks are performed other than what the operating system does for the active UID/GID. This also disables the mailbox_list_validate_fs_names setting.

This setting works with both Maildir and mbox, allowing you to prefix mailbox names with /path/ or ~user/ indicators.

mail_index_log2_max_age

Default2days
Valuetime
Advanced Setting; this should not normally be changed.

Delete .log.2 index file when older than this value.

Older .log.2 files are useful for QRESYNC and dsync, so this value should not be too low.

mail_index_log_rotate_min_size

Default32k
Valuesize
Advanced Setting; this should not normally be changed.

Rotate transaction log if it is larger than this size and is older than mail_index_log_rotate_min_age.

mail_index_rewrite_max_log_bytes

Default128k
Valuesize
See Also
Advanced Setting; this should not normally be changed.

Rewrite the index when the number of bytes that needs to be read from the .log index file on refresh is between these min/max values.

mail_index_rewrite_min_log_bytes

Default8k
Valuesize
See Also
Advanced Setting; this should not normally be changed.

Rewrite the index when the number of bytes that needs to be read from the .log index file on refresh is between these min/max values.

mail_max_keyword_length

Default50
Valueunsigned integer
Advanced Setting; this should not normally be changed.

The maximum length allowed for a mail keyword name.

Compliance is enforced only during attempts to create new keywords.

mail_save_crlf

Defaultno
Valueboolean
Advanced Setting; this should not normally be changed.

Save message with CR+LF line endings?

Messages are normally saved with LF line endings.

Enabling this makes saving messages less CPU-intensive, especially with the sendfile() system call used in Linux and FreeBSD. However, enabling comes at the cost of slightly increased disk I/O, which could decrease the speed in some deployments.

mailbox_idle_check_interval

Default30secs
Valuetime
Advanced Setting; this should not normally be changed.

The minimum time between checks for new mail/other changes when a mailbox is in the IMAP IDLE state.

mailbox_subscriptions_filename

Defaultsubscriptions
specific Mailbox Formats have different defaults
Valuestring
Advanced Setting; this should not normally be changed.

Specifies the filename used for storing mailbox subscriptions.

managesieve_client_workarounds

Default[None]
ValueBoolean List
Advanced Setting; this should not normally be changed.

Enables various workarounds for ManageSieve clients. Currently there are none.

managesieve_implementation_string

DefaultDovecot Pigeonhole
Valuestring
Advanced Setting; this should not normally be changed.

Sets the ManageSieve implementation string returned by the IMPLEMENTATION capability.

managesieve_max_compile_errors

Default5
Valueunsigned integer
Advanced Setting; this should not normally be changed.

The maximum number of compile errors that are returned to the client upon script upload or script verification.

managesieve_max_line_length

Default64k
Valuesize
Advanced Setting; this should not normally be changed.

The maximum ManageSieve command line length in bytes.

Since long command lines are very unlikely with ManageSieve, changing this will generally not be useful.

managesieve_notify_capability

Default<dynamically determined>
ValueBoolean List
Advanced Setting; this should not normally be changed.

NOTIFY capabilities reported by the ManageSieve service before authentication.

This does normally not need to be configured. If left unassigned, these will be assigned dynamically according to what the Sieve interpreter is configured to support using the global sieve_extensions setting (after login this may differ depending on the settings applicable to the authenticated user).

managesieve_sieve_capability

Default<dynamically determined>
ValueBoolean List
Advanced Setting; this should not normally be changed.

SIEVE capabilities reported by the ManageSieve service before authentication.

This does normally not need to be configured. If left unassigned, these will be assigned dynamically according to what the Sieve interpreter is configured to support using the global sieve_extensions setting (after login this may differ depending on the settings applicable to the authenticated user).

mbox_md5

Defaultapop3d
Valuestring
Allowed Valuesapop3dall
See Also
Advanced Setting; this should not normally be changed.

The mail-header selection algorithm to use for MD5 POP3 UIDLs when the setting pop3_uidl_format = %{md5} is applied.

mbox_min_index_size

Default[None]
Valuesize
See Also
Advanced Setting; this should not normally be changed.

For mboxes smaller than this size, index files are not written.

If an index file already exists, it gets read but not updated.

The default should not be changed for most installations.

metacache_bg_root_uploads

Defaultno
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

By default, doing changes to folders (e.g. creating or renaming) uploads changes immediately to object storage. If this setting is enabled, the upload happens sometimes later (within metacache_upload_interval).

metacache_bundle_list_cache

Defaultyes
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Enable caching bundle list.

metacache_index_merging

Defaultv2
Valuestring
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Specifies the algorithm to use when merging folder indexes.

Algorithm Description
none Disable the merging algorithm
v2 The new algorithm designed specifically for this purpose of merging two indexes. This is the recommended setting.

metacache_max_parallel_requests

Default10
Valueunsigned integer
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Maximum number of metacache read/write operations to do in parallel.

metacache_merge_max_uid_renumbers

Default100
Valueunsigned integer
Pluginobox plugin
Advanced Setting; this should not normally be changed.

This is used only with metacache_index_merging = v2.

If the merging detects that there are more than this many UIDs that are conflicting and would have to be renumbered, don't renumber any of them. This situation isn't expected to happen normally, and renumbering too many UIDs can cause unnecessary extra disk I/O.

The downside is that a caching IMAP client might become confused if it had previously seen different UIDs.

metacache_rescan_interval

Default1 day
Valuetime
See Also
Pluginobox plugin
Advanced Setting; this should not normally be changed.

How often to run a background metacache rescan, which makes sure that the disk space usage tracked by metacache process matches what really exists on filesystem.

The desync may happen, for example, because the metacache process (or the whole backend) crashes.

The rescanning helps with two issues:

  • If metacache filesystem uses more disk space than metacache process thinks, it may run out of disk space.
  • If metacache filesystem uses less disk space than metacache process thinks, metacache runs non-optimally since it's not filling it out as much as it could.

Setting this to 0 disables the rescan.

It's also possible to do this manually by running the doveadm metacache rescan command.

metacache_roots

Defaultmail_home and mail_chroot
Valuestring
See Also
Pluginobox plugin
Advanced Setting; this should not normally be changed.

List of metacache root directories, separated with :.

Usually this is automatically parsed directly from mail_home and mail_chroot settings.

Accessing a metacache directory outside these roots will result in a warning: "Index directory is outside metacache_roots".

It's possible to disable this check entirely by setting the value to :.

TIP

This setting is required for metacache_rescan_interval.

metacache_secondary_indexes

Defaultyes
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Enable including secondary indexes into the user root bundle when using the virtual or virtual-attachments plugin.

This setting can be used to exclude the virtual and virtual-attachments folders from the user root bundle in case any problems are encountered.

metacache_size_weights

Default[None]
Valuestring
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Whenever metacache notices that metacache_max_space has been reached, it needs to delete some older index files to make space for new ones. This is done by calculating cleanup weights.

The simplest cleanup weight is to just use the user's last access UNIX timestamp as the weight. The lowest weight gets deleted first.

It's possible to enable using only simple weights by explicitly setting metacache_priority_weights and this setting to empty values. However, by default priorities are taken into account when calculating the weight.

The metacache_priority_weights setting can be used to fine tune how metacache adjusts the cleanup weights for different index priorities. There are 4 major priorities (these are also visible in e.g. doveadm metacache list output):

Priority Description
0 User root indexes (highest priority)
1 FTS indexes
2 INBOX and Junk folder indexes ("special" folders)
3 Non-special folder indexes (lowest priority)

The metacache_priority_weights contains <percentage> <weight adjustment> pairs for each of these priorities. So, for example, the first 10% +1d applies to the user root priority and the last 100% 0 applies to other folders' priority.

The weight calculation is then done by:

  • Initial weight is the user's last access UNIX timestamp
  • metacache_priority_weights is next looked up for the given priority indexes
  • If the total disk space used by the indexes is equal or less than the <percentage>, add <weight adjustment> to weight. So, for example, with 10% +1d if the disk space used by index files of this priority type take <= 10% of metacache_max_space, increase the weight by 1d = 60*60*24 = 86400.
  • Because the initial weight is based on UNIX timestamp, the weight adjustment is also given as time. This practically means that e.g. +1d typically gives 1 extra day for the index files to exist compared to index files that don't have the weight boost.
  • <percentage> exists so that the weight boost doesn't cause some index files to dominate too much. For example, if root indexes' weights weren't limited, it could be possible that the system would be full of only root indexes and active users' other indexes would be cleaned almost immediately.

This setting is used to do final adjustments depending on the disk space used by this user's indexes of the specific priority. The setting is in format <low size> <low weight adjustment> <max size> <high weight adjustment>.

The weight adjustment calculation is:

  • If disk space is equal or less than <low size>, increase weight by (<low size> - <disk space>) * <low weight adjustment> / <low size>
  • Otherwise, cap the <disk space> to <max size> and increase weight by (<disk space> - <low size>) * <high weight adjustment> / (<max size> - <low size>)
  • The idea here is to give extra weight boost for
    • Small indexes, because they're small enough that it won't matter if they live longer than most, AND
    • Very large indexes, because it's so expensive to keep uploading/downloading them in object storage
  • With the default 2M +30 1G +120 value the priority adjustments will look like:
    • 0 kB: +30
    • 500 kB: +23
    • 1 MB: +15
    • 1,5 MB: +8
    • 2 MB: 0
    • 10 MB: +1
    • 50 MB: +6
    • 100 MB: +12
    • 258 MB: +30
    • 500 MB: +60
    • >=1 GB: +120

Example:

metacache_priority_weights = 10% +1d 10% +1d 50% +1h 100% 0
metacache_size_weights = 2M +30 1G +120

metacache_userdb

Defaultmetacache/metacache-users.db
Valuestring
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Path to a database which metacache process periodically writes to.

This database is read by metacache at startup to get the latest state.

The path is relative to state_dir.

obox_allow_nonreproducible_uids

Defaultno
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Normally Dovecot attempts to make sure that IMAP UIDs aren't lost even if a backend crashes (or if user is moved to another backend without indexes first being uploaded). This requires uploading index bundles whenever expunging recently saved mails. Setting this to "yes" avoids this extra index bundle upload at the cost of potentially changing IMAP UIDs. This could cause caching IMAP clients to become confused, possibly even causing it to delete wrong mails. Also FTS indexes may become inconsistent since they also rely on UIDs.

obox_autofix_storage

Defaultno
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

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.

obox_avoid_cached_vsize

Defaultno
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Avoid getting the email's size from the cache whenever the email body is opened anyway. This avoid unnecessary errors if a lot of the vsizes are wrong. The vsize in dovecot.index is also automatically updated to the fixed value with or without this setting.

This setting was mainly useful due to earlier bugs that caused the vsize to be wrong in many cases.

obox_disable_fast_copy

Defaultno
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Workaround for object storages with a broken copy operation. Instead perform copying by reading and writing the full object.

obox_fetch_lost_mails_as_empty

Defaultno
Valueboolean
See Also
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Cassandra: "Object exists in dict, but not in storage" errors will be handled by returning empty emails to the IMAP client. The tagged FETCH response will be OK instead of NO.

obox_lost_mailbox_prefix

Defaultrecovered-lost-folder-
Valuestring
Pluginobox plugin
Advanced Setting; this should not normally be changed.

If folder name is lost entirely due to lost index files, generate a name for the folder using this prefix.

obox_max_rescan_mail_count

Default10
Valueunsigned integer
Pluginobox plugin
Advanced Setting; this should not normally be changed.

Keep a maximum of this many newly saved mails in local metacache indexes before metacache is flushed to object storage. For example with a value of 10, every 11th mail triggers a metacache flush. Note that the flush isn't immediate - it will happen in the background some time within the next metacache_upload_interval.

A higher value reduces the number of index bundle uploads, but increases the number of mail downloads to fill the caches after a backend crash.

obox_pop3_backend_uidls

Defaultyes
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

If set to no, don't try to lookup migrated POP3 UIDLs from email metadata in any situation. This used to bring performance improvements, but now the existence of migrated UIDLs is tracked more efficiently and there should be no need to change this setting.

obox_size_missing_action

Defaultwarn-read
Valuestring
Allowed Valueswarn-readreadstat
Pluginobox plugin
Advanced Setting; this should not normally be changed.

This setting controls what should be done when the mail object is missing the size metadata.

Options:

Value Description
read Same as warn-read, but doesn't log a warning.
stat Use fs_stat() to get the size, which is the fastest but doesn't work if mails are compressed or encrypted.
warn-read Log a warning and fallback to reading the email to calculate its size.

obox_use_object_ids

Defaultyes
Valueboolean
Pluginobox plugin
Advanced Setting; this should not normally be changed.

If enabled, access objects directly via their IDs instead of by path, if possible.

quota_clone_unset

Defaultno
Valueboolean
Pluginquota-clone plugin
Changes
  • Added: 3.0.0
Advanced Setting; this should not normally be changed.

Unset quota information before updating. This is needed with some dict drivers that do not support upserting, such as SQL with older SQLite.

service_privileged_group

Default[None]
Valuestring
See Also
Advanced Setting; this should not normally be changed.

Secondary UNIX group - which is disabled by default - but can be enabled by the process. mail_privileged_group setting is a more user friendly way to use this setting for mail processes.

sieve_duplicate_default_period

Default14d
Valuetime
See Also
Pluginsieve plugin
Advanced Setting; this should not normally be changed.

Default period after which tracked values are purged from the duplicate tracking database.

sieve_duplicate_max_period

Default7d
Valuetime
See Also
Pluginsieve plugin
Advanced Setting; this should not normally be changed.

Maximum period after which tracked values are purged from the duplicate tracking database.

sieve_include_max_includes

Default255
Valueunsigned integer
See Also
Pluginsieve plugin
Advanced Setting; this should not normally be changed.

The maximum number of scripts that may be included. This is the total number of scripts involved in the include tree.

sieve_max_script_size

Default1M
Valuesize
Pluginsieve plugin
Advanced Setting; this should not normally be changed.

The maximum size of a Sieve script. The compiler will refuse to compile any script larger than this limit.

If set to 0, no limit on the script size is enforced.

sieve_variables_max_scope_count

Default255
Valueunsigned integer
See Also
Pluginsieve plugin
Advanced Setting; this should not normally be changed.

The maximum number of variables that can be declared in a scope.

There are currently two variable scopes: the normal script scope and the global scope created by the Sieve include extension.

The minimum value for this setting is 128.

sieve_variables_max_value_size

Default4k
Valuesize
See Also
Pluginsieve plugin
Advanced Setting; this should not normally be changed.

The maximum allowed size for the value of a variable. If exceeded at runtime, the value is always truncated to the configured maximum.

The minimum value for this setting is 4000 bytes.

state_dir

Default/var/lib/dovecot
Valuestring
Advanced Setting; this should not normally be changed.

The compile-time directory PKG_STATEDIR (typically /var/lib/dovecot) is hard-coded as the location of state files. The PKG_STATEDIR value is taken as the default state_dir setting but can be overridden - for instance, if you wish to use the same binaries for a system daemon and a user daemon.

The settings state_dir = /home/foo/dovecot/state and base_dir = /home/foo/dovecot/run give an example of usage.

virtual_max_open_mailboxes

Default64
Valueunsigned integer
Pluginvirtual plugin
Advanced Setting; this should not normally be changed.

How many mailboxes to open in virtual plugin.

Revision: 8f8e997

Last updated:

Copyright © Open-Xchange GmbH