Default variables: configuration

Some of debops.dovecot default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

dovecot__features

Currently supported features for dovecot__features are:

imap: IMAP4rev2 (RFC 9051) with explicit TLS support via STARTTLS, typically using port 143.
imaps: IMAP4rev2 with implicit TLS support, typically using port 993.
pop3: POP3 (RFC 1939, extensions from RFC 2449 and authentication from RFC 1734) with explicit TLS support via STARTTLS, typically using port 110.
pop3s: POP3 with implicit TLS support, typically using port 995.
sieve: Support for mail filtering/sorting using Sieve (RFC 5228) scripts and the ManageSieve protocol (RFC 5804, both with various extensions from other RFCs), the latter typically using port 4190. See Dovecot's ManageSieve Documentation for further details.
quota: Support for per-user mail quotas. See Dovecot's Quota Plugin Documentation for further details.
dsync: Support for two-directional/pairwise dsync synchronization between two dovecot servers using dovecot's own dsync protocol, typically using port 12345. See Dovecot's Replication Documentation for further details.

Note that imaps and pop3s (implicit TLS) are recommended over imap and pop3 (explicit TLS) by RFC 8314. Furthermore, LMTP is recommended over LDA by the Dovecot project.

DSync Replication

Dovecot supports master/master replication using dsync. The replication is done asynchronously, so high latency between the replicas isn't a problem. The replication is done by looking at Dovecot index files (not what exists in the filesystem), so no mails get lost due to filesystem corruption or an accidental deletion, they will simply be replicated back.

Replication works only between server pairs. Currently dsync is only supported together with a virtual email user since dsync would need root access otherwise.

The most important configuration variable is dovecot__dsync_host, which needs to be set to point to the other server for each server in a sync pair. Assuming that you have two servers, named mail1.example.com and mail2.example.com, setting something like this in your Ansible inventory should be sufficient:

dovecot__dsync_host: '{{ "mail1.example.com"
                         if ansible_fqdn == "mail2.example.com"
                         else "mail2.example.com" }}'

Other variables are dovecot__dsync_port, dovecot__dsync_replica, dovecot__dsync_password_path and dovecot__dsync_password, but these should all have sensible defaults for most installations.

For more information, see the Dovecot Replication wiki page.

dovecot__user_accounts

Currently supported mechanisms for dovecot__user_accounts are:

deny: Deny access for a statically defined list of users (see dovecot__deny_users).
system: Mail users are Linux system users.
mysql: Mail users are stored in a MySQL/MariaDB database (see SQL User Databases below).
pgsql: Mail users are stored in a PostgreSQL database (see SQL User Databases below).
sqlite: Mail users are stored in a SQLite database (see SQL User Databases below).
ldap: Mail users are stored in the LDAP directory.
passwdfile: Users and passwords are stored in a file.
checkpassword: Users and passwords are stored in an external program.

SQL User Databases

Users can be stored in an external SQL database (see dovecot__user_accounts above). In order to do so, a database-driver specific connection string needs to be defined in dovecot__sql_connect. The parameters are generally provided as a space-delimited string of parameter=value pairs (which means that it is not possible to use spaces in parameters), with the possible parameters defined by the used database type:

pgsql

host
The host on which the database server is running.

port
The port on which the database server is listening.

user
The username to use when connecting to the database.

password
The password to use when connecting to the database.

dbname
The name of the database to use.

maxconns
The number of connections to create to the database (default 5).

mysql

The basic options (host, port, user, password, dbname) are the same as for pgsql, additional settings include:

client_flags
See the MySQL manual.

ssl_ca, ssl_ca_path
Set either one or both to enable SSL.

ssl_cert, ssl_key
For sending client-side certificates to the server.

ssl_cipher
Sets the minimum allowed cipher security (default: HIGH).

ssl_verify_server_cert
Verifies that the name in the server SSL certificate matches the host (default: no).

option_file
Read options from the given file instead of the default my.cnf location.

option_group
Read options from the given group (default: client).

You can connect to UNIX sockets by using host=/var/run/mysql.sock.

sqlite: Only one parameter is supported - the path to the database file (which is defined without the parameter=value format).

Examples:

# pgsql
dovecot__sql_connect: 'host=192.168.1.1 dbname=users'
# mysql
dovecot__sql_connect: 'host=sql.example.com dbname=virtual user=virtual password=blarg'
# sqlite
dovecot__sql_connect: '/etc/dovecot/authdb.sqlite'

The database should have a structure like this:

CREATE TABLE `users` (
  `userid` varchar(128) NOT NULL,
  `domain` varchar(128) NOT NULL,
  `password` varchar(128) NOT NULL,
  `home` varchar(255) NOT NULL,
  `uid` int(11) NOT NULL,
  `gid` int(11) NOT NULL,
  `active` char(1) NOT NULL DEFAULT 'Y',
  `maildir` varchar(255) NOT NULL
);

Other configuration parameters of interest are dovecot__sql_default_pass_scheme, dovecot__sql_password_query, dovecot__sql_user_query, and dovecot__sql_iterate_query.

dovecot__configuration

The dovecot__*_configuration variables define the contents of the /etc/dovecot/dovecot.conf configuration file. The variables are merged in the order defined by the dovecot__combined_configuration variable, which allows modification of the default configuration through the Ansible inventory.

See the dovecot configuration documentation for details on the possible configuration parameters.

Examples

See dovecot__default_configuration variable for an example of existing configuration.

Autosubscribe users to the Junk mailbox:

dovecot__group_configuration:

  - section: 'mailbox_namespaces'
    options:

      - name: 'namespace inbox'
        options:

          - name: 'mailbox Junk'
            options:

              - name: 'auto'
                value: 'subscribe'

Rename the Junk mailbox to INBOX.Spam:

dovecot__group_configuration:

  - section: 'mailbox_namespaces'
    options:

      - name: 'namespace inbox'
        options:

          - name: 'mailbox Junk'
            state: 'absent'

          - name: 'mailbox INBOX.Spam'
            options:

              - name: 'auto'
                value: 'subscribe'

              - name: 'special_use'
                value: '\Junk'

Syntax

The variables contain a list of YAML dictionaries, each dictionary can have the following parameters:

section

Required. Name of the section to create in the /etc/dovecot/dovecot.conf file. This parameter is used as an "anchor", configuration entries with the same section are combined together and affect each other in order of appearance.

title

Optional. A short description of a given configuration section. If not defined, the section name itself will be used.

state

Optional. If not specified or present, the configuration section will be generated. If hidden, the section will be generated, but without a section header. If absent, ignore or init, the configuration section will not be generated. If comment, the section will be generated but commented out.

weight

Optional. A positive or negative number which can be used to affect the order of sections in the generated configuration file. Positive numbers add more "weight" to the section making it appear "lower" in the file; negative numbers subtract the "weight" and therefore move the section upper in the file.

comment

Optional. This parameter can be used to provide a short description which will be included in the generated configuration file.

options

Required. A list of dovecot configuration options for a given section.

Note that the options parameters can be used recursively to generate configuration blocks of arbitrary depth (as illustrated in the example above).

The options can be specified with the following parameters:

name: Required. The name of a given dovecot configuration option for a given section. Options with the same section and name hierarchy will be merged in order of appearance.
option: Optional. An alternative to name to be used as the key in the key = value pairs written to the configuration.
value: Either value or options is required. This defines the value of a given configuration option. It can be either a string, a boolean, a number, or a YAML list (elements will be joined with commas).
options: Either value or options is required. This parameters takes a list of configuration sub-options, thus allowing options to be used recursively to generate configuration blocks of arbitrary depth (as illustrated in the example above).
raw: Optional. String or YAML text block which will be included in the configuration file "as is". If this parameter is specified, the name and value parameters are ignored - you need to specify the entire line(s) with configuration option names as well.
state: Optional. Same values as documented above.
comment: Optional. String or YAML text block that contains comments about a given configuration option.