IMAP Configuration
Dovecot was optimized since the beginning to work as an efficient IMAP server.
Namespaces
See Namespaces.
IMAP Extensions
Dovecot supports many IMAP extensions.
COMPRESS
Dovecot supports the IMAP COMPRESS (RFC 4978) extension.
It allows an IMAP client to dynamically enable stream compression for an IMAP session.
The extension is enabled by default and configured with the default compression level for the available mechanism.
When the client connection comes through a Dovecot proxy, the compression is by default handled by the proxy instead of the backend's imap process. See imap_compress_on_proxy.
SEARCH=FUZZY
IMAP provides SEARCH as part of the core protocol, so it is useful to activate a Full Text Search indexing driver to handle these searches.
See fts plugin.
METADATA
Dovecot supports the IMAP METADATA extension (RFC 5464), which allows per-mailbox, per-user data to be stored and accessed via IMAP commands.
See imap_metadata for configuration instructions.
Storing Metadata in SQL Dictionary
You can store metadata into a database. This works best with a dedicated table for storing the entries.
-- Since username is a primary key, it is required to have some value.
-- When empty, it means that the value applies to keys with 'shared/' prefix.
-- Keys with 'priv/' prefix are expected to have a non-empty username.
CREATE TABLE metadata (
username VARCHAR(255) NOT NULL DEFAULT '',
attr_name VARCHAR(255) NOT NULL,
attr_value TEXT,
PRIMARY KEY(username, attr_name)
);dict_server {
dict metadata {
driver = sql
sql_driver = mysql
dict_map $key {
sql_table = attr_priv
username_field = username
key_field attr_name {
value = $key
}
value_field attr_value {
}
}
}
}
mail_attribute {
dict proxy {
name = metadata
}
}SPECIAL-USE
No special-use mailboxes are configured by default. However, you can use @mailbox_defaults group to include the recommended default mailboxes with special-use flags configured. Alternatively, you can configure the mailbox settings explicitly with mailbox_special_use.
PREVIEW
Dovecot supports the PREVIEW extension (RFC 8970), retrieved via the IMAP FETCH command.
The extension is enabled by default. Preview text is generated during message delivery and is stored in the Dovecot index files.
NOTIFY
URLAUTH:
Set imap_urlauth_host and mail_attribute.
IMAP Hibernation
Dovecot supports moving connections that have issued IDLE to a special holding process, called imap-hibernate. This process is responsible for holding the idling connections until they issue some command that requires them to be thawed back into a (new) imap process. This way, memory and CPU resources are saved, since there is only one hibernation process.
Added: 3.3.0 Connections that are not in IDLE, but simply have no command running, can also be hibernated.
Configuration
IMAP hibernation is enabled by default in Dovecot Pro. imap_hibernate_timeout can be used to adjust the delay before moving users to imap-hibernate process.
A hibernated session survives a configuration reload if service_shutdown_clients_timeout allows it, and it's then continued with the new configuration, provided that the new configuration is compatible with the session. See reloading the configuration for the changes that are incompatible and disconnect the session instead.
Hibernating Connections Without IDLE
Added: 3.3.0
imap_hibernate_nonidle_timeout hibernates connections whose last command has finished this long ago, even if they are not in IDLE. This helps with clients that keep the connection open between commands, such as clients that poll with NOOP or STATUS. Input from the client moves the connection back to a new imap process, so the timeout should be longer than the clients' polling interval. Some commands are answered by the imap-hibernate process itself, see Commands Handled by imap-hibernate.
imap_hibernate_timeout = 5s
imap_hibernate_nonidle_timeout = 5minThings to know about hibernating connections without IDLE:
- New mails and flag changes that happened during the hibernation are sent to the client before the reply to its next command.
- If messages were expunged from the selected mailbox during the hibernation, the client is disconnected with
* BYE IMAP session state is inconsistent, please relogin.The client's next command hasn't started yet when the connection is moved back, so EXPUNGE replies can't be sent and the client's message sequence numbers can't be kept in sync. Theimap_client_unhibernatedevent'serrorfield is thenIMAP session state is inconsistent: Mailbox <name>: <count> messages expunged during hibernation, which can be used to count how often this happens. - The connection is not hibernated while there are expunges that the client hasn't been told about yet, e.g. after a FETCH command. Hibernation is tried again after the next command.
- The connection is not hibernated if the
delay-newmailimap_client_workaroundsis enabled. - The
imap-hibernateprocess disconnects the client after 30 minutes of inactivity, the same as the imap process does. - Connections using NOTIFY are not hibernated.
Commands Handled by imap-hibernate
Added: 3.3.0
The imap-hibernate process answers some commands itself, so that a new imap process doesn't need to be created for them. This helps especially with clients that stop and restart IDLE periodically, e.g. sending DONE, NOOP and IDLE every 29 minutes.
| Command | When answered by imap-hibernate |
|---|---|
DONE | imap_hibernate_nonidle_timeout is set and the connection could also be hibernated without IDLE (e.g. the delay-newmail imap_client_workarounds isn't enabled). The connection then stays hibernated without IDLE. Otherwise only when followed by IDLE or LOGOUT in the same input. |
IDLE | No mailbox change has been noticed since the hibernation. |
NOOP | No mailbox change has been noticed since the hibernation. |
CHECK | A mailbox is selected and no mailbox change has been noticed since the hibernation. |
LOGOUT | Always, unless IDLE is running. |
All other commands, and these commands when the conditions don't hold, move the connection back to a new imap process. If the same input contains both commands that can be answered and commands that can't, the answered commands' replies are sent first by the new imap process. While IDLE is running, DONE is answered only if all the following commands in the same input can also be answered. Otherwise the new imap process finishes the IDLE, so it can still send pending EXPUNGEs before it.
Things to know:
- A mailbox change is noticed using the same inotify watches that wake up a hibernated IDLE. Any change in the mailbox's index files counts, even if it wouldn't be visible to the client. Changes that are not noticed by inotify (e.g. changes done by another server on shared storage) are not noticed either, so
NOOPdoesn't show them. This is the same limitation that hibernated IDLE has. - Connections hibernated by
imap_hibernate_nonidle_timeoutwhile a mailbox is selected have no inotify watches, so theirNOOP,CHECKandIDLEalways move the connection back to an imap process. - After
DONEhas been answered byimap-hibernate, the connection is hibernated without IDLE, so messages expunged before the client's next command cause the relogin described in Hibernating Connections Without IDLE. This is whyDONEis answered only whenimap_hibernate_nonidle_timeoutis set. LOGOUTanswered byimap-hibernatedoesn't run themailbox_autoexpungecheck that the imap process does at logout. The check was already done before the connection was hibernated.- The
imap_command_finishedevent is sent also byimap-hibernatefor the commands it finishes. It has theimap-hibernatecategory, so it can be used to count how many commands were answered without an imap process.
Search Query Nesting Limit
Added: 3.3.0
The IMAP search key grammar is recursive: parenthesized key lists and the operators that take a key (NOT, OR, FUZZY, INTHREAD, MIMEPART PARENT/CHILD, ...) nest other keys inside them. Dovecot builds and walks the resulting search argument tree with one C stack frame per nesting level, so a query nested deeply enough would overflow the stack of the imap process.
Queries nested deeper than the allowed limit are rejected with:
a BAD Error in IMAP command SEARCH: Too much nesting in search queryThis affects every command that takes search arguments: SEARCH, UID SEARCH, SORT, THREAD, and the search arguments of STORE and FETCH. doveadm search and the other doveadm mailbox commands use the same search query parser and the same limit.
The limit is not a fixed constant and it is not configured in dovecot.conf. It is derived from the stack size limit (RLIMIT_STACK) of the process, so that a larger stack allows deeper nesting:
maximum nesting depth = max(32, RLIMIT_STACK / 2 / 4096)With the common 8 MB default stack this allows 1024 levels of nesting, which is far more than any normal client uses.
The other built-in and configurable resource limits are listed in Dovecot Limits.
Raising the Limit
Legitimate queries should never come close to the limit. If a client does need deeper nesting, raise the stack size limit of the Dovecot processes. Dovecot itself has no setting for this - the limit is inherited from the process that starts the master process.
With systemd, override it for the Dovecot service:
[Service]
LimitSTACK=16MThen run systemctl daemon-reload and restart Dovecot.
With a SysV style init script, raise it before starting Dovecot:
ulimit -s 16384Note that the stack size applies to every Dovecot process, so raising it increases the memory each process may use. Lowering it below the default has the opposite effect and lowers the nesting limit as well.