All Dovecot Settings

Settings

`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: 2.4.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: 2.4.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: 2.4.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: 2.4.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_gssapi_hostname`

Default	`<name returned by gethostname()>`
Value	string

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_internal_failure_delay`

Default	`2secs`
Value	time (milliseconds)
See Also	`auth_failure_delay`
Changes	Added: 2.4.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_krb5_keytab`

Default	`<system default (e.g. /etc/krb5.keytab)>`
Value	string

This specifies the Kerberos keytab to use for the GSSAPI mechanism.

Note: You may need to set the auth service to run as root in order for this file to be readable.

`auth_master_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: 2.4.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.

It is usually neither necessary nor advisable to change the default.

`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_use_winbind`

Default	`no`
Value	boolean

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_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_winbind_helper_path`

Default	[None]
Value	string

This setting tells the system the path for Samba's ntlm_auth helper binary.

Example:

auth_winbind_helper_path = /usr/bin/ntlm_auth

`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
}

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

`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: 2.4.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: 2.4.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.

`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: 2.4.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_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_flatcurve_substring_search`

Default	`no`
Value	boolean
Plugin	fts-flatcurve plugin

If enabled, allows substring searches (RFC 3501 compliant). However, this requires significant additional storage space. Many users today expect "Google-like" behavior, which is prefix searching, so substring searching is arguably not the modern expected behavior anyway. Therefore, even though it is not strictly RFC compliant, prefix (non-substring) searching is enabled by default.

`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: 2.4.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: 2.4.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	[None]
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_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: 2.4.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: 2.4.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: 2.4.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: 2.4.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: 2.4.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: 2.4.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: 2.4.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: 2.4.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: 2.4.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.