Dovecot Core Settings

See Settings for list of all setting groups.

auth_anonymous_username

  • Default: anonymous

  • Values: String

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

auth_cache_negative_ttl

  • Default: hour

  • Values: Time

This sets the time to live for negative hits (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: 0

  • Values: Size

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

The setting auth_cache_size = 0 disables use of the authentication cache.

auth_cache_ttl

  • Default: 1hour

  • Values: Time

This determines the time to live for cached data. After the TTL expires, the cached record is no longer used, unless the main database look-up returns internal failure.

auth_cache_verify_password_with_worker

New in version v2.2.34.

Changed in version v2.3.18: Fixed to work properly. Older versions lost passdb extra fields.

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

Enables all authentication debug logging (also enables auth_verbose). Passwords are logged as <hidden>.

auth_debug_passwords

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

Enabling this enables auth_debug as well.

auth_default_realm

  • Default: <empty>

  • Values: String

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 plaintext logins.

auth_failure_delay

  • Default: 2secs

  • Values: Time

This is the delay before replying to failed authentication attempts.

This setting defines the interval for which the authentication process flushes all auth failures. Thus, this is the maximum interval a user may encounter.

auth_gssapi_hostname

  • Default: <name returned by gethostname()>

  • Values: 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_krb5_keytab

  • Default: <system default (e.g. /etc/krb5.keytab)>

  • Values: 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: <empty>

  • Values: 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

  • Values: plain, login, digest-md5, cram-md5, ntlm, rpa, apop, anonymous, gssapi, otp, skey, gss-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

Do policy lookup after authentication is completed?

See also

auth_policy_server_url

auth_policy_check_before_auth

Do policy lookup before authentication is started?

See also

auth_policy_server_url

auth_policy_hash_mech

  • Default: sha256

  • Values: md4, md5, sha1, sha256, sha512

Hash mechanism to use for password.

See also

auth_policy_server_url

auth_policy_hash_nonce

  • Default: <empty>

  • Values: String

Cluster-wide nonce to add to hash.

REQUIRED configuration when you want to use authentication policy.

Example Setting:

auth_policy_hash_nonce = <localized_random_string>

See also

auth_policy_server_url

auth_policy_hash_truncate

How many bits to use from password hash when reporting to policy server.

See also

auth_policy_server_url

auth_policy_log_only

Only log what the policy server response would do?

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

See also

auth_policy_server_url

auth_policy_reject_on_fail

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

See also

auth_policy_server_url

auth_policy_report_after_auth

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

  • Values: String

Request attributes specification.

Variables that can be used for this setting:

Auth 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}. (v2.2.34+)

See also

auth_policy_server_url

auth_policy_server_api_header

  • Default: <empty>

  • Values: String

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

See also

auth_policy_server_url

auth_policy_server_timeout_msecs

Auth policy request timeout.

auth_policy_server_url

  • Default: <empty>

  • Values: String

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 Setting:

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

  • Default: <empty>

  • Values: String

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_realms

  • Default: <empty>

  • Values: 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 Setting:

auth_realms = example.com another.example.com foo
auth_socket_path

  • Default: auth-userdb

  • Values: 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

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

See also

ssl_ca

ssl_verify_client_cert

Dovecot SSL configuration

auth_ssl_username_from_cert

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.

See also

ssl_cert_username_field

auth_stats

New in version v2.3.0.

If enabled, authentication statistics are added.

auth_use_winbind

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

  • Values: 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

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_username_translation

  • Default: <empty>

  • Values: String

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_verbose

New in version v2.2.24.

Adjust log verbosity.

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

Explicitly setting auth_debug will override this setting.

auth_verbose_passwords

  • Default: no

  • Values: no, yes, plain, sha1

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 plaintext password (NOT RECOMMENDED)

sha1

Output SHA1 hashed password

auth_winbind_helper_path

  • Default: <empty>

  • Values: 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

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.

base_dir

  • Default: /var/run/dovecot/

  • Values: String

The base directory in which Dovecot should store runtime data.

This can be used to override the base directory determined at compile time.

config_cache_size

  • Default: 1 M

  • Values: Size

The maximum size of the in-memory configuration cache.

The cache should be large enough to allow keeping the full, parsed Dovecot configuration in memory.

The default is almost always large enough, unless your system has numerous large TLS certificates in the configuration.

debug_log_path

The log file to use for debug messages.

default_client_limit

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 client_limit setting within service blocks.

default_idle_kill

  • Default: 1mins

  • Values: Time

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

default_internal_group

  • Default: dovecot

  • Values: String

Define the default internal group.

See also

default_internal_user

default_internal_user

  • Default: dovecot

  • Values: String

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.

See also

default_internal_group

default_login_user

  • Default: dovenull

  • Values: 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

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

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

default_vsz_limit

  • Default: 256M

  • Values: 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 vsz_limit setting within service blocks.

deliver_log_format

  • Default: msgid=%m: %$

  • Values: String

The format to use for logging mail deliveries.

Variables that can be used for this setting:

Variable Name

Description

Global variables

%$

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: %$
dict_db_config

  • Default: <empty>

  • Values: String

Points to a Berkeley DB config file. Equivalent to adding DB_CONFIG=/path to import_environment.

See https://docs.oracle.com/database/bdb181/html/bdb-sql/sql_db_config.html for more information.

Example:

dict_db_config=/etc/dovecot/berkeley.conf
director_flush_socket

  • Default: <empty>

  • Values: String

The doveadm director flush command removes all user associations either from the given host or all hosts. All the existing connections will be kicked.

This setting points to a file path of a flush script that is automatically executed when the flush command is run.

Variables that can be used for this setting:

Variable Name

Description

Global variables

%{host}, %h

Hostname of the backend

%{ip}, %i

IP address of the backend
director_mail_servers

List of IPs or hostnames of all backend mail servers.

This list is used to bootstrap a Director ring; backend hosts can be dynamically added to a running ring via the doveadm commands.

director_max_parallel_kicks

The maximum number of concurrent kicks allowed in the Director ring.

director_max_parallel_moves

How many concurrent user moves are allowed in the Director ring?

This default can be overridden with doveadm director flush --max-parallel parameter.

director_output_buffer_size

  • Default: 10M

  • Values: Size

This allows configuring the max buffer size for outgoing connections. Previously it was hardcoded to 10 MB, which wasn’t necessarily enough for very busy directors. If the max buffer size is reached, the connection is disconnected (and reconnected).

director_ping_idle_timeout

  • Default: 30secs

  • Values: Time

Minimum time to wait for a reply to PING that was sent to another director before disconnecting (and reconnecting). This setting is used when there’s otherwise no input coming from the connection.

director_ping_max_timeout

  • Default: 1mins

  • Values: Time

Maximum time to wait for a reply to PING that was sent to another director before disconnecting (and reconnecting).

This setting is used when the other director keeps sending input, but among it is no PONG reply.

director_servers

A list of IP addresses or hostnames for all Director servers, including the machine on which the setting is made.

Ports can be specified after a colon (in IP:port form) if something other than the default port is to be used (the default port is the one used by the Director service’s inet_listener).

This list is used to bootstrap a Director ring; directors can be dynamically added to a running ring via the doveadm commands.

director_user_expire

  • Default: 15mins

  • Values: Time

How long to keep routing information in the Director ring after a user has no more active connections.

director_user_kick_delay

  • Default: 2secs

  • Values: Time

How long to wait after a user has been kicked from the Director ring before that user can log in to the new server. This timeout should allow time for the old backend to complete all of the user’s existing processes.

director_username_hash

How the username is translated before being hashed. For example, one might want to use %Ln if the user can log in with or without @domain and %Ld if mailboxes are shared within the domain.

Variables that can be used for this setting:

Variable Name

Description

Global variables

%{user}, %u

Username (username@domain)

%{username}, %n

Username

%{domain}, %d

Domain
disable_plaintext_auth

If yes, disables the LOGIN command and all other plaintext authentication unless SSL/TLS is used (LOGINDISABLED capability) or the connection is “secured”:

  • Client IP is in login_trusted_networks

  • Client IP is from localhost, and it’s not coming from HAProxy listener

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

dotlock_use_excl

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

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

The setting ALL allows all commands.

doveadm_api_key

  • Default: <empty>

  • Values: 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: <empty>

  • Values: String

Directory where doveadm stores HTTP rawlogs.

See also

Rawlog

doveadm_password

  • Default: <empty>

  • Values: 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: 0

  • Values: <1-65535>

The destination port to be used for the next doveadm proxying hop.

A value of 0 means that proxying is not in use.

doveadm_socket_path

  • Default: doveadm-server

  • Values: String

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

doveadm_ssl

  • Default: no

  • Values: no, ssl, starttls

New in version v2.3.9.

TODO

doveadm_username

  • Default: doveadm

  • Values: String

The username for authentication to the doveadm service.

doveadm_worker_count

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.

dsync_alt_char

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

New in version v2.2.30.

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

dsync_features

  • Default: <empty>

  • Values: String

New in version v2.2.26.

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.

New in version v2.3.20.

dsync_hashed_headers

  • Default: Date Message-ID

  • Values: String

New in version v2.2.33.

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.

dsync_remote_cmd

  • Default: ssh -l%{login} %{host} doveadm dsync-server -u%u -U

  • Values: String

Command to replicate when the replication plug-in is used.

Variables that can be used for this setting:

Variable Name

Description

Global variables

%{user}, %u

Username

%{login}

Remote login name (from login@host)

%{host}

Remote hostname (from login@host)
first_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.

See also

last_valid_gid

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

See also

last_valid_gid

haproxy_timeout

  • Default: 3secs

  • Values: Time

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

haproxy_trusted_networks

  • Default: <empty>

  • Values: 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

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

imap_capability

  • Default: <empty>

  • Values: 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: <empty>

  • Values: 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_fetch_failure

  • Default: disconnect-immediately

  • Values: disconnect-after, disconnect-immediately, no-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: 0

  • Values: Size

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_log

  • Default: <empty>

  • Values: String

The ID fields sent by the client that are output to the log.

Using * as the value means that everything available should be sent.

imap_id_retain

New in version v2.2.29.

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 Auth variables.

imap_id_send

  • Default: name *

  • Values: 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)

New in version v2.3.10.

Example:

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

  • Default: 2mins

  • Values: Time

The amount of time to wait between “OK Still here” untagged IMAP responses when the client is in IDLE operation.

imap_literal_minus

New in version v2.2.25.

Enable IMAP LITERAL- 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}

  • Values: String

This setting specifies the IMAP logout format string. Supported variables are:

Variable Name

Description

Mail user variables

%{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_max_line_length

  • Default: 64k

  • Values: Size

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.

imap_metadata

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: <empty>

  • Values: String

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

  • Values: String

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

  • Values: <1-65535>

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

imapc_cmd_timeout

See: imapc_cmd_timeout

imapc_connection_retry_count

See: imapc_connection_retry_count

imapc_connection_retry_interval

See: imapc_connection_retry_interval

imapc_features

See: imapc_features

imapc_host

See: imapc_host

imapc_list_prefix

See: imapc_list_prefix

imapc_master_user

See: imapc_master_user

imapc_max_idle_time

See: imapc_max_idle_time

imapc_max_line_length

See: imapc_max_line_length

imapc_password

See: imapc_password

imapc_port

See: imapc_port

imapc_rawlog_dir

See: imapc_rawlog_dir

imapc_sasl_mechanisms

See: imapc_sasl_mechanisms

imapc_ssl

See: imapc_ssl

imapc_ssl_verify

See: imapc_ssl_verify

imapc_user

See: imapc_user

import_environment

  • Default: TZ CORE_OUTOFMEM CORE_ERROR

  • Values: 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

The log file to use for informational messages.

instance_name

  • Default: dovecot

  • Values: 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.

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

See also

first_valid_gid

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

See also

first_valid_uid

lda_mailbox_autocreate

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

lda_mailbox_autosubscribe

Should automatically created mailboxes be subscribed to?

lda_original_recipient_header

  • Default: <empty>

  • Values: 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
libexec_dir

  • Default: /usr/libexec/dovecot

  • Values: String

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

listen

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

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

Example:

listen = 127.0.0.1, 192.168.0.1
lmtp_add_received_header

New in version v2.3.9.

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

lmtp_address_translate

  • Default: <empty>

  • Values: String

Removed in version v2.3.0.

lmtp_client_workarounds

  • Default: <empty>

  • Values: String

New in version v2.3.9.

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

  • Values: alternative, final, none

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

Proxy to other LMTP/SMTP servers?

Proxy destination is determined via passdb lookup parameters.

See also

Proxy PasswordDatabase

lmtp_proxy_rawlog_dir

  • Default: <empty>

  • Values: String

New in version v2.3.2.

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.

See also

Rawlog

lmtp_rawlog_dir

  • Default: <empty>

  • Values: String

New in version v2.3.2.

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.

See also

Rawlog

lmtp_rcpt_check_quota

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

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

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.

lmtp_verbose_replies

New in version v2.3.18.

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.

lock_method

  • Default: fcntl

  • Values: fcntl, flock, dotlock

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: <empty>

  • Values: String

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

For example:

log_core_filter = category=error

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

log_debug

  • Default: <empty>

  • Values: String

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

Note

This will eventually replace mail_debug and auth_debug settings.

log_path

  • Default: syslog

  • Values: String

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

See also

debug_log_path

info_log_path

log_timestamp

  • Default: %b %d %H:%M:%S

  • Values: String

The prefix for each line written to the log file.

% variables are in strftime(3) format.

login_access_sockets

  • Default: <empty>

  • Values: String

For blacklisting or whitelisting networks, supply a space-separated list of login-access-check sockets for this setting.

Dovecot login processes can check via UNIX socket whether login should be allowed for the incoming connection.

login_greeting

  • Default: Dovecot ready.

  • Values: String

The greeting message displayed to clients.

Variables:

LMTP

Other Protocols

login_log_format

  • Default: %$: %s

  • Values: String

The formatting of login log messages.

Variables:

Variable Name

Description

Global variables

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

  • Values: 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

  • Values: String

Location of the login plugin directory.

login_plugins

  • Default: <empty>

  • Values: String

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

login_proxy_max_disconnect_delay

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

New in version v2.3.12.

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: <empty>

  • Values: String

New in version v2.3.17.

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

See also

Rawlog

login_proxy_timeout

New in version v2.3.12.

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_timeout passdb extra field.

login_source_ips

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: <empty>

  • Values: <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.

Client connections from trusted networks are also treated as “secured”, i.e. the same as if they had been using SSL/TLS. This affects the ssl and disable_plaintext_auth settings. It also marks the connection as “secured” for all auth lookups, which also affects the %{secured} variable.

This original client IP address is then used for logging and authentication checks.

Plaintext authentication is always allowed for trusted networks (disable_plaintext_auth is ignored).

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: <empty>

  • Values: 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: <empty>

  • Values: String

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

See Mail Cache Settings for details and for the list of fields.

See also

mail_cache_fields

mail_never_cache_fields

mail_attachment_detection_options

  • Default: <empty>

  • Values: 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.

New in version v2.3.13.

add-flags-on-save

Deprecated alias for add-flags.

Before v2.3.13 the detection was done only during save, not during fetch.

Deprecated since version v2.3.13.

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.

New in version v2.3.13.

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: <empty>

  • Values: 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

  • Values: posix, sis posix, sis-queue posix

Which filesystem type to use for saving attachments.

Options:

posix

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

sis posix

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

sis-queue posix

SiS with delayed comparison and de-duplication.

Mail user variables can be used.

See also

mail_attachment_dir

mail_attachment_hash

  • Default: %{sha1}

  • Values: %{md4}, %{md5}, %{sha1}, %{sha256}, %{sha512}, %{size}

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.

See also

mail_attachment_dir

mail_attachment_min_size

  • Default: 128k

  • Values: Size

Attachments below this size will not be saved externally.

See also

mail_attachment_dir

mail_attribute_dict

  • Default: <empty>

  • Values: String

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

See also

imap_metadata

mail_cache_fields

  • Default: flags

  • Values: String

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 Settings for details and for the list of fields.

See also

mail_always_cache_fields

mail_never_cache_fields

mail_chroot

  • Default: <empty>

  • Values: 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_debug

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

  • Values: always, optimized, never

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.

With obox, this option is recommended to be used because it affects only the local metacache operations. If a server crashes, the existing metacache is treated as potentially corrupted and isn’t used.

mail_full_filesystem_access

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_gid

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.

See also

mail_uid

mail_home

  • Default: <empty>

  • Values: String

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

See also

mail_location

Quick Configuration

mail_location

  • Default: <empty>

  • Values: String

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.

See also

Mail Location Settings

mail_log_prefix

  • Default: %s(%u)<%{pid}><%{session}>:

  • Values: String

You can specify a log prefix for mail processes here.

Mail service user variables can be used.

mail_max_keyword_length

The maximum length allowed for a mail keyword name.

Compliance is enforced only during attempts to create new keywords

mail_max_lock_timeout

  • Default: 0

  • Values: 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

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

  • Values: String

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 Settings for details and for the list of fields.

See also

mail_always_cache_fields

mail_cache_fields

mail_nfs_index

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

See also

mail_fsync

mail_nfs_storage

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

  • Values: String

The directory in which to search for Dovecot mail plugins.

See also

mail_plugins

mail_plugins

  • Default: <empty>

  • Values: String

A space-separated list of plugins to load.

See also

mail_plugin_dir

Example Usage

mail_prefetch_count

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.

  • obox: Read multiple mails in parallel from object storage to local disk without waiting for previous reads to finish. The downside is that each mail uses a file descriptor and disk space in mail_temp_dir.

    This setting is also the default for obox_max_parallel_copies, obox_max_parallel_deletes and obox_max_parallel_writes.

For imapc and obox formats a good value is likely between 10..100.

0 means that no prefetching is done.

mail_privileged_group

  • Default: <empty>

  • Values: 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_save_crlf

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.

mail_server_admin

  • Default: <empty>

  • Values: String

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

See also

imap_metadata

mail_server_comment

  • Default: <empty>

  • Values: String

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.

See also

imap_metadata

mail_shared_explicit_inbox

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

mail_sort_max_read_count

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.

Note

As a special case with the obox format when doing a SORT (ARRIVAL), the SORT will always return OK.

When it reaches the slow access limit, it falls back to using the save-date (instead of received-date) for the rest of the mails.

Often this produces mostly the same result, especially in the INBOX.

mail_temp_dir

  • Default: /tmp

  • Values: 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

  • Values: 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.

A value of 0 means this scan never occurs.

Changed in version 2.3.21: 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 mail_temp_scan_interval.

  • 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 mail_temp_scan_interval.

  • mdbox: Delete .temp.* files having ctime older than 36 hours from storage/. The scan is done if storage/ directory’s atime is older than mail_temp_scan_interval.

mail_uid

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.

See also

mail_gid

mail_vsize_bg_after_count

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
}

See also

Quota Plugin

mailbox_idle_check_interval

  • Default: 30secs

  • Values: Time

The minimum time between checks for new mail/other changes when a mailbox is in the IMAP IDLE state.

mailbox_list_index

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

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

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

See also

Mailbox list index

mailbox_list_index_very_dirty_syncs

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

See: maildir_broken_filename_sizes

maildir_copy_with_hardlinks

See: maildir_copy_with_hardlinks

maildir_empty_new

See: maildir_empty_new

maildir_stat_dirs

See: maildir_stat_dirs

maildir_very_dirty_syncs

See: maildir_very_dirty_syncs

master_user_separator

  • Default: <empty>

  • Values: String

Removed in version v2.3.20.

This setting was accidentally used by the director service. It has been replaced by the auth_master_user_separator setting. With old Dovecot versions both the settings must be set to the same value.

mbox_dirty_syncs

See: mbox_dirty_syncs

mbox_dotlock_change_timeout

See: mbox_dotlock_change_timeout

mbox_lazy_writes

See: mbox_lazy_writes

mbox_lock_timeout

See: mbox_lock_timeout

mbox_md5

See: mbox_md5

mbox_min_index_size

See: mbox_min_index_size

mbox_read_locks

See: mbox_read_locks

mbox_very_dirty_syncs

See: mbox_very_dirty_syncs

mbox_write_locks

See: mbox_write_locks

mdbox_preallocate_space

See: mdbox_preallocate_space

mdbox_rotate_interval

See: mdbox_rotate_interval

mdbox_rotate_size

See: mdbox_rotate_size

mmap_disable

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

old_stats_carbon_interval

  • Default: 30secs

  • Values: Time

New in version v2.2.27.

The interval at which to send stats to the Carbon server.

See also

old_stats_carbon_server

old_stats_carbon_name

  • Default: <empty>

  • Values: String

New in version v2.2.27.

The identifier to use for this node when exporting stats to the Carbon server.

Do not use dots (.) in this setting.

Example:

stats_carbon_name = hostname

See also

old_stats_carbon_server

old_stats_carbon_server

  • Default: <empty>

  • Values: <hostname | ip>:<port>

New in version v2.2.27.

Send server statistics to an external Carbon server.

old_stats_command_min_time

  • Default: 1min

  • Values: Time

Command-level stats older than this value will be cleared once the memory limit in old_stats_memory_limit is reached.

old_stats_domain_min_time

  • Default: 12hours

  • Values: Time

Domain-level stats older than this value will be cleared once the memory limit in old_stats_memory_limit is reached.

old_stats_ip_min_time

  • Default: 12hours

  • Values: Time

IP Address-level stats older than this value will be cleared once the memory limit in old_stats_memory_limit is reached.

old_stats_memory_limit

  • Default: 16M

  • Values: Size

The maximum amount of memory that can be used by the old stats process.

old_stats_session_min_time

  • Default: 15mins

  • Values: Time

Session-level stats older than this value will be cleared once the memory limit in old_stats_memory_limit is reached.

old_stats_user_min_time

  • Default: 1hour

  • Values: Time

User-level stats older than this value will be cleared once the memory limit in old_stats_memory_limit is reached.

pop3_client_workarounds

  • Default: <empty>

  • Values: 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

  • Values: default, flag, expunge

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

pop3_deleted_flag

  • Default: <empty>

  • Values: String

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

See also

pop3_delete_type

pop3_enable_last

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

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

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

  • Values: String

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

Variables available:

Variable Name

Description

Mail user variables

%{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_no_flag_updates

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

pop3_reuse_xuidl

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

pop3_save_uidl

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

  • Values: allow, rename

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

  • Values: 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):

Variable Name

Description

Global variables

%{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
pop3c_features

See: pop3c_features

pop3c_host

See: pop3c_host

pop3c_master_user

See: pop3c_master_user

pop3c_password

See: pop3c_password

pop3c_port

See: pop3c_port

pop3c_quick_received_date

See: pop3c_quick_received_date

pop3c_rawlog_dir

See: pop3c_rawlog_dir

pop3c_ssl

See: pop3c_ssl

pop3c_ssl_verify

See: pop3c_ssl_verify

pop3c_user

See: pop3c_user

postmaster_address

  • Default: postmaster@%{if;%d;ne;;%d;%{hostname}}

  • Values: 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: <empty>

  • Values: String

New in version 2.3.19.

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 filter syntax.

For example:

process_shutdown_filter = "event=mail_user_session_finished AND rss > 10M"
protocols

  • Default: imap pop3 lmtp

  • Values: String

The list of protocols this node will support.

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

quota_full_tempfail

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.

See also

Quota Plugin

rawlog_dir

  • Default: <empty>

  • Values: String

New in version v2.2.26.

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
}

See also

Rawlog

recipient_delimiter

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

rejection_reason

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

  • Values: String

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

The following variables are allowed:

Variable Name

Description

Global variables

%{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

  • Values: String

The Subject: header to use for bounce messages.

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

See also

rejection_reason

replication_dsync_parameters

  • Default: -d -N -l 30 -U

  • Values: String

New in version v2.2.29.

The parameters used by the replicator for the doveadm sync (dsync) command.

See also

replicator

replication_full_sync_interval

  • Default: 1day

  • Values: Time

How often full synchronization is to be performed with the replicator.

See also

replicator

replication_max_conns

How many dsyncs may be run in parallel for replicator.

See also

replicator

replicator

  • Default: <empty>

  • Values: String

The replicator host to be used in dsync operation.

replicator_host

  • Default: <empty>

  • Values: String

Specifies remote hostname or UNIX socket to connect for replicator process. If replicator_port is set to 0, then it will be treated as UNIX socket.

See also

replicator

replicator_port

The port indicated here is used by dsync for replication. If set to 0, replicator_host is interpreted as UNIX socket path.

See also

replicator

sendmail_path

  • Default: /usr/sbin/sendmail

  • Values: String

The binary to use for sending email.

Used only if submission_host is not set.

shutdown_clients

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.

ssl

  • Default: yes

  • Values: yes, no, required

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 disable_plaintext_auth in that even non-plaintext authentication mechanisms aren’t allowed without SSL/TLS.

Note that SSL is still not required for “secured” connections:

  • Client IP is in login_trusted_networks

  • Client IP is from localhost, and it’s not coming from HAProxy listener

See also

Dovecot SSL configuration

ssl_alt_cert

  • Default: <empty>

  • Values: String

New in version v2.2.31.

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

See also

ssl

Dovecot SSL configuration

ssl_alt_key

  • Default: <empty>

  • Values: String

New in version v2.2.31.

Private key for ssl_alt_cert.

Example:

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

See also

ssl

ssl_alt_cert

Dovecot SSL configuration

ssl_ca

  • Default: <empty>

  • Values: String

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

See also

ssl

ssl_client_require_valid_cert

ssl_verify_client_cert

Dovecot SSL configuration

ssl_cert

  • Default: </etc/ssl/certs/dovecot.pem

  • Values: String

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

See also

ssl

ssl_key

Dovecot SSL configuration

ssl_cert_username_field

  • Default: commonName

  • Values: String

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.

See also

ssl

Dovecot SSL configuration

ssl_cipher_list

  • Default: ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@STRENGTH

  • Values: String

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.

See also

ssl

ssl_cipher_suites

ssl_min_protocol

Dovecot SSL configuration

ssl_cipher_suites

  • Default: <OpenSSL version specific>

  • Values: String

New in version v2.3.15.

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

See also

ssl

ssl_cipher_list

Dovecot SSL configuration

ssl_client_ca_dir

  • Default: <empty>

  • Values: String

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.

See also

SSL

ssl_client_ca_file

  • Default: <empty>

  • Values: String

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.

See also

ssl

Dovecot SSL configuration

ssl_client_cert

  • Default: <empty>

  • Values: String

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

See also

ssl

ssl_client_key

Dovecot SSL configuration

ssl_client_key

  • Default: <empty>

  • Values: String

Private key for ssl_client_cert.

Example:

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

See also

ssl

ssl_client_cert

Dovecot SSL configuration

ssl_crypto_device

  • Default: <empty>

  • Values: <Obtain by running ‘openssl engine’ command>

Which SSL crypto device to use.

See also

ssl

Dovecot SSL configuration

ssl_curve_list

  • Default: <defaults from the SSL library>

  • Values: String

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

See also

ssl

Dovecot SSL configuration

ssl_dh

  • Default: <empty>

  • Values: String

New in version v2.3.0.

As of Dovecot v2.3, 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 gendh 4096 on a machine with sufficient entropy (this may take some time).

Example:

ssl_dh=</path/to/dh.pem

See also

ssl

Dovecot SSL configuration

ssl_client_require_valid_cert

Require a valid certificate when connecting to external SSL services?

See also

ssl

Dovecot SSL configuration

ssl_key

  • Default: <empty>

  • Values: String

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

See also

ssl

ssl_cert

ssl_key_password

Dovecot SSL configuration

ssl_key_password

  • Default: <empty>

  • Values: String

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.

See also

ssl

ssl_key

Dovecot SSL configuration

ssl_min_protocol

  • Default: TLSv1.2

  • Values: String

The minimum SSL protocol version Dovecot accepts.

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

Supported values are:

ANY

Support any version. (SHOULD NOT BE USED)

New in version v2.3.15.

SSLv3

Support SSLv3+. (SHOULD NOT BE USED) (SSLv3 deprecated: RFC 7568)

TLSv1

Support TLSv1+. (default before v2.3.15) (TLSv1 deprecated: RFC 8996)

TLSv1.1

Support TLSv1.1+. (TLSv1.1 deprecated: RFC 8996)

TLSv1.2

Support TLSv1.2+. (default since v2.3.15)

TLSv1.3

Support TLSv1.3+.

New in version v2.3.15.

LATEST

Support only the latest version available.

New in version v2.3.15.

See also

ssl

ssl_cipher_list

Dovecot SSL configuration

ssl_options

  • Default: no-compression

  • Values: compression, no_compression, no_ticket

Additional options for SSL.

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

Currently supported options are:

compression

Enable compression (v2.3+).

no_compression

Disable compression (before v2.3).

no_ticket

Disable SSL session tickets.

See also

ssl

Dovecot SSL configuration

ssl_prefer_server_ciphers

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

See also

ssl

Dovecot SSL configuration

ssl_require_crl

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.

See also

ssl

ssl_ca

Dovecot SSL configuration

ssl_verify_client_cert

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.

See also

SSL

ssl

auth_ssl_require_client_cert

Dovecot SSL configuration

state_dir

  • Default: /var/lib/dovecot

  • Values: String

The compile-time directory PKG_STATEDIR (typically /var/lib/dovecot) is hard-coded as the location of things such as the ssl-parameters.dat file and the replicator database. 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.

stats_writer_socket_path

  • Default: stats-writer

  • Values: String

The path to the stats-writer socket.

submission_client_workarounds

  • Default: <empty>

  • Values: 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).

New in version v2.3.18.

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: <empty>

  • Values: String

Use this SMTP submission host to send messages.

Overrides sendmail_path value, if set.

submission_logout_format

  • Default: in=%i out=%o

  • Values: String

The SMTP Submission logout format string.

Variables supported:

Variable Name

Description

Mail user variables

%{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

  • Values: 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

Maximum number of recipients accepted per connection.

submission_relay_command_timeout

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

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

submission_relay_host

  • Default: <empty>

  • Values: String

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

submission_relay_master_user

  • Default: <empty>

  • Values: String

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

submission_relay_max_idle_time

  • Default: 29mins

  • Values: Time

Submission relay max idle time for connection to relay MTA.

submission_relay_password

  • Default: <empty>

  • Values: String

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

submission_relay_port

  • Default: 25

  • Values: <1-65535>

Port for the submission relay server.

submission_relay_rawlog_dir

  • Default: <empty>

  • Values: String

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

Mail user variables can be used.

See also

Rawlog

submission_relay_ssl

  • Default: no

  • Values: no, smtps, starttls

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

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

submission_relay_trusted

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: <empty>

  • Values: String

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

submission_ssl

If enabled, use SSL/TLS to connect to submission_host.

submission_timeout

  • Default: 30secs

  • Values: Time

Timeout for submitting outgoing messages.

See also

submission_host

syslog_facility

  • Default: mail

  • Values: String

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

valid_chroot_dirs

  • Default: <empty>

  • Values: 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.

verbose_proctitle

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 IMAP processes.

verbose_ssl

If enabled, protocol-level SSL errors are logged.

version_ignore

If enabled, ignore version mismatches between different Dovecot versions.