path: root/doc/wiki/ConfigFile.txt

Dovecot Configuration File
==========================

Contents


 1. Dovecot Configuration File

     1. Basic syntax

     2. Sections

     3. Filters

     4. Including config files

     5. External config files

     6. Long lines

     7. Reading value from file

     8. Variable expansion

Basic syntax
------------

The syntax generally looks like this:

---%<-------------------------------------------------------------------------
# this is a comment

settings_key = settings_value
---%<-------------------------------------------------------------------------

If Dovecot doesn't seem to be reading your configuration correctly, use
'doveconf -n' to check how Dovecot actually parses it. You can also check more
complex configurations by providing filters, for example:'doveconf -n -f
service=imap -f local=10.0.0.1 -f remote=1.2.3.4'

Sections
--------

Sections look like this:

---%<-------------------------------------------------------------------------
section optional_name {
  section_setting_key = section_setting_value
  subsection optional_subname {
    subkey = subvalue
  }
}
---%<-------------------------------------------------------------------------

Note that sections must be currently written with the linefeeds as shown above.
So for example this doesn't work:

---%<-------------------------------------------------------------------------
section optional_name { key = value } # DOES NOT WORK
---%<-------------------------------------------------------------------------

The sections can be optionally named. This is especially useful if you want to
update the same section later on in the config. For example:

---%<-------------------------------------------------------------------------
namespace inbox {
  inbox = yes
}
# ...
# possibly included from another file:
namespace inbox {
  mailbox Trash {
    special_use = \Trash
  }
}
# The namespaces get merged into the same inbox namespace.
---%<-------------------------------------------------------------------------

Without naming the namespace it would have created a new namespace. The section
name may also sometimes be used as part of the settings instead of simply a
name. For example:

---%<-------------------------------------------------------------------------
service auth {
  unix_listener auth-master {
    # ..
  }
}
---%<-------------------------------------------------------------------------

Above the "auth-master" both uniquely identifies the section name, but also it
names the UNIX socket path.

Filters
-------

There are a few different filters that can be used to apply settings
conditionally. The filters look exactly like sections, which may be a bit
confusing. The currently supported filters are:

 * protocol <name>: Name of the service/protocol that is reading the settings.
   For example: imap, pop3, doveadm, lmtp, lda
 * remote <ip/network>: Remote client's IP/network. For non-TCP connections
   this will never match. For example 10.0.0.1 or 10.0.0.0/16.
 * local_name <name>: Matches TLS connection's SNI
   [https://en.wikipedia.org/wiki/Server_Name_Indication] name, if it's sent by
   the client. Commonly used to <configure multiple TLS certificates>
   [SSL.DovecotConfiguration.txt].
 * local <ip/range>: Locally connected IP/network. For non-TCP connections this
   will never match. For example 127.0.0.1 or 10.0.0.0/16.

These filters work for most of the settings, but most importantly auth settings
currently only support the protocol filter. Some of the other settings are also
global and can't be filtered, such as log_path.

An example, which uses all of the filters:

---%<-------------------------------------------------------------------------
local 127.0.0.1 {
  local_name imap.example.com {
     remote 10.0.0.0/24 {
       protocol imap {
         # ...
       }
     }
  }
}
---%<-------------------------------------------------------------------------

The nesting of the filters must be exactly in that order or the config parsing
will fail.

When applying the settings, the settings within the most-specific filters
override the less-specific filter's settings, so the order of the filters in
config file doesn't matter. For example:

---%<-------------------------------------------------------------------------
local 127.0.0.2 {
  key = 127.0.0.2
}
local 127.0.0.0/24 {
  key = 127.0.0.0/24
}
local 127.0.0.1 {
  key = 127.0.0.1
}
# The order of the above blocks doesn't matter:
# If local IP=127.0.0.1, key=127.0.0.1
# If local IP=127.0.0.2, key=127.0.0.2
# If local IP=127.0.0.3, key=127.0.0.0/24
---%<-------------------------------------------------------------------------

Similarly remote local filters override remote filters, which override
local_name filters, which override protocol filters. In some situations Dovecot
may also return an error if it detects that the same setting is being
ambiguously set by multiple matching filters.

Including config files
----------------------

The main dovecot.conf file can also include other config files:

---%<-------------------------------------------------------------------------
!include local.conf
!include /path/to/another.conf
!include conf.d/*.conf
---%<-------------------------------------------------------------------------

The paths are relative to the currently parsed config file's directory. For
example:

---%<-------------------------------------------------------------------------
# /etc/dovecot/dovecot.conf:
!include conf.d/imap.conf
# /etc/dovecot/conf.d/imap.conf:
!include imap2.conf
# /etc/dovecot/conf.d/imap2.conf is being included
---%<-------------------------------------------------------------------------

If any of the includes fail (e.g. file doesn't exist or permission denied), it
results in an error. It's not an error if wildcards don't result in any
matching files. To avoid these errors, you can use !include_try instead:

---%<-------------------------------------------------------------------------
!include_try passwords.conf
---%<-------------------------------------------------------------------------

Including a file preserves the context where it's included from. For example:

---%<-------------------------------------------------------------------------
protocol imap {
  plugin {
!include imap-plugin-settings.conf
  }
}
---%<-------------------------------------------------------------------------

External config files
---------------------

Due to historical reasons there are still some config files that are external
to the main dovecot.conf, which are typically named '*.conf.ext'. For example:

 * passdb/userdb { args } for ldap/sql points to a dovecot-ldap.conf.ext and
   dovecot-sql.conf.ext.
 * dict { .. } points to dovecot-dict-*.conf.ext

Although these external config files look similar to the main dovecot.conf
file, they have quite a lot of differences in details. Their parsing is done
with a completely different config parser, so things like filters, $variables,
!includes and<files don't work.

The external config files are also not loaded by the config process at startup,
but instead they're parsed whenever the value is being used. So the external
passdb/userdb files are loaded by auth process at startup, while the dict
config is loaded by dict process at startup.

Eventually these external config files will hopefully be removed.

Long lines
----------

It's possible to split the setting values into multiple lines. Unfortunately
this was broken for a long time, so outside *.conf.ext files this works only in
v2.2.22+:

---%<-------------------------------------------------------------------------
# This works in *.conf.ext files, but in the main dovecot.conf only with
v2.2.22+:
setting_key = \
  long \
  value
# equivalent to: "long value"
---%<-------------------------------------------------------------------------

All the whitespace between lines is converted to a single space regardless of
how many spaces or tabs are at the beginning of the line or before the '\'.
Even if there is zero whitespace a single space is added.

Reading value from file
-----------------------

It's possible to read the value for a setting from a file:

---%<-------------------------------------------------------------------------
key = </path/to/file
---%<-------------------------------------------------------------------------

The value is read exactly as the entire contents of the file. This includes all
the whitespace and newlines. The paths are relative to the currently parsed
config file's directory, similar to how !include works. The file is read
immediately whenever parsing the configuration file, so if it changes
afterwards it requires a configuration reload to see the changes. This
functionality is especially useful for reading SSL certificates and keys.

Variable expansion
------------------

It's possible to refer to other earlier settings as $name. For example:

---%<-------------------------------------------------------------------------
key = value1
key2 = $key value2
# Equivalent to key2 = value1 value2
---%<-------------------------------------------------------------------------

This is commonly used with mail_plugins settings to easily add more plugins
e.g. inside imap protocol:

---%<-------------------------------------------------------------------------
mail_plugins = acl quota
protocol imap {
  mail_plugins = $mail_plugins imap_acl imap_quota
}
---%<-------------------------------------------------------------------------

However, you must be careful with the ordering of these in the configuration
file, because the $variables are expanded immediately while parsing the config
file and they're not updated later. For example this is a common problem:

---%<-------------------------------------------------------------------------
# NON-WORKING EXAMPLE
# Enable ACL plugin:
mail_plugins = $mail_plugins acl
protocol imap {
  mail_plugins = $mail_plugins imap_acl
}
# Enable quota plugin:
mail_plugins = $mail_plugins quota
protocol imap {
  mail_plugins = $mail_plugins imap_quota
}
# The end result is:
# mail_plugins = " acl quota" - OK
# protocol imap {
#   mail_plugins = " acl imap_acl imap_quota" - NOT OK
# }
# v2.2.24+ also gives a warning about this:
# doveconf: Warning: /etc/dovecot/dovecot.conf line 8: Global setting
mail_plugins won't change the setting inside an earlier filter at
/etc/dovecot/dovecot.conf line 5 (if this is intentional, avoid this warning by
moving the global setting before /etc/dovecot/dovecot.conf line 5)
---%<-------------------------------------------------------------------------

This is because the second mail_plugins change that added "quota" globally
didn't update anything inside the existing 'protocol { .. }' or other filters.

Some variables exist in the plugin section only, such as sieve_extensions.
Those variables *cannot* be referred to, that is '$sieve_extensions' won't
work.

(This file was created from the wiki on 2019-06-19 12:42)