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.

SQL Schema

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

/etc/dovecot/dovecot.conf

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

Set mailbox_list_index = yes.

URLAUTH:

Set imap_urlauth_host and mail_attribute.

IMAP Hibernation

WARNING

This is not supported on kqueue based systems currently, such as FreeBSD.

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: 2.4.6 Connections that are not in IDLE, but simply have no command running, can also be hibernated.

Configuration

imap_hibernate_timeout specifies the delay before moving users to imap-hibernate process. This requires inter-process communication between imap and 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.

imap_hibernate_timeout = 5s

service imap {
  # Note that this change will allow any process running as
  # $SET:default_internal_user (dovecot) to access mails as any other user.
  # This may be insecure in some installations, which is why this isn't
  # done by default.
  unix_listener imap-master {
    user = $SET:default_internal_user
  }
}

# The following is the default already
service imap {
  extra_groups = $default_internal_group
}
service imap-hibernate {
  unix_listener imap-hibernate {
    mode = 0660
    group = $default_internal_group
  }
}

Hibernating Connections Without IDLE

Added: 2.4.6

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. Any input from the client moves the connection back to a new imap process, so the timeout should be longer than the clients' polling interval.

imap_hibernate_timeout = 5s
imap_hibernate_nonidle_timeout = 5min

Things 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. The imap_client_unhibernated event's error field is then IMAP 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_workarounds is enabled.
• The imap-hibernate process disconnects the client after 30 minutes of inactivity, the same as the imap process does.
• Connections using NOTIFY are not hibernated.

Search Query Nesting Limit

Added: 2.4.6

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 query

This 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=16M

Then run systemctl daemon-reload and restart Dovecot.

With a SysV style init script, raise it before starting Dovecot:

ulimit -s 16384

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