All Dovecot Settings

Settings

CASSANDRA_GEODB_KEYSPACE

Default	"d8s_cluster"
Value	Python String
Changes	Added: 3.0.1

Cassandra keyspace used for dovecot cluster.

CASSANDRA_KEYSPACE

Default	"d8s_cluster"
Value	Python String
Changes	Deprecated: 3.0.1 Use CASSANDRA_GEODB_KEYSPACE instead.

Cassandra keyspace to use.

CASSANDRA_LOAD_BALANCING_POLICY

Default	"DCAwareRoundRobin"
Value	Python 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"
Value	Python String
Changes	Added: 3.0.1

Name of the local datacenter in Cassandra cluster.

CASSANDRA_PORT

Default	9042
Value	Python Integer

The port Cassandra servers listen on.

CASSANDRA_PROTOCOL_VERSION

Default	4
Value	Python Integer

Version of the cassandra protocol to be used.

CASSANDRA_SERVERS

Default	"localhost"
Value	Python String

Comma separated list of Cassandra server endpoints.

CASSANDRA_SITE

Default	"d8s_cluster"
Value	Python String
Changes	Deprecated: 3.0.1 Use CASSANDRA_LOCAL_DC instead.

Name of the local datacenter in Cassandra cluster.

CASSANDRA_TLS_ENABLED

Default	False
Value	Python Boolean

Whether to use TLS in Cassandra connections.

CASSANDRA_USED_HOSTS_PER_REMOTE_DC

Default	0
Value	Python 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_BROKER_TRANSPORT_OPTIONS

Default	{}
Value	Python Dictionary

Needed when using Redis Sentinel where it's required to provide "master_name" as a key in the dictionary.

CELERY_BROKER_URL

Default	"redis://localhost:6379/0"
Value	Python String

A valid URI to Redis server or Redis Sentinel used for controller task brokering.

CELERY_RESULT_BACKEND

Default	"redis://localhost:6379/0"
Value	Python String

A valid URI to Redis server or Redis Sentinel used for holding task results.

CELERY_RESULT_BACKEND_TRANSPORT_OPTIONS

Default	{}
Value	Python Dictionary

Needed when using Redis Sentinel for celery results where it's required to provide "master_name" as a key in the dictionary.

CELERY_RESULT_EXPIRES_SECS

Default	60
Value	Python Integer

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

CLUSTER_SITE

Default	"dc1a"
Value	Python 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"
Value	Python 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

Default	200
Value	Python Integer

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

GROUP_BALANCE_ENABLED

Default	False
Value	Python Boolean

Whether to enable group balancing feature. This feature slowly redistributes users between groups in the same backend so they are roughly the same size.

GROUP_BALANCE_GROUP_SIZE_SLACK_PERCENT

Default	10
Value	Python Integer

If group size differences are larger than the given percentage, users will be redistributed.

GROUP_BALANCE_MAX_USER_MOVES_PER_PASS

Default	200
Value	Python Integer
See Also	Automatic Group Size Rebalancing

Maximum total number of users that can be moved (across all groups) at each iteration of group balancing. Should be higher than GROUP_BALANCE_MAX_USER_MOVE_BETWEEN_GROUPS since that setting controls number of users moved between a group pair while this setting controls the total sum of users moved across all group pairs.

GROUP_BALANCE_MAX_USER_MOVE_BETWEEN_GROUPS

Default	100
Value	Python Integer
See Also	Automatic Group Size Rebalancing

Maximum number of users that can be moved between individual groups at each iteration of balancing. Used to prevent big swings in group sizes and too much load on Cassandra.

GROUP_MOVE_FINISH_TIMEOUT_SECS

Default	600
Value	Python Integer
Changes	Added: 3.0.1

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

Default	180
Value	Python Integer
Changes	Added: 3.0.1

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_COOL_TIME_SECS

Default	3600
Value	Python Integer

Minimum time in seconds between moving groups from hosts with failing logins to other hosts. If a host has high failure rate and the cool off time from its last group move has passed, controller will try to find another host which also has passed its cool-off period to move a group to.

HOST_FAILURE_MIN_LOGINS

Default	10
Value	Python 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 groups from it if there is high failure rate).

HOST_FAILURE_RATIO

Default	0.1
Value	Python Float

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

HOST_LOAD_BALANCE_MIN_COOL_TIME_SECS

Default	3600
Value	Python Integer

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_SAMPLES

Default	3000
Value	Python Integer

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

HOST_LOAD_BALANCE_SCORE_DELTA_THRESHOLD_RATIO

Default	0.5
Value	Python Float

Minimum load score difference between backends to initiate group move. See Cluster controller load balancing.

PROMETHEUS_JOB_NAME

Default	""
Value	Python String

If set, will be used as the job name to scrape backend and proxy statistics. Required when a Prometheus instance is used that is managed outside of kubernetes installation (e.g. a central instance or mixed environments). If the Prometheus instance scrapes each site hosts with a different job name, this setting must have the value of the job name to prevent unwanted data in query results. Can be empty if using the bundled Prometheus with controller.

PROMETHEUS_URL

Default	"http://localhost:9090/"
Value	Python String

URL of Prometheus used to gather backend and proxy statistics.

acl

Default	[None]
Value	string
Plugin	acl plugin

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

The format is:

backend[:option[:option...]]

Currently, there is a single backend available: vfile. This backend 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 CONTROL) directory. This is the default.

This backend has the following options:

Name	Description
<global_path>	If a path is defined, this is the location of the global ACL configuration file.
cache_secs	The interval, in seconds, for running stat() on the ACL file to check for changes. DEFAULT: 30

Example:

plugin {
  # Per-user ACL:
  acl = vfile

  # Global ACL; check for changes every minute
  #acl = vfile:/etc/dovecot/dovecot-acl:cache_secs=60
}

acl_anyone

Default	[None]
Value	string
Allowed Values	allow
Plugin	imap-acl plugin

Users who have different set of keys cannot share mails when the mails are encrypted, but sharing is possible within the scope of a key.

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 you wish to allow it, set:

plugin {
  acl_anyone = allow
}

acl_defaults_from_inbox

Default	no
Value	boolean
Plugin	acl 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_globals_only

Default	no
Value	boolean
Plugin	acl 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]
Value	string
Plugin	acl 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_namespace

Default	[None]
Value	string
Plugin	acl plugin

Ignore ACLs entirely for the given namespace.

You can define multiple namespaces by appending an increasing number to the setting name.

Example:

plugin {
  acl_ignore_namespace = virtual/
  # Ignore shared/ and all its (autocreated) child namespaces
  acl_ignore_namespace2 = shared/*
}

acl_shared_dict

Default	[None]
Value	string
See Also	dictionary
Plugin	acl plugin

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:

plugin {
  acl_shared_dict = file:/var/lib/dovecot/shared-mailboxes
}

acl_user

Default	[None]
Value	string
See Also	ACL master users
Plugin	acl plugin

See auth_master_user_separator for the format of this setting.

apparmor_hat

Default	[None]
Value	string
Plugin	apparmor plugin

The AppArmor "hat" to change to when a user is loaded.

You can define multiple hats by appending an increasing number to the setting name.

Example:

plugin {
  apparmor_hat = hat_name
  apparmor_hat2 = another_hat
}

auth_allow_cleartext

Default	no
Value	boolean
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

Default	no
Value	boolean
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

Default	anonymous
Value	string

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

auth_cache_negative_ttl

Default	1hour
Value	time

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]
Value	size

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

Default	1hour
Value	time

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

Default	no
Value	boolean

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

Default	no
Value	boolean
Changes	Deprecated: 3.0.0 The setting is obsolete, and kept only for backwards compatibility. Use log_debug = category=auth instead.

Enables all authentication debug logging (also enables auth_verbose).

Passwords are logged as <hidden>.

auth_debug_passwords

Default	no
Value	boolean

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

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

Default	2secs
Value	time
See Also	auth_internal_failure_delay

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

Default	2secs
Value	time (milliseconds)
See Also	auth_failure_delay
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]
Value	string

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

Default	plain
Value	string
Allowed Values	plainlogindigest-md5cram-md5ntlmrpaapopanonymousgssapiotpskeygss-spnego

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

Example:

auth_mechanisms = plain login

auth_policy_check_after_auth

Default	yes
Value	boolean
See Also	auth_policy_server_url

Do policy lookup after authentication is completed?

auth_policy_check_before_auth

Default	yes
Value	boolean
See Also	auth_policy_server_url

Do policy lookup before authentication is started?

auth_policy_hash_mech

Default	sha256
Value	string
Allowed Values	md4md5sha1sha256sha512
See Also	auth_policy_server_url

Hash mechanism to use for password.

auth_policy_hash_nonce

Default	[None]
Value	string
See Also	auth_policy_server_url

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

Default	no
Value	boolean
See Also	auth_policy_server_url

Only log what the policy server response would do?

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

auth_policy_reject_on_fail

Default	no
Value	boolean
See Also	auth_policy_server_url

If policy request fails for some reason, should users be rejected?

auth_policy_report_after_auth

Default	yes
Value	boolean

Report authentication result?

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

auth_policy_request_attributes

Default	login=%{requested_username} pwhash=%{hashed_password} remote=%{rip} device_id=%{client_id} protocol=%s session_id=%{session} fail_type=%{fail_type}
Value	string
See Also	auth_policy_server_url
Changes	Changed: 3.0.0 Default has changed.

Request attributes specification.

Variables that can be used for this setting:

• Authentication variables

• %{hashed_password}

  • Truncated auth policy hash of username and password

• %{requested_username}

  • Logged in user. Same as %{user}, except for master user logins the same as %{login_user}.

auth_policy_server_api_header

Default	[None]
Value	string
See Also	auth_policy_server_url

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_timeout_msecs

Default	2000
Value	time (milliseconds)

Auth policy server request timeout.

auth_policy_server_url

Default	[None]
Value	URL

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]
Value	string

This setting supplies a space-separated 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_socket_path

Default	auth-userdb
Value	string

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_ssl_require_client_cert

Default	no
Value	boolean
See Also	ssl_ca ssl_verify_client_cert SSL configuration

If yes, authentication fails when a valid SSL client certificate is not provided.

auth_ssl_username_from_cert

Default	no
Value	boolean
See Also	ssl_cert_username_field

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_cert_username_field = name setting (parsed using OpenSSL's OBJ_txt2nid() function).

x500UniqueIdentifier is a common choice.

auth_username_chars

Default	abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@
Value	string

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	%Lu
Value	string

Formatting applied to username before querying the auth database.

You can use the standard variables here.

Examples:

• %Lu: Lowercases the username
• %n: Drops the domain if one was supplied
• %n-AT-%d: Changes the "@" symbol into "-AT-" before lookup

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

auth_verbose

Default	no
Value	boolean

Adjust log verbosity.

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

auth_verbose_passwords

Default	no
Value	string
Allowed Values	noyesplainsha1

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

Default	30
Value	unsigned 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.

charset_aliases

Default	[None]
Value	string
Plugin	charset-alias plugin

A space-separated string of <from>=<to> charsets. The "from" charsets will be treated as "to" charsets when decoding to UTF-8.

Example:

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

cluster_backend_name

Default	[None]
Value	string

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_password

Default	[None]
Value	string

Password used for logging into backends to see if it's up or down.

Cluster: Applies only to Proxy.

cluster_backend_test_username

Default	[None]
Value	string

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. Username used by backend for running doveadm cluster group access command. This command just needs any existing user to work - it doesn't matter that it's not actually in the accessed group.

Cluster: Applies to both Proxy and Backend.

cluster_default_group_count

Default	[None]
Value	unsigned integer

Number of user groups that may be automatically created. This is used for creating a group for a user that doesn't yet have one. The group will be named default-N where N is between 1 and cluster_default_group_count.

Cluster: Applies only to Proxy.

cluster_geodb

Default	[None]
Value	string

Dictionary URI used for the globally shared GeoDB. This typically points to Cassandra.

Cluster: Applies to both Proxy and Backend.

cluster_local_site

Default	[None]
Value	string

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_localdb

Default	[None]
Value	string

Dictionary URI used for the server-specific local database. This typically points to SQLite under /dev/shm.

Cluster: Applies to both Proxy and Backend.

cluster_proxy_check_backends

Default	yes
Value	string

If enabled, this proxy runs checks to see whether backends are up or down.

If disabled, this proxy never sets any backends offline.

Cluster: Applies only to Proxy.

cluster_user_move_timeout

Default	[None]
Value	time

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

Cluster: Applies only to Proxy.

debug_log_path

Default	info_log_path
Value	string

The log file to use for debug messages.

default_client_limit

Default	1000
Value	unsigned integer

The maximum number of simultaneous client connections per process for a service.

Once this number of connections is reached, the next incoming connection prompts spawning of another process.

This value can be overridden via the service configuration (client_limit) setting within service blocks.

default_idle_kill

Default	1mins
Value	time

The default value to use for the service configuration (idle_kill) setting within service blocks.

default_internal_group

Default	dovecot
Value	string
See Also	default_internal_user

Define the default internal group.

default_internal_user

Default	dovecot
Value	string
See Also	default_internal_group

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

Default	dovenull
Value	string

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_process_limit

Default	100
Value	unsigned integer

The maximum number of processes that may exist for a service.

This value can be overridden via the service configuration (process_limit) setting within service blocks.

default_vsz_limit

Default	256M
Value	size

The default virtual memory size limit for service processes.

Designed to catch processes that leak memory so that they can be terminated before they use up all the available resources.

This value can be overridden via the service configuration (vsz_limit) setting within service blocks.

deliver_log_format

Default	msgid=%m: %$
Value	string

The format to use for logging mail deliveries.

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

Variable Name	Description
%$	Delivery status message (e.g., saved to INBOX)
%{msgid}, %m	Message-ID
%{subject}, %s	Subject
%{from}, %f	From address
%{from_envelope}, %e	SMTP FROM envelope
%{size}, %p	Physical size
%{vsize}, %w	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=%m: %$

dotlock_use_excl

Default	yes
Value	boolean

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

Default	ALL
Value	string

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

The setting ALL allows all commands.

doveadm_api_key

Default	[None]
Value	string

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_http_rawlog_dir

Default	[None]
Value	string
See Also	rawlog

Directory where doveadm stores HTTP rawlogs.

doveadm_password

Default	[None]
Value	string

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]
Value	unsigned integer

Value Range: <1-65535>

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_socket_path

Default	doveadm-server
Value	string

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

doveadm_ssl

Default	no
Value	string
Allowed Values	nosslstarttls

TODO

doveadm_username

Default	doveadm
Value	string

The username for authentication to the doveadm service.

doveadm_worker_count

Default	[None]
Value	unsigned 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]
Value	string
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]
Value	string
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	_
Value	string

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

Default	100
Value	unsigned integer

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

dsync_features

Default	[None]
Value	string

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.

first_valid_gid

Default	1
Value	unsigned integer
See Also	last_valid_gid

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.

first_valid_uid

Default	500
Value	unsigned integer
See Also	last_valid_uid

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

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

fs_auth_cache_dict

Default	[None]
Value	string
Plugin	obox plugin

Dictionary URI where fs-auth process keeps authentication cache. This allows sharing the cache between multiple servers.

fs_auth_request_max_retries

Default	1
Value	unsigned integer
Plugin	obox plugin

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

fs_auth_request_timeout

Default	10s
Value	time (milliseconds)
Plugin	obox plugin

Absolute HTTP request timeout for authentication lookups.

fs_server_backend

Default	[None]
Value	string
See Also	Object storage server emulator
Plugin	obox plugin

Specifies how to store files with fs-server.

fts_autoindex

Default	no
Value	boolean
See Also	fts_autoindex_exclude fts_autoindex_max_recent_msgs
Plugin	fts plugin

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

fts_autoindex_exclude

Default	[None]
Value	string
See Also	fts_autoindex
Plugin	fts plugin
Changes	Changed: 3.0.0 This setting now honors namespaces for mailbox names.

To exclude a mailbox from automatic indexing, it can be listed in this setting.

To exclude additional mailboxes, add sequential numbers to the end of the plugin name.

Use either mailbox names or special-use flags (e.g. Trash).

For example:

plugin {
  fts_autoindex_exclude = Junk
  fts_autoindex_exclude2 = Trash
  fts_autoindex_exclude3 = External Accounts/*
}

This setting matches also the namespace prefix in folder names.

Namespaces match as follows:

• The full folder name, including the namespace prefix.

  For example fts_autoindex_exclude = Public/incoming would match the incoming folder in the Public/ namespace.

• For inbox=yes namespace, the folder name without the namespace prefix.

  For example fts_autoindex_exclude = incoming would match the incoming folder in the INBOX namespace, but not in the Public/ namespace.

• The folder names support * and ? wildcards.

  Namespace prefixes must NOT be specified and will not match for:

  • the INBOX folder
  • special-use flags (e.g. Trash)

fts_autoindex_max_recent_msgs

Default	[None]
Value	unsigned integer
See Also	fts_autoindex
Plugin	fts 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:

plugin {
  fts_autoindex_max_recent_msgs = 999
}

fts_decoder

Default	[None]
Value	string
Plugin	fts plugin

Decode attachments to plaintext using this service and index the resulting plaintext.

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

Example:

plugin {
  fts_decoder = decode2text
}

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

This setting and fts_tika cannot be used simultaneously.

fts_dovecot_fs

Default	[None]
Value	string
See Also	obox_fs mail_location
Plugin	fts-dovecot plugin

Define the location for the fts cache and indexes path on remote filesystems.

It must be somewhat synchronized with obox_fs and mail_location.

It is recommended that the FTS and email fscaches point to DIFFERENT locations.

fts_dovecot_message_count_stats

Default	no
Value	string
Plugin	fts-dovecot plugin

Enable tracking per-folder message counts in fts.S stats file. This is useful for the doveadm fts check fast command to return per-folder results. Note that this changes the fts.S file format to be backwards incompatible, so this should be enabled only after all backends in the cluster have been upgraded.

Old Dovecot versions won't fail when they see the new fts.S file, but it needs to be regenerated, which can temporarily cause bad performance.

fts_dovecot_prefix

Default	no
Value	string
Plugin	fts-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_enforced

Default	no
Value	string
Allowed Values	yesnobody
Plugin	fts plugin

Require FTS indexes to perform a search? This controls what to do when searching headers and what to do on error situations.

When searching from message body, the FTS index is always (attempted to be) updated to contain any missing mails before the search is performed.

no

Searching from message headers won't update FTS indexes. For header searches, the FTS indexes are used for searching the mails that are already in it, but the unindexed mails are searched via dovecot.index.cache (or by opening the emails if the headers aren't in cache).

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

yes

Searching from message headers updates FTS indexes, the same way as searching from body does. If FTS lookup or indexing fails, the search fails.

body

Searching from message headers won't update FTS indexes (the same behavior as with no). If FTS lookup or indexing fails, the search fails.

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

fts_filters

Default	no
Value	string
See Also	FTS Tokenization
Plugin	fts plugin

The list of filters to apply.

Language specific filter chains can be specified with fts_filters_<lang> (e.g. fts_filters_en).

See filters for configuration information.

fts_header_excludes

Default	[None]
Value	string
Plugin	fts plugin

The list of headers to, respectively, 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

plugin {
  fts_header_excludes = Received DKIM-* X-* Comments
  fts_header_includes = X-Spam-Status Comments
}

• 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

plugin {
  fts_header_excludes = *
  fts_header_includes = From To Cc Bcc Subject Message-ID In-* X-CustomApp-*
}

• No headers are indexed, except those specified in the includes.

fts_header_includes

Default	[None]
Value	string
See Also	fts_header_excludes
Plugin	fts plugin

fts_index_timeout

Default	[None]
Value	unsigned integer
Plugin	fts plugin

When the full text search backend 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. Note the fts_enforced setting does not change this behavior.

A value of 0 means no timeout.

fts_language_config

Default	<textcat dir>
Value	string
See Also	fts_languages
Plugin	fts 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 fts_languages.

Doing this improves language detection performance during indexing and also makes the detection more accurate.

Example:

plugin {
  fts_language_config = /usr/share/libexttextcat/fpdb.conf
}

fts_languages

Default	<textcat dir>
Value	string
See Also	fts_language_config
Plugin	fts plugin

A space-separated list of languages that the full text search should detect.

At least one language must be specified.

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

The filters used for stemming and stopwords are language dependent.

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

Example:

plugin {
  fts_languages = en de
}

fts_message_max_size

Default	[None]
Value	size
Plugin	fts plugin
Changes	Added: 3.0.0

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

fts_solr

Default	[None]
Value	string
Plugin	fts-solr plugin

Configuration of fts_solr driver.

Format is a space separated list of options:

fts_solr = [option1[=value1]] [option2[=value2]] [...]

See fts-solr plugin for configuration information.

fts_tika

Default	[None]
Value	string
Plugin	fts plugin
Changes	Changed: 3.0.0 Basic authentication support (via URL) is added.

URL for Apache Tika decoder for attachments.

Example:

plugin {
  fts_tika = http://tikahost:9998/tika/
}

This setting and fts_decoder cannot be used simultaneously.

fts_tokenizers

Default	generic email-address
Value	string
See Also	FTS Tokenization
Plugin	fts plugin

The list of tokenizers to use.

This setting can be overridden for specific languages by using fts_tokenizers_<lang> (e.g. fts_tokenizers_en).

See tokenizers for configuration information.

haproxy_timeout

Default	3secs
Value	time

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

haproxy_trusted_networks

Default	[None]
Value	string

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>
Value	string

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.

imap_capability

Default	[None]
Value	string

Override the IMAP CAPABILITY response.

If the value begins with the + character, the capabilities listed here are added at the end of the default string.

Example:

imap_capability = +XFOO XBAR

imap_client_workarounds

Default	[None]
Value	string

Workarounds for various IMAP client bugs can be enabled here. The list is space-separated.

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 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 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_compress_<algorithm>_level

Default	<algorithm dependent>
Value	unsigned integer

Defines the compression level for the given algorithm.

Per RFC 4978, only the deflate algorithm is currently supported.

Algorithm	Minimum	Default	Maximum
deflate	0 (no compression)	6	9

imap_fetch_failure

Default	disconnect-immediately
Value	string
Allowed Values	disconnect-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

Default	30secs
Value	time

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

Default	no
Value	boolean

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

Default	name *
Value	string

Which ID field names and values to send to clients.

Using * as the value makes Dovecot use the default value.

There are currently defaults for the following fields:

Field	Default
name	Name of distributed package (Default: Dovecot)
version	Dovecot version
os	OS name reported by uname syscall (similar to uname -s output)
os-version	OS version reported by uname syscall (similar to uname -r output)
support-url	Support webpage set in Dovecot distribution (Default: http://www.dovecot.org/)
support-email	Support email set in Dovecot distribution (Default: dovecot@dovecot.org)
revision	Short commit hash of Dovecot git source tree HEAD (same as the commit hash reported in dovecot --version)

Example:

imap_id_send = "name" * "version" * support-url http://example.com/

imap_intercept_disconnect_after

Default	[None]
Value	time
Plugin	imap-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

Default	no
Value	boolean

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

imap_logout_format

Default	in=%i out=%o 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}
Value	string

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

Variable Name	Description
%{input}, %i	Total number of bytes read from client
%{output}, %o	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

Default	no
Value	boolean

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_dict setting.

Example:

# Store METADATA information within user's Maildir directory
mail_attribute_dict = file:%h/Maildir/dovecot-attributes

protocol imap {
  imap_metadata = yes
}

imap_urlauth_host

Default	[None]
Value	URL

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.

Note

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

imap_urlauth_logout_format

Default	in=%i out=%o
Value	string
See Also	imap_urlauth_host

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

Note

This setting is currently not used.

Variables allowed:

Name	Description
%i	Total number of bytes read from the client
%o	Total number of bytes sent to the client

imap_urlauth_port

Default	143
Value	unsigned integer
See Also	imap_urlauth_host

Value Range: <1-65535>

The port is used with the URLAUTH extension in IMAP operation.

imapc_cmd_timeout

Default	5 mins
Value	time

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

Default	1
Value	unsigned integer

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

imapc_connection_retry_interval

Default	1 secs
Value	time (milliseconds)

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

imapc_features

Default	[None]
Value	string
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.

A space-separated 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.

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]
Value	string

The remote IMAP host to connect to.

imapc_list_prefix

Default	[None]
Value	string

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]
Value	string
See Also	imapc_password imapc_user

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 = %u
imapc_master_user = masteruser
imapc_password = masteruser-secret

Mail user variables can be used.

imapc_max_idle_time

Default	29 mins
Value	time

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

Default	[None]
Value	size

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

This setting is used to limit maximum memory usage.

A value of 0 indicates no maximum.

imapc_password

Default	[None]
Value	string
See Also	imapc_master_user imapc_user

The authentication password for the remote IMAP server.

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

imapc_port

Default	143
Value	unsigned integer

The port on the remote IMAP host to connect to.

imapc_rawlog_dir

Default	[None]
Value	string
See Also	rawlog

Log all IMAP traffic input/output to this directory.

imapc_sasl_mechanisms

Default	plain
Value	string

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 plain login

imapc_ssl

Default	no
Value	string
Allowed Values	noimapsstarttls

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

Default	yes
Value	boolean
See Also	imapc_ssl

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.

imapc_user

Default	[None]
Value	string
See Also	imapc_master_user imapc_password

The user identity to be used for performing a regular IMAP LOGIN to the source IMAP server.

Mail user variables can be used.

imapsieve_mailbox<XXX>_after

Default	[None]
Value	string
See Also	sieve-imapsieve plugin
Plugin	imap-sieve plugin

Points to a directory relative to the base_dir where the plugin looks for script service sockets.

The XXX in this setting is a sequence number, which allows configuring multiple associations between Sieve scripts and mailboxes.

imapsieve_mailbox<XXX>_before

Default	[None]
Value	string
See Also	sieve-imapsieve plugin
Plugin	imap-sieve plugin

When an IMAP event of interest occurs, this sieve script is executed before any user script respectively.

This setting each specify the location of a single sieve script. The semantics of this setting is similar to sieve_before: the specified scripts form a sequence together with the user script in which the next script is only executed when an (implicit) keep action is executed.

The XXX in this setting is a sequence number, which allows configuring multiple associations between Sieve scripts and mailboxes.

imapsieve_mailbox<XXX>_causes

Default	[None]
Value	string
Allowed Values	APPENDCOPYFLAG
See Also	sieve-imapsieve plugin
Plugin	imap-sieve plugin

Only execute the administrator Sieve scripts for the mailbox configured with imapsieve_mailbox_name when one of the listed IMAPSIEVE causes apply.

This has no effect on the user script, which is always executed no matter the cause.

The XXX in this setting is a sequence number, which allows configuring multiple associations between Sieve scripts and mailboxes.

imapsieve_mailbox<XXX>_from

Default	[None]
Value	string
See Also	sieve-imapsieve plugin
Plugin	imap-sieve plugin

Only execute the administrator Sieve scripts for the mailbox configured with imapsieve_mailbox_name when the message originates from the indicated mailbox.

This setting supports wildcards with a syntax compatible with the IMAP LIST command, meaning that this setting can apply to multiple or even all ("*") mailboxes.

The XXX in this setting is a sequence number, which allows configuring multiple associations between Sieve scripts and mailboxes.

imapsieve_mailbox<XXX>_name

Default	[None]
Value	string
See Also	sieve-imapsieve plugin
Plugin	imap-sieve plugin

This setting configures the name of a mailbox for which administrator scripts are configured.

The XXX in this setting is a sequence number, which allows configuring multiple associations between Sieve scripts and mailboxes.

All imapsieve_mailbox<XXX>_* settings with matching sequence numbers apply to the mailbox named by this setting.

The sequence of configured mailboxes ends at the first missing imapsieve_mailbox<XXX>_name setting.

This setting supports wildcards with a syntax compatible with the IMAP LIST command, meaning that this setting can apply to multiple or even all ("*") mailboxes.

imapsieve_url

Default	[None]
Value	URL
See Also	sieve-imapsieve plugin
Plugin	imap-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.

plugin {
  imapsieve_url = sieve://sieve.example.com
}

import_environment

Default	TZ CORE_OUTOFMEM CORE_ERROR
Value	string

A list of environment variables, space-separated, that are preserved and passed to all child processes.

It can include key = value pairs for assigning variables the desired value upon Dovecot startup.

info_log_path

Default	log_path
Value	string

The log file to use for informational messages.

instance_name

Default	dovecot
Value	string

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

Default	[None]
Value	string

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_api_utimaco_sql_connect

Default	[None]
Value	string
See Also	intercept_utimaco_x1_sql_connect

The Utimaco SQL database connect string for the Intercept API service.

This setting is different from intercept_utimaco_x1_sql_connect so that a less privileged database user can be configured for the API (needs no write access).

intercept_backend

Default	[None]
Value	string

The intercept backend to use.

intercept_box_add_hdr

Default	[None]
Value	string
See Also	intercept_box_path
Plugin	intercept-box plugin

Add an extra HTTP request header when intercept_box_fs points to HTTP-based storage.

See intercept_box_path for supported variable substitutions.

intercept_box_crypt_cipher

Default	[None]
Value	string
See Also	intercept_box_crypt_key
Plugin	intercept-box plugin

Encryption cipher used to generate the %{crypted_user} variable.

intercept_box_crypt_key

Default	[None]
Value	string
See Also	intercept_box_crypt_cipher
Plugin	intercept-box plugin

Secret encryption key used to generate the %{crypted_user} variable.

intercept_box_fs

Default	[None]
Value	string
Plugin	intercept-box plugin

Configuration for intercept-box plugin.

Example for POSIX interception:

intercept_box_fs = posix:prefix=/tmp/intercept/%u/%s-

intercept_box_path

Default	[None]
Value	string
Plugin	intercept-box plugin

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

The folder-name elements are specified in the order user, timestamp, type,

For example:

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

Variable substitutions supported:

Variable	Long Name	Description
%u	user	user@domain
%n	username	user
%d	domain	domain
%s	service	imap/pop3/lmtp
%l	lip	local IP
%r	rip	remote IP
%a	lport	local port
%b	rport	remote port
%h	home	user's home directory
	crypted_user	user@domain encrypted and hex-encoded
	timestamp	timestamp
	type	type
	guid	unique GUID including hostname
	guid128	unique hex-encoded 128bit GUID

intercept_buffer_dir

Default	[None]
Value	string

Path to temporary files creating intercepted data.

Needed only when intercept_buffer_max_size > 0.

intercept_buffer_max_size

Default	0
Value	size

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

If 0, buffers are always kept in memory.

intercept_debug

Default	[None]
Value	boolean
Plugin	imap-intercept plugin, lda-intercept plugin, lmtp-intercept plugin, mail-intercept plugin, pop3-intercept plugin

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_fs

Default	[None]
Value	string

Path to the intercept storage.

Variable substitutions supported:

Variable	Long Name	Description
%u	user	user@domain
%n	username	user
%d	domain	domain
%s	service	imap/pop3/lmtp
%l	lip	local IP
%r	rip	remote IP
%a	lport	local port
%b	rport	remote port
%h	home	user's home directory
	session	session ID
	crypted_user	user@domain encrypted and hex-encoded
	year	Time (year), e.g., 2012
	month	Time (month), e.g., 01..12
	day	Time (day), e.g., 01..31
	hour	Time (hour), e.g., 00..23
	min	Time (minute), e.g., 00..59
	sec	Time (second), e.g., 00..59

intercept_fs_header_line

Default	[None]
Value	string

Add a header to the log.

See intercept_fs for supported variable substitutions.

intercept_fs_rotate_at_midnight

Default	no
Value	boolean

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

intercept_fs_rotate_interval

Default	[None]
Value	time

Flush log and create a new one this often.

intercept_fs_rotate_size

Default	[None]
Value	size

Rotate the log when it reaches this size.

intercept_pine_host

Default	[None]
Value	string

PineApp server's hostname.

intercept_pine_port

Default	[None]
Value	unsigned integer

PineApp server's port.

intercept_tz

Default	<system time zone>
Value	string

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_user_crypt_cipher

Default	aes-256-cbc
Value	string
See Also	intercept_user_crypt_key

Encryption cipher used to generate the %{crypted_user} variable.

intercept_user_crypt_key

Default	[None]
Value	string
See Also	intercept_user_crypt_cipher

Secret encryption key used to generate the %{crypted_user} variable.

intercept_utimaco_sql_driver

Default	mysql
Value	string
Allowed Values	mysql

The Utimaco SQL database driver for the API service.

intercept_utimaco_x1_sql_connect

Default	[None]
Value	string

The Utimaco X1 SQL database connect string.

intercept_utimaco_x1_sql_driver

Default	mysql
Value	string
Allowed Values	mysql

The Utimaco X1 SQL database driver.

intercept_utimaco_x3_kafka_brokers

Default	[None]
Value	string

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]
Value	time

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]
Value	string

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]
Value	URL

The HTTP URL of the Utimaco X3 receiver.

last_login_dict

Default	[None]
Value	string
Plugin	last-login plugin

The dictionary where last login information is updated.

Example:

plugin {
  last_login_dict = redis:host=127.0.0.1:port=6379
}

last_login_key

Default	last-login/%u
Value	string
Plugin	last-login plugin

The key that is updated in the dictionary (defined by last_login_dict) with the last login information.

last_login_precision

Default	s
Value	string
Allowed Values	smsusns
Plugin	last-login plugin

Precision for last login timestamp.

last_valid_gid

Default	[None]
Value	unsigned integer
See Also	first_valid_gid

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]
Value	unsigned integer
See Also	first_valid_uid

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

Default	[None]
Value	string
See Also	lazy-expunge storage locations
Plugin	lazy-expunge plugin

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

lazy_expunge_exclude

Default	[None]
Value	string
Plugin	lazy-expunge plugin

Mailbox name/wildcard to exclude from lazy expunging.

Use either mailbox names or refer to them using special-use flags (e.g. Trash).

To exclude additional mailboxes, add sequential numbers to the end of the plugin name. For example:

plugin {
  lazy_expunge_exclude = Drafts
  lazy_expunge_exclude2 = External Accounts/*
}

This setting matches also the namespace prefix in folder names.

Namespaces match as follows:

• The full folder name, including the namespace prefix.

  For example lazy_expunge_exclude = Public/incoming would match the incoming folder in the Public/ namespace.

• For inbox=yes namespace, the folder name without the namespace prefix.

  For example lazy_expunge_exclude = incoming would match the incoming folder in the INBOX namespace, but not in the Public/ namespace.

• The folder names support * and ? wildcards.

  Namespace prefixes must NOT be specified and will not match for:

  • the INBOX folder
  • special-use flags (e.g. Trash)

lazy_expunge_only_last_instance

Default	no
Value	boolean
Plugin	lazy-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:

• Maildir (with maildir_copy_with_hardlinks = yes, which is the default)
• sdbox/mdbox

lda_mailbox_autocreate

Default	no
Value	boolean

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

lda_mailbox_autosubscribe

Default	no
Value	boolean

Should automatically created mailboxes be subscribed to?

lda_original_recipient_header

Default	[None]
Value	string

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

Example:

lda_original_recipient_header = X-Original-To

listen

Default	*, ::
Value	IP 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

listescape_char

Default	\
Value	string
Plugin	listescape plugin

The escape character to use.

% needs to be written twice to escape it, because Config variables are expanded in plugin section.

lmtp_add_received_header

Default	yes
Value	boolean

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

lmtp_client_workarounds

Default	[None]
Value	string

Configures the list of active workarounds for LMTP client bugs. The list is space-separated. 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

Default	final
Value	string
Allowed Values	alternativefinalnone

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

Default	no
Value	boolean
See Also	proxy passdb

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]
Value	string
See Also	rawlog

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]
Value	string
See Also	rawlog

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

Default	no
Value	boolean

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

Default	no
Value	boolean

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

Default	[None]
Value	unsigned integer

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.

lock_method

Default	fcntl
Value	string
Allowed Values	fcntlflockdotlock

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]
Value	string

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_debug

Default	[None]
Value	string

Filter to specify what debug logging to enable. The syntax of the filter is described in Global Metric Filters.

Note

This will eventually replace mail_debug and auth_debug settings.

log_path

Default	syslog
Value	string
See Also	debug_log_path info_log_path

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
Value	string

The prefix for each line written to the log file.

% variables are in strftime(3) format.

login_log_format

Default	%$: %s
Value	string

The formatting of login log messages.

Variables allowed (in addition to Global variables):

Variable Name	Description
%s	A login_log_format_elements string
%$	The log data

login_log_format_elements

Default	user=<%u> method=%m rip=%r lip=%l mpid=%e %c session=<%{session}>
Value	string

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
Value	string

Location of the login plugin directory.

login_plugins

Default	[None]
Value	string

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

login_proxy_max_disconnect_delay

Default	[None]
Value	unsigned integer

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

Default	3
Value	unsigned 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]
Value	string
See Also	rawlog

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

Default	30 secs
Value	time (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_socket_path

Default	[None]
Value	string
Changes	Added: 3.0.0

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.

login_source_ips

Default	[None]
Value	IP addresses

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.

To allow sharing of the same configuration across multiple servers, you may use a ? character at the start of the value to indicate that only the listed addresses that exist on the current server should be used.

Example:

login_source_ips = ?proxy-sources.example.com

login_trusted_networks

Default	[None]
Value	IP addresses

Value Format: A space-separated list of trusted network ranges.

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 (%{rip}, %{rport})
• Server IP and port (%{lip}, %{lport})

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 (%{rip}, %{rport})

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 (%{rip}, %{rport})

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 (%{rip}, %{rport})
• 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 (%{rip}, %{rport})
• 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.

mail_access_groups

Default	[None]
Value	string

Supplementary groups that are granted access for mail processes.

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

Note: It may be dangerous to set these up if users can create symlinks. For example: 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_always_cache_fields

Default	[None]
Value	string
See Also	mail_cache_fields mail_never_cache_fields

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	[None]
Value	string

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_attachment_dir

Default	[None]
Value	string

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_attachment_fs

Default	sis posix
Value	string
Allowed Values	posixsis posixsis-queue posix
See Also	mail_attachment_dir

Which filesystem type to use for saving attachments.

Options:

posix

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

sis posix

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 posix

SiS with delayed comparison and de-duplication.

Mail user variables can be used.

mail_attachment_min_size

Default	128k
Value	size
See Also	mail_attachment_dir

Attachments below this size will not be saved externally.

mail_attribute_dict

Default	[None]
Value	string
See Also	imap_metadata

The dictionary to be used for key=value mailbox attributes.

This is used by the URLAUTH and METADATA extensions.

Mail user variables can be used.

Example:

mail_attribute_dict = file:%h/dovecot-attributes

mail_cache_fields

Default	flags
Value	string
See Also	mail_always_cache_fields mail_never_cache_fields

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_chroot

Default	[None]
Value	string

The default chroot directory for mail processes.

This chroots all users globally into the same directory.

Mail service user variables can be used.

mail_compress_save

Default	[None]
Value	string
Plugin	mail-compress plugin

The compression algorithm to use. This setting is REQUIRED - if empty, the plugin is disabled.

The following algorithms are supported:

Name	Library (algorithm)
bz2	libbzip2 (bzip2)
gz	zlib (gzip)
lz4	liblz4
zstd	Zstandard

mail_compress_save_level

Default	<algorithm dependent>
Value	string
Plugin	mail-compress plugin

The compression level to use. This value is dependent on the algorithm chosen in mail_compress_save.

Name	Minimum	Default	Maximum
bz2	1	9	9
gz	0 (no compression)	6	9
lz4	1	1	9
zstd	1	3	22

mail_crypt_acl_require_secure_key_sharing

Default	no
Value	boolean
Plugin	mail-crypt plugin

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

mail_crypt_curve

Default	no
Value	string
Plugin	mail-crypt plugin

Defines the elliptic curve to use for key generation.

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

Example:

plugin {
  mail_crypt_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 plugin environment 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.

mail_crypt_global_private_key

Default	[None]
Value	string
Plugin	mail-crypt plugin

Private key(s) to decrypt files. Key(s) must be in PEM format, using pkey format.

You can define multiple keys by appending an increasing number to the setting label, e.g.: mail_crypt_global_private_key2.

mail_crypt_global_public_key

Default	[None]
Value	string
Plugin	mail-crypt plugin

Public key to encrypt files. Key must be in PEM format, using pkey format.

mail_crypt_private_key

Default	[None]
Value	string
Plugin	mail-crypt plugin

Private key to decrypt user's master key. Key must be in PEM format, using pkey format.

mail_crypt_private_password

Default	[None]
Value	string
Plugin	mail-crypt plugin

Password to decrypt user's master key or environment private key.

mail_crypt_require_encrypted_user_key

Default	[None]
Value	boolean
Plugin	mail-crypt plugin

If true, require user key encryption with password.

mail_crypt_save_version

Default	2
Value	unsigned integer
Plugin	mail-crypt plugin

Sets the version of the mail_crypt compatibility desired.

Version	Description
0	Decryption is active; no encryption occurs.
1	Do not use (implemented for legacy reasons only).
2	Encryption and decryption are active.

mail_debug

Default	no
Value	boolean

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_fsync

Default	optimized
Value	string
Allowed Values	alwaysoptimizednever

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

Default	[None]
Value	stringunsigned integer
See Also	mail_uid

The system group ID used for accessing mail messages.

Can be either numeric IDs or group names.

If you use multiple values here, userdb can override them by returning the gid field.

mail_home

Default	[None]
Value	string
See Also	mail_location quick configuration

There are various possible ways of specifying this parameter and mail_location.

The following example is one option when home=/var/vmail/domain/user/ and mail=/var/vmail/domain/user/mail/:

mail_home = /var/vmail/%d/%n
mail_location = maildir:~/mail

Mail service user variables can be used.

mail_location

Default	[None]
Value	string
See Also	mail_location setting

This setting indicates the location for users' mailboxes.

For an empty value, Dovecot attempts to find the mailboxes automatically (looking at ~/Maildir, /var/mail/username, ~/mail, and ~/Mail, in that order). However, auto-detection commonly fails for users whose mail directory hasn't yet been created, so you should explicitly state the full location here, if possible.

Mail user variables can be used.

mail_log_cached_only

Default	no
Value	boolean
Plugin	mail-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]
Value	string
Plugin	mail-log plugin

A space-separated 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]
Value	string
Plugin	mail-log plugin

A space-separated 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	%s(%u)<%{process:pid}><%{session}>
Value	string

You can specify a log prefix for mail processes here.

Mail service user variables can be used.

mail_lua_script

Default	[None]
Value	string
Plugin	mail-lua plugin

Specify filename to load for user.

Example:

plugin {
  mail_lua_script = /etc/dovecot/user.lua
}

mail_max_lock_timeout

Default	0
Value	time

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

Default	10
Value	unsigned 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_never_cache_fields

Default	imap.envelope
Value	string
See Also	mail_always_cache_fields mail_cache_fields

List of fields that should never be cached.

This should generally never include anything other than imap.envelope, which isn't needed because it can be generated from the cached header fields.

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

mail_nfs_index

Default	no
Value	boolean
See Also	mail_fsync

When mail-index files exist in NFS storage and you're running a multi-server setup that you wish to flush NFS caches, this can be set to yes (in this case, make sure also to use mmap_disable = yes and mail_fsync = optimized).

mail_nfs_storage

Default	no
Value	boolean

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_plugin_dir

Default	/usr/lib64/dovecot
Value	string
See Also	mail_plugins

The directory in which to search for Dovecot mail plugins.

mail_plugins

Default	[None]
Value	string
See Also	mail_plugin_dir variable expansion

A space-separated list of plugins to load.

mail_prefetch_count

Default	0
Value	unsigned integer

The number of messages to try to prefetch whenever possible. 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.

For imapc, a good value is likely between 10..100.

0 means that no prefetching is done.

mail_privileged_group

Default	[None]
Value	string

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]
Value	string
See Also	imap_metadata

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]
Value	string
See Also	imap_metadata

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

Default	no
Value	boolean

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

mail_sort_max_read_count

Default	[None]
Value	unsigned 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	/tmp
Value	string

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

Default	1week
Value	time

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

Default	[None]
Value	stringunsigned integer
See Also	mail_gid

This setting indicates the system userid used for accessing mail messages. If you use multiple values here, userdb can override them by returning UID or GID fields. You can use either numeric IDs or usernames here.

mail_vsize_bg_after_count

Default	[None]
Value	unsigned integer
See Also	quota plugin

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_list_index

Default	yes
Value	boolean

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

Default	no
Value	boolean
See Also	mailbox_list_index

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_very_dirty_syncs

Default	no
Value	boolean

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

maildir_broken_filename_sizes

Default	no
Value	boolean
See Also	Maildir

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.

maildir_copy_with_hardlinks

Default	yes
Value	boolean
See Also	Maildir

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

Default	no
Value	boolean
See Also	Maildir

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

maildir_stat_dirs

Default	no
Value	boolean
See Also	Maildir

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

Default	no
Value	boolean
See Also	Maildir

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

Default	bytes=%i/%o
Value	string

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

Variable	Substitution
%i	Total number of bytes read from client.
%o	Total number of bytes sent to client.

master_user

Default	[None]
Value	string
See Also	acl_user
Plugin	acl plugin

TODO

mbox_dirty_syncs

Default	yes
Value	boolean
See Also	mbox_very_dirty_syncs mbox

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

Default	2 mins
Value	time
See Also	mbox

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

Default	yes
Value	boolean
See Also	mbox

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

Default	5 mins
Value	time
See Also	mbox

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

mbox_read_locks

Default	fcntl
Value	string
Allowed Values	dotlockdotlock_tryfcntlflocklockf
See Also	mbox

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

To use multiple values, separate them with spaces.

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

mbox_very_dirty_syncs

Default	no
Value	boolean
See Also	mbox_dirty_syncs mbox

If enabled, Dovecot performs the optimizations from mbox_dirty_syncs also for the IMAP SELECT, EXAMINE, EXPUNGE, and CHECK commands.

If set, this option overrides mbox_dirty_syncs.

mbox_write_locks

Default	dotlock fcntl
Value	string
Allowed Values	dotlockdotlock_tryfcntlflocklockf
See Also	mbox

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

To use multiple values, separate them with spaces.

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

mdbox_preallocate_space

Default	no
Value	boolean
See Also	mdbox_rotate_size mdbox

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]
Value	size
See Also	mdbox

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

Default	10M
Value	size
See Also	mdbox

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

message_hashing

Default	hash_method=md5 min_atc_size=1
Value	string
Plugin	message-hashing plugin

A string of space-separated key=value configuration options.

Supported options:

Key	Default	Type	Description
hash_method	md5	string	The hashing method to use. Must be a recognized Dovecot hashing method (see auth_policy_hash_mech for list of supported methods) or else the plugin will log a warning and be disabled.
min_atc_size	1	unsigned integer	The minimum size of an attachment (in bytes) to be processed; attachments smaller than this will be skipped.

metacache_close_delay

Default	2secs
Value	time
Plugin	obox 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

Default	8 hours
Value	time
Plugin	obox 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_last_host_dict

Default	[None]
Value	string
Plugin	obox plugin

If this setting is configured to a valid Dictionary URI, obox looks up metacache_last_host key from dict. This is meant to be used with Palomar.

The metacache_last_host value is kept in Palomar GeoDB.

If the lookup is successful and metacache_last_host is different from the current host (cluster_backend_name), metacache is pulled from the metacache_last_host backend. Obox also updates metacache_last_host to the given dict.

metacache_max_grace

Default	1G
Value	time
Plugin	obox plugin

How much disk space on top of metacache_max_space can be used before Dovecot stops allowing more users to login.

metacache_max_space

Default	[None]
Value	size
Plugin	obox 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_upload_interval

Default	5min
Value	time
Plugin	obox 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.

mmap_disable

Default	no
Value	boolean

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

namespace

Default	[None]
Value	string

Name of the namespace.

Giving name is optional, but doing so enables referencing the configuration later on.

Example, to name a namespace foo:

namespace foo {
  [...]
}

namespace/alias_for

Default	[None]
Value	string

Defines the namespace prefix for purposes of alias detection.

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 {
  # If primary namespace has empty prefix
  alias_for =

  # OR if primary namespace has 'prefix=INBOX/'
  alias_for=INBOX/
}

namespace/disabled

Default	no
Value	boolean

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

Default	no
Value	boolean

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

namespace/ignore_on_failure

Default	no
Value	boolean

If namespace namespace/location fails to load, by default the entire session will fail to start. If this is set, this namespace will be ignored instead.

namespace/inbox

Default	no
Value	boolean

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

There can be only one namespace defined like this.

namespace/list

Default	yes
Value	string
Allowed Values	yesnochildren
See Also	namespace/hidden

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/location

Default	mail_location
Value	string

Specifies driver and parameters for physical mailbox storage. It allows an override of the mail_location setting for a namespace.

Mail user variables can be used.

Example:

namespace {
  location = sdbox:/archive/%u
}

namespace/mailbox/auto

Default	no
Value	string
Allowed Values	createnosubscribe

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.

namespace/mailbox/autoexpunge

Default	no
Value	time
See Also	namespace/mailbox/autoexpunge_max_mails

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.

namespace/mailbox/autoexpunge_max_mails

Default	[None]
Value	unsigned integer

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

Once this threshold has been reached, namespace/mailbox/autoexpunge processing is done.

namespace/mailbox/special_use

Default	[None]
Value	string
Changes	Changed: 3.0.0 Using non-standard special-use flags will result in a warning message at startup.

Space-separated 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.

namespace/order

Default	[None]
Value	unsigned integer

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

Namespaces are automatically numbered if this setting does not exist.

namespace/prefix

Default	[None]
Value	string

Specifies prefix for namespace.

Note: Must end with namespace/separator.

Mail user variables can be used.

Example:

namespace {
  prefix = Shared/
  separator = /
}

namespace/separator

Default	"." for Maildir; "/" for other mbox formats
Value	string
See Also	namespace hierarchy separators

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

Default	yes
Value	boolean

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

Default	private
Value	string
Allowed Values	privatesharedpublic

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.

nfs_hostchange_migration

Default	no
Value	boolean
Plugin	nfs-hostchange plugin

When enabled, assume user is being migrated.

notify_status_dict

Default	[None]
Value	string
Plugin	notify-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.

plugin {
  notify_status_dict = proxy:dict-async:notify_status
}

notify_status_mailbox

Default	[None]
Value	string
Plugin	notify-status plugin

A mailbox pattern to enable for status updates. Wildcards are acceptable.

By default, all mailboxes are processed. When defining one or more patterns only mailboxes matching the pattern are enabled for status updates.

You can define multiple mailbox patterns by appending an increasing number to the setting label.

Example:

plugin {
  notify_status_mailbox = Spam
  notify_status_mailbox2 = Archive/*
}

notify_status_value

Default	{"messages":%%{messages},"unseen":%%{unseen}}
Value	string
Plugin	notify-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)

obox_fs

Default	[None]
Value	string
Plugin	obox plugin

This setting handles the basic Object Storage configuration.

INFO

See the storage provider pages for specific parameters that can be used.

obox_index_fs

Default	obox_fs
Value	string
Plugin	obox plugin

This setting handles the object storage configuration for index bundles.

obox_max_parallel_copies

Default	mail_prefetch_count
Value	unsigned integer
Plugin	obox 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

Default	mail_prefetch_count
Value	unsigned integer
Plugin	obox 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.

obox_max_parallel_writes

Default	mail_prefetch_count
Value	unsigned integer
Plugin	obox plugin

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

obox_refresh_index_once_after

Default	[None]
Value	unsigned integer
Plugin	obox 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.

obox_rescan_mails_once_after

Default	[None]
Value	unsigned integer
Plugin	obox 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.

obox_track_copy_flags

Default	no
Value	boolean
Plugin	obox plugin

Try to avoid Cassandra SELECTs when expunging mails.

Enable only if dictmap/Cassandra and lazy-expunge plugin are used.

pop3_client_workarounds

Default	[None]
Value	string

Workarounds for various POP3 client bugs can be enabled here. The list is space-separated.

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

Default	default
Value	string
Allowed Values	defaultflagexpunge

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

pop3_deleted_flag

Default	[None]
Value	string
See Also	pop3_delete_type

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.

Note

This keyword will visible on IMAP clients for the message.

Example:

pop3_deleted_flag = $POP3Deleted

pop3_enable_last

Default	no
Value	boolean

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

Default	no
Value	boolean

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

Default	no
Value	boolean

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

pop3_logout_format

Default	top=%t/%p retr=%r/%b del=%d/%m size=%s
Value	string

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

Variables available (in addition to Mail user variables):

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

pop3_migration_all_mailboxes

Default	no
Value	boolean
Plugin	pop3-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

Default	no
Value	boolean
Plugin	pop3-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

Default	no
Value	boolean
Plugin	pop3-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

Default	no
Value	string
Plugin	pop3-migration plugin

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

plugin {
  pop3_migration_mailbox = POP3-MIGRATION-NS/INBOX
}

pop3_migration_skip_size_check

Default	no
Value	boolean
Plugin	pop3-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

Default	no
Value	boolean
Plugin	pop3-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

Default	no
Value	boolean

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

pop3_reuse_xuidl

Default	no
Value	boolean

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

pop3_save_uidl

Default	no
Value	boolean

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

Default	allow
Value	string
Allowed Values	allowrename

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	%08Xu%08Xv
Value	string

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

The following variables can be used in combination with the standard variable modifiers (e.g., %Uf supplies the filename in uppercase) and with Global variables:

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

pop3_uidl_migrate_format

Default	[None]
Value	string
Plugin	pop3-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]
Value	string

A space-separated 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]
Value	string

The remote POP3 host to connect to.

pop3c_master_user

Default	[None]
Value	string
See Also	pop3c_password pop3c_user

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 = %u
pop3c_master_user = masteruser
pop3c_password = masteruser-secret

Mail user variables can be used.

pop3c_password

Default	[None]
Value	string
See Also	pop3c_master_user pop3c_user

The authentication password for the remote POP3 server.

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

pop3c_port

Default	110
Value	unsigned integer

The port on the remote POP3 host to connect to.

pop3c_quick_received_date

Default	no
Value	boolean

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

pop3c_rawlog_dir

Default	[None]
Value	string
See Also	rawlog

Log all POP3 traffic input/output to this directory.

pop3c_ssl

Default	no
Value	string
Allowed Values	nopop3sstarttls

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

Default	yes
Value	boolean
See Also	pop3c_ssl

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.

pop3c_user

Default	%u
Value	string
See Also	pop3c_master_user pop3c_password

The user identity to be used for performing authentication to the source POP3 server.

Mail user variables can be used.

postmaster_address

Default	postmaster@%{if;%d;ne;;%d;%{hostname}}
Value	string

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

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

process_shutdown_filter

Default	[None]
Value	string

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 > 10M"

protocols

Default	imap pop3 lmtp
Value	string

The list of protocols this node will support.

It takes a space-separated list of protocols (which are configured separately) as its value.

push_notification_driver

Default	[None]
Value	string
Plugin	push-notification plugin

The configuration value is the name of the driver, optionally followed by an : and driver-specific options (see Push Notifications for the list of drivers and options supported).

It is possible to specify multiple push notification drivers by adding a sequential number to the push_notification_driver label, starting with the number 2. There can be no numbering gaps for the labels; only the drivers that appear in sequential order will be processed.

quota

Default	[None]
Value	string
See Also	quota root
Plugin	quota plugin

Quota root configuration has the following syntax:

quota = <backend>[:<quota root name>[:<backend args>]]

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. By default, an empty string is used, but you may want to change that since some clients (Apple Mail) break and don't show quota at all then.

You can define multiple quota roots by appending an increasing number to the setting label:

plugin {
  quota = maildir:User quota
  quota2 = fs:Disk quota
  #quota3 = ...
}

Globally available arguments for <backend args> parameter:

Name	Description
noenforcing	Don't try to enforce quotas by calculating if saving would get user over quota. Only handle write failures.
ns=<prefix>	A separate namespace-specific quota that's shared between all users.

If you want to specify multiple backend arguments, separate them with ':' (e.g. noenforcing:ns=Public/:foo:bar).

quota_clone_dict

Default	[None]
Value	string
Plugin	quota-clone plugin

The dictionary to update with quota clone information. This must be set for the plugin to be active.

See dictionary for dictionary configuration.

plugin {
  quota_clone_dict = redis:host=127.0.0.1:port=6379
}

quota_exceeded_message

Default	[None]
Value	string
Plugin	quota plugin

The message specified here is passed on to a user who goes over quota.

The value is either the message or the path to a file (prefixed with a <) that will be used as the message data.

plugin {
  quota_exceeded_message = Quota exceeded.

  # Read message from a file
  #quota_exceeded_message = </path/to/quota_exceeded_message.txt
}

quota_full_tempfail

Default	no
Value	boolean
See Also	quota plugin

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_grace

Default	10%%
Value	stringsize
See Also	quota root
Plugin	quota plugin

If set, allows message deliveries to exceed quota by this value.

quota_mailbox_count

Default	0
Value	unsigned integer
See Also	quota maximum mailbox count
Plugin	quota 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.

0 means unlimited.

quota_mailbox_message_count

Default	0
Value	unsigned integer
Plugin	quota plugin
Changes	Added: 3.0.0

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

0 means unlimited.

quota_max_mail_size

Default	0
Value	unsigned integer
See Also	quota maximum saved mail size
Plugin	quota plugin

The maximum message size that is allowed to be saved (e.g. by LMTP, IMAP APPEND or doveadm save).

0 means unlimited.

quota_over_flag

Default	10%%
Value	string
See Also	quota overquota flag
Plugin	quota plugin

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

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

Usually, this value will be loaded via userdb.

quota_over_flag_lazy_check

Default	no
Value	boolean
Plugin	quota plugin

If enabled, overquota-flag is checked only when current quota usage is going to already be checked.

Can be used to optimize the overquota-flag check in case it is running too slowly.

quota_over_flag_value

Default	[None]
Value	string
See Also	quota overquota flag
Plugin	quota plugin

The search string to match against quota_over_flag to determine if the overquota-flag is set for the user.

Wildcards can be used in a generic way, e.g. *yes or *TRUE*.

quota_over_script

Default	[None]
Value	string
Plugin	quota plugin

The service script to execute if overquota-flag is wrong. Configured the same as quota_warning scripts.

The current quota_over_flag value is appended as the last parameter.

plugin {
  quota_over_script = quota-warning mismatch %u
}

quota_rule

Default	[None]
Value	string
See Also	quota root
Plugin	quota plugin

Quota rule configuration has the following syntax:

quota_rule = <mailbox name>:<limit configuration>

You can define multiple quota rules by appending an increasing number to the setting label.

* as the mailbox name configures the default limit, which is applied on top of a mailbox-specific limit if found.

? as the mailbox name works almost like *. The difference is that ? is used only if quota backend doesn't override the limit.

* and ? wildcards can be used as a generic wildcard in mailbox names, so for example box* matches boxes.

The following limit names are supported:

Name	Description
backend	Quota backend-specific limit configuration.
bytes	Quota limit (without suffix: in bytes). 0 means unlimited.
ignore	Don't include the specified mailbox in quota at all.
messages	Quota limit in number of messages. 0 means unlimited.
storage	Quota limit (without suffix: in kilobytes). 0 means unlimited.

Settings with a limit value support the size syntax as a suffix.

Settings also support % as a suffix. Percents are relative to the default rule. For example:

plugin {
  quota = maildir:User quota
  quota_rule = *:storage=1GB
  # 10% of 1GB = 100MB
  quota_rule2 = Trash:storage=+10%%
  # 20% of 1GB = 200MB
  quota_rule3 = Spam:storage=+20%%
}

Note that % is written twice to escape it, because Config variables are expanded in plugin section.

userdb configuration may or may not require this escaping.

Backend-specific configuration currently is used only with Maildir++ quota backend. It means you can have the quota in Maildir++ format (e.g. 10000000S).

quota_timestamp

Default	[None]
Value	string
Plugin	quota-timestamp plugin

Connection string for the Redis service.

This string MUST begin with redis:.

quota_timestamp_prefix

Default	[None]
Value	string
Plugin	quota-timestamp plugin

A prefix to add to the key string when storing in Redis.

quota_timestamp_set_interval

Default	15min
Value	time
Plugin	quota-timestamp plugin

The interval between Redis updates for a user.

quota_timestamp_value_prefix

Default	[None]
Value	string
Plugin	quota-timestamp plugin

A prefix to add to the value string when storing in Redis.

quota_warning

Default	[None]
Value	string
See Also	quota warning scripts
Plugin	quota plugin

You can configure Dovecot to run an external command when user's quota exceeds a specified limit. Note that the warning is ONLY executed at the exact time when the limit is being crossed, so when you're testing you have to do it by crossing the limit by saving a new mail. If something else besides Dovecot updates quota so that the limit is crossed, the warning is never executed.

Quota warning configuration has the following syntax:

quota_warning = <limit configuration> <quota-warning socket name> <parameters>

limit_configuration is almost exactly same as for quota, with the exception of adding - before the value for "reverse" warnings where the script is called when quota drops below the value. Usually you want to use percents instead of absolute limits.

Only the command for the first exceeded limit is executed, so configure the highest limit first. The actual commands that are run need to be created as services (create a named Dovecot service and use the service name as the quota-warning socket name argument).

Note: The percent sign (%) needs to be written as %% to avoid config expansion (see Config variables).

You can define multiple quota rules by appending an increasing number to the setting label.

rawlog_dir

Default	[None]
Value	string
See Also	rawlog

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/%u
  # if you want to put files into user's homedir, use this, do not use ~
  #rawlog_dir = %h/rawlog
}

recipient_delimiter

Default	+
Value	string

The separator between the :user and :detail address parts.

rejection_reason

Default	Your message to <%t> was automatically rejected:%n%r
Value	string

A human-readable message for the recipients of bounce messages.

The following variables are allowed, including Global variables:

Variable Name	Description
%{crlf}, %n	Newline (CRLF)
%{reason}, %r	Reason for rejection
%{subject}, %s	Original subject line
%{to}, %t	Recipient address

The variable values are obtained from the mail being delivered or the delivery protocol.

rejection_subject

Default	Rejected: %s
Value	string
See Also	rejection_reason

The Subject: header to use for bounce messages.

See rejection_reason for the list of variables that can be used.

sendmail_path

Default	/usr/sbin/sendmail
Value	string

The binary to use for sending email.

Used only if submission_host is not set.

shutdown_clients

Default	yes
Value	boolean

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

Default	file:~/sieve;active=~/.dovecot.sieve
Value	string
See Also	Sieve script locations
Plugin	sieve plugin

The location of the user's main Sieve script or script storage.

The LDA Sieve plugin uses this to find the active script for Sieve filtering at delivery.

The Sieve include extension uses this location for retrieving :personal scripts.

This location is also where the ManageSieve service will store the user's scripts, if supported by the location type.

For the file location type, the location will then be the path to the storage directory for all the user's personal Sieve scripts.

ManageSieve maintains a symbolic link pointing to the currently active script (the script executed at delivery). The location of this symbolic link can be configured using the ;active=<path> option.

sieve_<extension>_bin_dir

Default	[None]
Value	string
Plugin	sieve-extprograms plugin

Points to a directory where the plugin looks for programs (shell scripts) to execute directly and pipe messages to.

"<extension>" in the setting name is replaced by either pipe, filter or execute depending on which extension is being configured.

sieve_<extension>_exec_timeout

Default	10s
Value	time
Plugin	sieve-extprograms plugin

Configures the maximum execution time after which the program is forcibly terminated.

"<extension>" in the setting name is replaced by either pipe, filter or execute depending on which extension is being configured.

sieve_<extension>_input_eol

Default	crlf
Value	string
Allowed Values	crlflf
Plugin	sieve-extprograms plugin

Determines the end-of-line character sequence used for the data piped to external programs. 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.

"<extension>" in the setting name is replaced by either pipe, filter or execute depending on which extension is being configured.

sieve_<extension>_socket_dir

Default	[None]
Value	string
Plugin	sieve-extprograms plugin

Points to a directory relative to the base_dir where the plugin looks for script service sockets.

"<extension>" in the setting name is replaced by either pipe, filter or execute depending on which extension is being configured.

sieve_after

Default	[None]
Value	string
Plugin	sieve plugin

This setting can be specified multiple times by adding a number after the setting name, such as sieve_after2 and so on.

Location of scripts that need to be executed after the user's personal script.

If a Sieve file storage location location path points to a directory, all the Sieve scripts contained therein (with the proper .sieve extension) are executed. The order of execution within that directory is determined by the file names, using a normal 8bit per-character comparison.

Multiple script locations can be specified by appending an increasing number to the setting name.

The Sieve scripts found from these locations are added to the script execution sequence in the specified order.

Reading the numbered sieve_before settings stops at the first missing setting, so no numbers may be skipped.

sieve_before

Default	[None]
Value	string
See Also	sieve_after
Plugin	sieve plugin

This setting can be specified multiple times by adding a number after the setting name, such as sieve_before2 and so on.

See sieve_after for configuration details, as this setting behaves the same way, except the scripts are run before user's personal scripts (instead of after).

sieve_default

Default	[None]
Value	string
Plugin	sieve plugin

Location of the default personal sieve script file which gets executed ONLY if user's private Sieve script does not exist, e.g. file:/var/lib/dovecot/default.sieve (check the multiscript section for instructions on running global Sieve scripts before and after the user's personal script).

This is usually a global script, so be sure to pre-compile the specified script manually in that case using the sievec command line tool, as explained by sievec(1).

sieve_default_name

Default	[None]
Value	string
See Also	Sieve visible default script
Plugin	sieve plugin

The name by which the default Sieve script is visible to ManageSieve clients. Normally, it is not visible at all.

sieve_discard

Default	[None]
Value	string
Plugin	sieve plugin

The location of a Sieve script that is run for any message that is about to be discarded; i.e., it is not delivered anywhere by the normal Sieve execution.

This only happens when the "implicit keep" is canceled, by e.g. the "discard" action, and no actions that deliver the message are executed.

This "discard script" can prevent discarding the message, by executing alternative actions.

If the discard script does nothing, the message is still discarded as it would be when no discard script is configured.

sieve_editheader_forbid_add

Default	[None]
Value	string
See Also	Sieve editheader extension
Plugin	sieve 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_forbid_delete

Default	[None]
Value	string
See Also	Sieve editheader extension
Plugin	sieve 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

Default	2048
Value	unsigned integer
See Also	Sieve editheader extension
Plugin	sieve 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_editheader_protected

Default	[None]
Value	string
See Also	Sieve editheader extension
Plugin	sieve plugin

A space-separated list of headers that cannot be added to or deleted from the message header.

This setting is provided for backwards compatibility.

It is a combination of the sieve_editheader_forbid_add and sieve_editheader_forbid_delete settings. The same limitations apply.

sieve_extensions

Default	<see description>
Value	string
Plugin	sieve 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.

This setting can use + and - to specify differences relative to the default.

Example:

# Enable the deprecated imapflags extension in addition to all
# extensions enabled by default.
plugin {
	sieve_extensions = +imapflags
}

sieve_global

Default	[None]
Value	string
Plugin	sieve plugin

Location for :global include scripts for the Sieve include extension.

sieve_global_extensions

Default	sieve_extensions
Value	string
Plugin	sieve 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 similar 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]
Value	string
Plugin	sieve 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

Default	32
Value	unsigned integer
Plugin	sieve 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

Default	30s
Value	time
Plugin	sieve 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

Default	4
Value	unsigned integer
Plugin	sieve plugin

The maximum number of redirect actions that can be performed during a single script execution.

0 means redirect is prohibited.

sieve_notify_mailto_envelope_from

Default	[None]
Value	string
See Also	sieve_redirect_envelope_from Sieve notifications extensions
Plugin	sieve plugin

Defines the source of the notification sender address for e-mail notifications.

sieve_plugins

Default	[None]
Value	string
Plugin	sieve plugin

The Pigeonhole Sieve interpreter can have plugins of its own.

Using this setting, the used plugins can be specified. Plugin names should be space-separated in the setting.

Check Sieve plugins for available plugins.

sieve_quota_max_scripts

Default	[None]
Value	unsigned integer
Plugin	sieve plugin

The maximum number of personal Sieve scripts a single user can have.

Default is 0, which is unlimited.

sieve_quota_max_storage

Default	[None]
Value	unsigned integer
Plugin	sieve plugin

The maximum amount of disk storage a single user's scripts may occupy.

Default is 0, which is unlimited.

sieve_redirect_envelope_from

Default	sender
Value	string
Plugin	sieve 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

Default	1h
Value	time
Plugin	sieve 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_spamtest_max_header

Default	10
Value	string
See Also	Sieve spamtest extension
Plugin	sieve 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_max_value.

The syntax is identical to the sieve_spamtest_status_header setting.

sieve_spamtest_max_value

Default	[None]
Value	unsigned integer
See Also	Sieve spamtest extension
Plugin	sieve plugin

This statically specifies the maximum value a numeric spam score can have.

sieve_spamtest_status_header

Default	[None]
Value	string
See Also	Sieve spamtest extension
Plugin	sieve 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]
Value	string
Allowed Values	scorestrlentext
See Also	Sieve spamtest extension
Plugin	sieve 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'.

sieve_spamtest_text_value<X>

Default	[None]
Value	string
See Also	Sieve spamtest extension
Plugin	sieve plugin

When the sieve_spamtest_status_type setting is set to text, these settings specify that the spamtest test will match against the value <X> when the specified string is equal to the text (extracted) from the status header.

For spamtest and spamtestplus, values of X between 0 and 10 are recognized, while virustest only uses values between 0 and 5.

sieve_trace_addresses

Default	no
Value	boolean
See Also	Sieve trace debugging
Plugin	sieve plugin

Enables showing byte code addresses in the trace output, rather than only the source line numbers.

sieve_trace_debug

Default	no
Value	boolean
See Also	Sieve trace debugging
Plugin	sieve plugin

Enables highly verbose debugging messages that are usually only useful for developers.

sieve_trace_dir

Default	[None]
Value	string
See Also	Sieve trace debugging
Plugin	sieve 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]
Value	string
See Also	Sieve trace debugging
Plugin	sieve 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]
Value	string
Plugin	sieve 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

Default	[None]
Value	string
Plugin	sieve plugin

The path to the file where the user log file is written. a default location is used.

If the main user's personal Sieve (as configured with sieve is a file, the logfile is set to <filename>.log by default.

If it is not a file, the default user log file is ~/.dovecot.sieve.log.

sieve_vacation_default_period

Default	7d
Value	time
See Also	Sieve vacation extension
Plugin	sieve plugin

Specifies the default period that is used when no :days or :seconds tag is specified.

The configured value must lie between sieve_vacation_min_period and sieve_vacation_max_period.

sieve_vacation_dont_check_recipient

Default	no
Value	boolean
See Also	Sieve vacation extension
Plugin	sieve plugin

This disables the checks for implicit delivery entirely. This means that the vacation command does not verify that the message is explicitly addressed at the recipient.

Use this option with caution. Specifying yes 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

Default	[None]
Value	time
See Also	Sieve vacation extension
Plugin	sieve 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

Default	1d
Value	time
See Also	Sieve vacation extension
Plugin	sieve 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_receipt

Default	no
Value	boolean
See Also	Sieve vacation extension
Plugin	sieve 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

Default	no
Value	boolean
See Also	Sieve vacation extension
Plugin	sieve 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_max_header

Default	[None]
Value	string
See Also	Sieve virustest extension
Plugin	sieve 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_max_value.

The syntax is identical to sieve_virustest_status_header.

sieve_virustest_max_value

Default	[None]
Value	unsigned integer
See Also	Sieve virustest extension
Plugin	sieve plugin

This statically specifies the maximum value a numeric spam score can have.

sieve_virustest_status_header

Default	[None]
Value	string
See Also	Sieve virustest extension
Plugin	sieve 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]
Value	string
Allowed Values	scorestrlentext
See Also	Sieve virustest extension
Plugin	sieve 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'.

sieve_virustest_text_value<X>

Default	[None]
Value	string
See Also	Sieve virustest extension
Plugin	sieve plugin

When the sieve_virustest_status_type setting is set to text, these settings specify that the spamtest test will match against the value <X> when the specified string is equal to the text (extracted) from the status header.

For spamtest and spamtestplus, values of X between 0 and 10 are recognized, while virustest only uses values between 0 and 5.

sieve_zimbra_addressbook_dict

Default	[None]
Value	string
Plugin	sieve-zimbra-compat plugin

The URI 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]
Value	string
Plugin	sieve-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_as_redirect

Default	no
Value	boolean
Plugin	sieve-zimbra-compat plugin

If enabled, executes the "vnd.zimbra.notify" action as a "redirect" action.

sieve_zimbra_notify_envelope_from

Default	sieve_notify_mailto_envelope_from or postmaster
Value	string
Plugin	sieve-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.

ssl

Default	yes
Value	string
Allowed Values	yesnorequired
See Also	SSL configuration

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_alt_cert

Default	[None]
Value	string
See Also	ssl SSL configuration

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_alt_cert = </path/to/alternative/cert.pem

ssl_alt_key

Default	[None]
Value	string
See Also	ssl ssl_alt_cert SSL configuration

Private key for ssl_alt_cert.

Example:

ssl_alt_key = </path/to/alternative/key.pem
ssl_alt_cert = </path/to/alternative/cert.pem

ssl_ca

Default	[None]
Value	string
See Also	ssl ssl_client_require_valid_cert ssl_verify_client_cert

List of SSL CA certificates that are used to validate whether SSL certificates presented by incoming imap/pop3/etc. client connections are valid.

These CAs are also used by some processes for validating outgoing SSL connections in addition to ssl_client_ca_file and ssl_client_ca_dir. This is mainly important for imap-login, pop3-login, etc. processes which are chrooted and can't access the CA files outside the chroot.

Note that mail processes (imap, pop3, etc.) don't read this setting to save memory, because the CAs can be large and there can be many mail processes.

Example:

ssl_ca = </etc/dovecot/ca.crt
ssl_verify_client_cert = yes
auth_ssl_require_client_cert = yes

ssl_cert

Default	</etc/ssl/certs/dovecot.pem
Value	string
See Also	ssl ssl_key SSL configuration

The PEM-encoded X.509 SSL/TLS certificate presented for incoming imap/pop3/etc. client connections.

The ssl_key is also needed for the private certificate.

Example:

ssl_cert = </etc/ssl/private/dovecot.crt
ssl_key = </etc/ssl/private/dovecot.key

ssl_cert_username_field

Default	commonName
Value	string
See Also	ssl SSL configuration

Field name in the SSL client certificate that is used for auth_ssl_username_from_cert.

The most common choices are commonName and x500UniqueIdentifier.

Note: auth_ssl_username_from_cert MUST be enabled.

ssl_cipher_list

Default	ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@STRENGTH
Value	string
See Also	ssl ssl_cipher_suites ssl_min_protocol SSL configuration

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_cipher_suites

Default	<OpenSSL version specific>
Value	string
See Also	ssl ssl_cipher_list SSL configuration

The list of SSL cipher suites to use for TLSv1.3 connections, in order of preference. Use ssl_cipher_list for TLSv1.2 and below connections.

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

See: https://wiki.openssl.org/index.php/TLS1.3#Ciphersuites

ssl_client_ca_dir

Default	[None]
Value	string
See Also	ssl SSL configuration

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 backend).

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]
Value	string
See Also	ssl SSL configuration

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 backend).

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

Default	[None]
Value	string
See Also	ssl ssl_client_key SSL configuration

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 is also needed for the private certificate.

Example:

ssl_client_cert = </etc/dovecot/dovecot-client.crt
ssl_client_key = </etc/dovecot/dovecot-client.key

ssl_client_key

Default	[None]
Value	string
See Also	ssl ssl_client_cert SSL configuration

Private key for ssl_client_cert.

Example:

ssl_client_cert = </etc/dovecot/dovecot-client.crt
ssl_client_key = </etc/dovecot/dovecot-client.key

ssl_client_require_valid_cert

Default	yes
Value	boolean
See Also	ssl SSL configuration

Require a valid certificate when connecting to external SSL services?

ssl_crypto_device

Default	[None]
Value	string
See Also	ssl SSL configuration

Available Values: <Obtain by running openssl engine command>

Which SSL crypto device to use.

ssl_curve_list

Default	<defaults from the SSL library>
Value	string
See Also	ssl SSL configuration

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_dh

Default	[None]
Value	string
See Also	ssl SSL configuration

The path to the Diffie-Hellman parameters file must be provided. 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_dh=</path/to/dh.pem

ssl_key

Default	[None]
Value	string
See Also	ssl ssl_cert ssl_key_password SSL configuration

The PEM-encoded X.509 SSL/TLS private key for ssl_cert.

Example:

ssl_cert = </etc/ssl/private/dovecot.crt
ssl_key = </etc/ssl/private/dovecot.key

ssl_key_password

Default	[None]
Value	string
See Also	ssl ssl_key SSL configuration

The password to use if ssl_key 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_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_min_protocol

Default	TLSv1.2
Value	string
See Also	ssl ssl_cipher_list SSL configuration

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]
Value	string
Allowed Values	compressionno_ticket
See Also	ssl SSL configuration

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_prefer_server_ciphers

Default	no
Value	boolean
See Also	ssl SSL configuration

If enabled, give preference to the server's cipher list over a client's list. This setting is used only for server connections.

ssl_require_crl

Default	yes
Value	boolean
See Also	ssl ssl_ca SSL configuration

If enabled, the CRL check must succeed for presented SSL client certificate and any intermediate certificates. The CRL list is generally appended to the ssl_ca file.

This setting is used only for server connections.

ssl_verify_client_cert

Default	no
Value	boolean
See Also	ssl auth_ssl_require_client_cert SSL configuration

If enabled, the imap/pop3/etc. client is requested to send an SSL certificate.

Note: This setting doesn't yet require the certificate to be valid or to even exist. See auth_ssl_require_client_cert.

stats_writer_socket_path

Default	stats-writer
Value	string

The path to the stats-writer socket.

submission_add_received_header

Default	yes
Value	boolean
Changes	Added: 3.0.0

Controls if "Received:" header should be added to mails by the submission backend.

submission_client_workarounds

Default	[None]
Value	string

Configures the list of active workarounds for Submission client bugs. The list is space-separated.

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]
Value	URL

Use this SMTP submission host to send messages.

Overrides sendmail_path value, if set.

submission_logout_format

Default	in=%i out=%o
Value	string

The SMTP Submission logout format string.

Variables supported, including Mail user variables:

Variable Name	Description
%{input}, %i	Bytes read from client
%{output}, %o	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

Default	40M
Value	size

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]
Value	unsigned integer

Maximum number of recipients accepted per connection.

0 means unlimited.

submission_relay_command_timeout

Default	5mins
Value	time (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

Default	30secs
Value	time (milliseconds)

Timeout for connecting to and logging into the submission service's relay server.

submission_relay_host

Default	[None]
Value	string

Host of the relay server (REQUIRED to provide the submission service).

submission_relay_master_user

Default	[None]
Value	string

Master user name for authentication to the relay MTA if authentication is required.

submission_relay_max_idle_time

Default	29mins
Value	time

Submission relay max idle time for connection to relay MTA.

submission_relay_password

Default	[None]
Value	string

Password for authentication to the relay MTA if authentication is required.

submission_relay_port

Default	25
Value	unsigned integer

Value Range: <1-65535>

Port for the submission relay server.

submission_relay_rawlog_dir

Default	[None]
Value	string
See Also	rawlog

Write protocol logs for relay connection to this directory for debugging.

Mail user variables can be used.

submission_relay_ssl

Default	no
Value	string
Allowed Values	nosmtpsstarttls

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

Default	yes
Value	boolean

If enabled, TLS certificate of the relay server must be verified.

submission_relay_trusted

Default	no
Value	boolean

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]
Value	string

User name for authentication to the relay MTA if authentication is required.

submission_ssl

Default	no
Value	string
Allowed Values	nosmtpsstarttls
See Also	submission_host

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

Default	30secs
Value	time
See Also	submission_host

Timeout for submitting outgoing messages.

syslog_facility

Default	mail
Value	string

The syslog facility used if you're logging to syslog.

trash

Default	[None]
Value	string
Plugin	trash plugin

A text file that configures the plugin's behavior. This setting is required for the plugin to be active.

trash = /etc/dovecot/dovecot-trash.conf.External

The file uses the following format:

<priority> <mailbox name>

Deletion begins with the mailbox that has the lowest priority number and proceeds from there.

valid_chroot_dirs

Default	[None]
Value	string

A colon-separated 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]
Value	string
Plugin	vault plugin

This setting enables the vault plugin and identifies where to store a copy of the message.

verbose_proctitle

Default	no
Value	boolean

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.

verbose_ssl

Default	no
Value	boolean

If enabled, protocol-level SSL errors are logged.

version_ignore

Default	no
Value	boolean

If enabled, ignore version mismatches between different Dovecot versions.

welcome_script

Default	[None]
Value	string
Plugin	welcome plugin

The script to run when the user logs in for the first time (that is, when this user's INBOX is created). This must be set or else the plugin will not be active.

plugin {
  welcome_script = welcome %u
}

welcome_wait

Default	no
Value	boolean
Plugin	welcome plugin

If enabled, wait for the script to finish. By default, the welcome script is run asynchronously.

Advanced Settings

NOTE

These settings should not normally be changed.

auth_gssapi_hostname

Default	<name returned by gethostname()>
Value	string
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)>
Value	string
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_policy_hash_truncate

Default	12
Value	unsigned integer
See Also	auth_policy_server_url
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]
Value	string
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_use_winbind

Default	no
Value	boolean
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]
Value	string
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]
Value	string
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/
Value	string
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.

dsync_hashed_headers

Default	Date Message-ID
Value	string
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.

fts_dovecot_mail_flush_interval

Default	10
Value	unsigned integer
Plugin	fts-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

Default	200
Value	unsigned integer
Plugin	fts-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

Default	128 kB
Value	size
Plugin	fts-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.

imap_idle_notify_interval

Default	2mins
Value	time
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

Default	64k
Value	size
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_max_client_idle_time_msecs

Default	20000
Value	unsigned integer
Advanced Setting; this should not normally be changed.

The maximum client idle time for the intercept-api service.

If the client idles longer than this, the connection is closed.

intercept_api_rawlog_dir

Default	[None]
Value	string
Advanced Setting; this should not normally be changed.

If this directory exists, and it is writable by the intercept-api service, the messages exchanged between client and server are logged here. This is useful for debugging.

intercept_api_utimaco_sql_query_surveillance

Default	SELECT uuid, UNIX_TIMESTAMP(created) AS created FROM targets WHERE userid_hash = '%Mu'
Value	string
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_proxy_path

Default	[None]
Value	string
Advanced Setting; this should not normally be changed.

Unix socket for connecting to intercept-proxy process.

intercept_utimaco_x1_max_client_idle_time_msecs

Default	20000
Value	unsigned integer
Advanced Setting; this should not normally be changed.

The maximum client idle time for the utimaco-x1 service.

If the client idles longer than this, the connection is closed.

intercept_utimaco_x1_rawlog_dir

Default	[None]
Value	string
Advanced Setting; this should not normally be changed.

If this directory exists, and it is writable by the utimaco-x1 service, the messages exchanged between client and server are logged here. This is useful for debugging.

intercept_utimaco_x1_sql_query_add_surveillance

Default	INSERT INTO targets (userid_hash, uuid, address) VALUES ('%Mu', '%i', '%a')
Value	string
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

Default	DELETE FROM targets WHERE uuid = '%i'
Value	string
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 = '%Mu
Value	string
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
%u	User ID
%i	UUID
%a	Address

INFO

To use SHA256 instead of MD5, replace %Mu with %{sha256:userid}.

intercept_utimaco_x1_sql_query_get_surveillance_status

Default	SELECT uuid FROM targets WHERE uuid = '%i'
Value	string
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

Default	SELECT userid_hash, address FROM targets WHERE uuid = '%i'
Value	string
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

Default	SELECT uuid FROM targets
Value	string
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

Default	no
Value	boolean
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

Default	[None]
Value	boolean
Advanced Setting; this should not normally be changed.

Enable debug logging for utimaco-x3 service.

intercept_utimaco_x3_kafka_consume_max_size

Default	10M
Value	size
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]
Value	size
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

Default	utimaco-x3-consumers
Value	string
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]
Value	string
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

Default	no
Value	boolean
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.

libexec_dir

Default	/usr/libexec/dovecot
Value	string
Advanced Setting; this should not normally be changed.

The directory from which you execute commands via doveadm-exec.

lmtp_verbose_replies

Default	no
Value	boolean
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_greeting

Default	Dovecot ready.
Value	string
Advanced Setting; this should not normally be changed.

The greeting message displayed to clients.

Variables allowed:

• LMTP: Mail service user variables
• Other Protocols: Login variables

login_proxy_notify_path

Default	proxy-notify
Value	string
Advanced Setting; this should not normally be changed.

Path to proxy-notify pipe.

Login Variables can be used.

mail_attachment_hash

Default	%{sha1}
Value	string
Allowed Values	%{md4}%{md5}%{sha1}%{sha256}%{sha512}%{size}
See Also	mail_attachment_dir
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_cache_max_header_name_length

Default	100
Value	unsigned 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

Default	100
Value	unsigned 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

Default	1G
Value	size
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]
Value	unsigned 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

Default	200
Value	unsigned 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

Default	20
Value	unsigned 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

Default	4
Value	unsigned 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

Default	32k
Value	size
Advanced Setting; this should not normally be changed.

Only compress cache file if it is larger than this size.

mail_cache_record_max_size

Default	64k
Value	size
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

Default	30days
Value	time
See Also	mail cache configuration
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_full_filesystem_access

Default	no
Value	boolean
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 setting works with both Maildir and mbox, allowing you to prefix mailbox names with /path/ or ~user/ indicators.

mail_index_log2_max_age

Default	2days
Value	time
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_max_size

Default	1M
Value	size
See Also	mail_index_log_rotate_min_age mail_index_log_rotate_min_size
Advanced Setting; this should not normally be changed.

Always rotate transaction log after it exceeds this size.

mail_index_log_rotate_min_age

Default	5mins
Value	time
See Also	mail_index_log_rotate_max_size
Advanced Setting; this should not normally be changed.

Rotate transaction log if it is older than this value and is larger than mail_index_log_rotate_min_size.

mail_index_log_rotate_min_size

Default	32k
Value	size
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

Default	128k
Value	size
See Also	mail_index_rewrite_min_log_bytes
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

Default	8k
Value	size
See Also	mail_index_rewrite_max_log_bytes
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

Default	50
Value	unsigned 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

Default	no
Value	boolean
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

Default	30secs
Value	time
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.

managesieve_client_workarounds

Default	[None]
Value	string
Advanced Setting; this should not normally be changed.

Enables various workarounds for ManageSieve clients. Currently there are none.

managesieve_implementation_string

Default	Dovecot Pigeonhole
Value	string
Advanced Setting; this should not normally be changed.

Sets the ManageSieve implementation string returned by the IMPLEMENTATION capability.

managesieve_max_compile_errors

Default	5
Value	unsigned 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

Default	65536
Value	unsigned integer
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>
Value	string
Advanced Setting; this should not normally be changed.

NOTIFY capabilities reported by the ManageSieve service before authentication.

If left unassigned, these will be assigned dynamically according to what the Sieve interpreter supports by default (after login this may differ depending on the authenticated user).

managesieve_sieve_capability

Default	fileinto reject envelope encoded-character vacation subaddress comparator-i;ascii-numeric relational regex imap4flags copy include variables body enotify environment mailbox date index ihave duplicate mime foreverypart extracttext
Value	string
Advanced Setting; this should not normally be changed.

SIEVE capabilities reported by the ManageSieve service before authentication.

If left unassigned, these will be assigned dynamically according to what the Sieve interpreter supports by default (after login this may differ depending on the authenticated user).

mbox_md5

Default	apop3d
Value	string
Allowed Values	apop3dall
See Also	pop3_uidl_format mbox
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 = %m is applied.

mbox_min_index_size

Default	[None]
Value	size
See Also	mbox
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

Default	no
Value	boolean
Plugin	obox 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_disable_bundle_list_cache

Default	no
Value	boolean
Plugin	obox plugin
Advanced Setting; this should not normally be changed.

Disable caching bundle list.

metacache_disable_secondary_indexes

Default	no
Value	boolean
Plugin	obox plugin
Advanced Setting; this should not normally be changed.

Disable 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_index_merging

Default	v2
Value	string
Plugin	obox 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

Default	10
Value	unsigned integer
Plugin	obox 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

Default	100
Value	unsigned integer
Plugin	obox 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_priority_weights

Default	[None]
Value	string
Plugin	obox plugin
Advanced Setting; this should not normally be changed.

See metacache_size_weights.

metacache_rescan_interval

Default	1 day
Value	time
See Also	metacache_roots
Plugin	obox 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

Default	mail_home and mail_chroot
Value	string
See Also	metacache_rescan_interval
Plugin	obox 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_size_weights

Default	[None]
Value	string
Plugin	obox 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:

plugin {
  metacache_priority_weights = 10% +1d 10% +1d 50% +1h 100% 0
  metacache_size_weights = 2M +30 1G +120
}

metacache_socket_path

Default	metacache
Value	string
Plugin	obox plugin
Advanced Setting; this should not normally be changed.

Path to communicate with metacache process.

metacache_userdb

Default	metacache/metacache-users.db
Value	string
Plugin	obox 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

Default	no
Value	boolean
Plugin	obox 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

Default	no
Value	boolean
Plugin	obox 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

Default	no
Value	boolean
Plugin	obox 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

Default	no
Value	boolean
Plugin	obox 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_dont_use_object_ids

Default	no
Value	boolean
Plugin	obox plugin
Advanced Setting; this should not normally be changed.

Access objects directly via their paths instead of IDs, if possible.

obox_fetch_lost_mails_as_empty

Default	no
Value	boolean
See Also	storage workarounds
Plugin	obox 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

Default	recovered-lost-folder-
Value	string
Plugin	obox 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

Default	10
Value	unsigned integer
Plugin	obox 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_no_pop3_backend_uidls

Default	no
Value	boolean
Plugin	obox plugin
Advanced Setting; this should not normally be changed.

Enable if there are no migrated POP3 UIDLs. If enabled, don't try to look up UIDLs in any situation.

obox_size_missing_action

Default	warn-read
Value	string
Plugin	obox 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_username

Default	mail_location
Value	string
Plugin	obox plugin
Advanced Setting; this should not normally be changed.

Overrides the obox username in storage.

quota_clone_unset

Default	[None]
Value	boolean
Plugin	quota-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 backends that do not support upserting, such as SQL with older SQLite.

sieve_duplicate_default_period

Default	14d
Value	time
See Also	Sieve duplicate extension
Plugin	sieve 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

Default	7d
Value	time
See Also	Sieve duplicate extension
Plugin	sieve 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

Default	255
Value	unsigned integer
See Also	Sieve include extension
Plugin	sieve 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_include_max_nesting_depth

Default	10
Value	unsigned integer
See Also	Sieve include extension
Plugin	sieve plugin
Advanced Setting; this should not normally be changed.

The maximum nesting depth for the include tree.

sieve_max_script_size

Default	1M
Value	size
Plugin	sieve 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_size

Default	255
Value	unsigned integer
See Also	Sieve vacation extension
Plugin	sieve 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_variable_size

Default	4k
Value	size
See Also	Sieve variables extension
Plugin	sieve 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
Value	string
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

Default	64
Value	unsigned integer
Plugin	virtual plugin
Advanced Setting; this should not normally be changed.

How many mailboxes to open in virtual plugin.