Edit File: 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 2018-02-28 04:42)