DEBOPS.DOVECOT(5)

NAME
debops.dovecot - Manage Dovecot IMAP/POP3 server using Ansible

SYNOPSIS

debops service/dovecot [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

This Ansible <https://www.ansible.com/> role allows you to install and manage the Dovecot <https://dovecot.org/> IMAP/POP3 server to allow remote access to your mail boxes. It integrates with the ansible-pki <https://github.com/debops/ansible-pki/> role, so you can easily protect your access via secure TLS connection.

Additionally it allows you to configure a sieve <http://sieve.info/> service which allows you to store server-side rules for mail filtering.

GETTING STARTED

  Default setup

If you don't specify any configuration values, the role will setup an IMAP and IMAPS service using the certificates provided by ansible-pki <https://github.com/debops/ansible-pki>. It will further use the ansible-ferm <https://github.com/debops/ansible-ferm> role to open the required network ports with iptables: 143 (IMAP+STARTTLS) and 993 (IMAPS). Every user account which is able to login via PAM, can then also login via IMAP and access its mails stored as an mbox file in /var/mail/<username>.

  LDAP support

When the LDAP environment is configured on a host, the debops.dovecot role will automatically switch from system account authentication to LDAP-based accounts.

  Example inventory

You can install Dovecot on a host by adding it to the [debops_service_dovecot] group in your Ansible inventory:

[debops_service_dovecot]
hostname

  Example playbook

Here's an example playbook which uses debops.dovecot role to install Dovecot:

---
- name: Manage Dovecot service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_dovecot' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Prepare dovecot environment
      import_role:
        name: 'dovecot'
        tasks_from: 'main_env'
      tags: [ 'role::dovecot', 'role::secret', 'role::ferm' ]
    - name: Prepare postfix environment
      import_role:
        name: 'postfix'
        tasks_from: 'main_env'
      vars:
        postfix__dependent_maincf:
          - role: 'dovecot'
            config: '{{ dovecot__postfix__dependent_maincf }}'
        postfix__dependent_mastercf:
          - role: 'dovecot'
            config: '{{ dovecot__postfix__dependent_mastercf }}'
      tags: [ 'role::postfix', 'role::secret', 'role::ferm' ]
  roles:
    - role: secret
      tags: [ 'role::secret', 'role::postfix' ]
      secret__directories:
        - '{{ postfix__secret__directories }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ dovecot__ferm__dependent_rules }}'
    - role: postfix
      tags: [ 'role::postfix', 'skip::postfix' ]
      postfix__dependent_maincf:
        - role: 'dovecot'
          config: '{{ dovecot__postfix__dependent_maincf }}'
      postfix__dependent_mastercf:
        - role: 'dovecot'
          config: '{{ dovecot__postfix__dependent_mastercf }}'
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::ldap' ]
      python__dependent_packages3:
        - '{{ ldap__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ ldap__python__dependent_packages2 }}'
    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]
      ldap__dependent_tasks:
        - '{{ dovecot__ldap__dependent_tasks }}'
    - role: dovecot
      tags: [ 'role::dovecot', 'skip::dovecot' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::dovecot
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

GUIDES AND EXAMPLES

  Check Dovecot IMAP config is running

Take a look at the official Dovecot documentation on how to test an IMAP connection, Auth and Inbox listing. See Test Dovecot Installation <https://wiki2.dovecot.org/TestInstallation>.

  Using maildir mail storage format

If you want to use maildir instead of mbox you first have to make sure, that your mail delivery agent is storing the incoming mails in the maildir format. If you are using the ansible-postfix <https://github.com/debops/ansible-postfix> role, this can be achieved by setting the following configuration:

•   Make sure local is in your postfix capabilities list

•   Set the postfix home_mailbox configuration value to the desired path. It must end with a slash / to indicate the maildir format:

    postfix_local_maincf: |
      home_mailbox = Maildir/

    This example will store the mails in the Maildir/ folder within the user's home directory. You can make dovecot looking for this maildir by setting:

    dovecot_mail_location: 'maildir:~/Maildir'

    The dovecot_mail_location variable corresponds to the mail_location statement in the dovecot configuration file, so you can also set much more advanced values. Check the dovecot mail_location <https://wiki2.dovecot.org/MailLocation/> documentation for more examples.

  Enable server-side mail filtering with sieve

Sieve <https://wiki2.dovecot.org/Pigeonhole/Sieve/> is a programming language to define mail filtering rules. The rules are stored as text files on the mail server and can be managed by a client via ManageSieve <https://wiki2.dovecot.org/Pigeonhole/ManageSieve/> network protocol. Dovecot provides sieve support via Pigeonhole sieve interpreter.

To enable the ManageSieve protocol in your Dovecot role you have to add it to the dovecot_protocols list:

dovecot_protocols: [ 'imap', 'managesieve' ]

It will create a network listener on port 4190 which requires STARTTLS for authentication. You can restrict access to this port by explicitly listing the networks or hosts which are allowed to connect:

dovecot_managesieve_config_map:
  login-service:
    inet_listener:
      sieve:
        allow: [ '192.168.1.0/24' ]

By default every host can connect.

The sieve filter rules are applied before delivering the mail to the user's mailbox. There are various ways for mail delivery but only a few of them respect the sieve filters. By default DebOps would simply use Postfix to write the mail. However, Postfix doesn't know about sieve. Therefore you have to manually add the following configuration to each user's ~/.forward file, to hook-in the Dovecot LDA (local delivery agent):

| "/usr/lib/dovecot/dovecot-lda"

To enable the sieve filter with the Dovecot LDA you further have to enable the plugin for the corresponding protocol:

dovecot_lda_config_map:
  protocol:
    mail_plugins: '$mail_plugins sieve'

The Dovecot LDA would then deliver the mail after enquiring the sieve files. Alternatively mail can be delivered via LMTP protocol, which also supports sieve filtering (see section below).

By default the Dovecot sieve plugin will store the user defined rules as plain text files in the ~/sieve/ folder. They can be managed directly via file system, by a mail client which supports the ManageSieve protocol or alternatively by a tool like sieve-connect <https://github.com/philpennock/sieve-connect/>.

  Enable LMTP to deliver mails from Postfix

LMTP <https://wiki2.dovecot.org/LMTP> is a reliable, scalable and secure protocol to deliver mails into virtual mail boxes. It is implemented by Dovecot as an alternative to the Dovecot LDA and also supports most mail plugins, such as sieve filtering.

It can be enabled by adding it to the dovecot_protocols list. E.g.:

dovecot_protocols: [ 'imap', 'lmtp' ]

Without further configuration, this will instruct DebOps to setup a LMTP unix socket, which is then used by Postfix for mail delivery. In this case Postfix will be automatically added as a dependency and configured accordingly.

To enable mail plugins specifically to LMTP only, they can be added to the mail_plugins parameter in dovecot_lmtp_config_map:

dovecot_lmtp_config_map:
  protocol:
    mail_plugins: '$mail_plugins sieve'

In case your Postfix is not running on the same machine, you can enable a network socket where the LMTP service is listening on. E.g.:

dovecot_lmtp_listeners: [ 'lmtp' ]

Then define its properties:

dovecot_lmtp_config_map:
  service:
    inet_listener:
      lmtp:
        port: 24
        allow: [ '192.168.1.0/24' ]
        address: 192.168.1.123

This would bind LMTP to the local address 192.168.1.123 on port 24. Additionally, access is restricted by ansible-ferm <https://github.com/debops/ansible-ferm> to the given network. When using the LMTP network socket, you have to configure Postfix independently by setting e.g.:

postfix_local_maincf: |
  virtual_transport = lmtp:inet:192.168.1.123:24

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_imap_config_map

Configuration dictionary related to the IMAP protocol configuration. Every configuration key is optional and overwrites the default values implicitly used by Dovecot. Each section service imap-login, service imap and protocol imap is defined as a YAML dict with the corresponding key:

login-service
    Configuration settings under this key will go into the service imap-login {} section which defines the pre-login process handling. Possible keys are inet_listener and upstream Dovecot options such as service_count or process_min_avail. More information about the login setup can be found at the Dovecot Login Process <https://wiki2.dovecot.org/LoginProcess> page.

inet_listener
    Will create a network listener definition. Accepts further YAML dicts with the listener name as key.

    The listener name itself must reference a dict defining listener properties such as port (network port), allow (address/subnet restrictions) or address (listen address). More information about the inet_listener setup can be found at the Dovecot inet_listeners <https://wiki2.dovecot.org/Services#inet_listeners> page.

unix_listener
    Will create a Unix socket definition. The key name of the listeners corresponds to the socket path.

    The listener name itself must reference a dict defining socket properties such as owner (socket owner), group (socket group) or mode (access mode). More information about the unix_listener setup can be found at the Dovecot unix_listeners <https://wiki2.dovecot.org/Services#unix_listeners_and_fifo_listeners> page.

service
    Configuration settings under this key will go into the service imap {} section which defines the post-login process handling. Possible keys are the upstream Dovecot options such as process_limit or vsz_limit. More information about the IMAP service options can be found at the Dovecot IMAP Service <https://wiki2.dovecot.org/Services#imap.2C_pop3.2C_submission.2C_managesieve> page.

protocol
    Configuration settings under this key will go into the protocol imap {} section which defines general protocol behaviour. Possible keys are the upstream Dovecot options such as mail_max_userip_connections or mail_plugins.

  Example

Restrict access to the IMAP service to 192.168.1.0/24. Always keep a process waiting for more connections, restrict maximal number of IMAP processes to 512 and allow 15 IMAP connections for each user:

dovecot_imap_config_map:
  login-service:
    inet_listener:
      imap:
        access: [ '192.168.1.0/24' ]
    process_min_avail: 1
  service:
    process_limit: 512
  protocol:
    mail_max_userip_connections: 15

  dovecot_imap_listeners

List of IMAP network listener names which will be used to decide which default listeners to create. Their configuration can be customized via dovecot_imap_config_map.

  Examples

Possible configuration options for enabling IMAP:
Service | dovecot_protocols | dovecot_imap_listeners | dovecot_pki
Port 143 (plain) | [ 'imap' ] | [ 'imap' ] | False
Port 143 (StartTLS) | [ 'imap' ] | [ 'imap' ] | True
Port 143 (StartTLS) + 995 (SSL) | [ 'imap' ] | [ 'imap', 'imaps' ] | True
Port 995 (SSL) | [ 'imap' ] | [ 'imaps' ] | True

  dovecot_pop3_config_map

Configuration dictionary related to the POP3 protocol configuration. Please to the dovecot_imap_config_map for a description of the dict layout.

  dovecot_pop3_listeners

List of POP3 network listener names which will be used to decide which default listeners to create. Their configuration can be customized via dovecot_pop3_config_map.

  dovecot_lmtp_config_map

Configuration dictionary related to the LMTP protocol configuration. Please refer to the dovecot_imap_config_map for a description of the dict layout.

In contrast to the other protocol maps, LMTP inet_listeners must always be listed in dovecot_lmtp_config_map and define the port property, as Dovecot doesn't define a default port for LMTP network listeners.

  dovecot_lmtp_listeners

List of LMTP network and unix listener names which will be created. The LMTP listeners configuration works a bit different from other network protocols. Each listeners mentioned in dovecot_lmtp_listeners must also be defined in dovecot_lmtp_config_map.

  dovecot_lda_config_map

Configuration dictionary related to the Dovecot LDA protocol configuration. The only valid key is protocol which references a YAML dict defining the protocol lda {} section. The protocol dict then accepts the upstream Dovecot configuration options such as mail_plugins.

  dovecot_auth_config_map

Configuration dictionary related to user authentication when sending emails over the SMTP protocol configuration. Postfix uses the /var/spool/postfix/private/auth UNIX socket to communicate with Dovecot in order to authenticate an user, while sending emails. See also smtpd_sasl_type and smtpd_sasl_path values in postconf__postfix__dependent_maincf.

Please refer to the dovecot_imap_config_map for a description of the dict layout.

  dovecot_auth_listeners

List of AUTH unix listener names which will be created. The AUTH listeners configuration works like the dovecot_lmtp_listeners. Each listeners mentioned in dovecot_auth_listeners must also be defined in dovecot_auth_config_map.

  Example

Enable sieve mail plugin with local mail delivery:

dovecot_lda_config_map:
  protocol:
    mail_plugins: '$mail_plugins sieve'

  dovecot_managesieve_config_map

Configuration dictionary related to the ManageSieve protocol configuration. Please refer to the dovecot_imap_config_map for a description of the dict layout.

  dovecot_managesieve_listeners

List of ManageSieve network listener names which will be used to decide which default listeners to create when managesieve is enabled in dovecot_protocols. Their configuration can be customized via dovecot_managesieve_config_map.

  Example

If you want to enable a second ManageSieve listener, you need to add its name to the dovecot_managesieve_listeners list and define its properties in the dovecot_managesieve_config_map. For example to bind a second listener to a specific address on port 2000:

dovecot_managesieve_listeners: [ 'sieve', 'sieve_deprecated' ]
dovecot_managesieve_config_map:
  login-service:
    inet_listeners:
      sieve_deprecated:
        address: 192.168.1.42
        port: 2000

  dovecot_postfix_transport

LMTP socket name which will be configured in Postfix to send mails for delivery. The value is a file system path relative to /var/spool/postfix Make sure there is a corresponding LMTP unix_listener defined in dovecot_lmtp_config_map and enabled via dovecot_lmtp_listeners. The LMTP transport target will only be configured in Postfix when 'lmtp' is enabled in dovecot_protocols.

For most people the default configuration will be sufficient.

AUTHOR
Reto Gantenbein, Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others