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.

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.

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

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.