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 parmeters 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 substract 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.