Getting started

Default setup

If you don't specify any configuration values, the role will attempt to automatically detect which IMAP server to connect to and listen for incoming connections on localhost, port 1143.

The defaults are based on the assumption that imapproxy will be installed on the same host as the service using imapproxy. If you want to proxy incoming connections from an external host, this can be controlled via the imapproxy__listen_address and imapproxy__listen_port variables. Note that external access also needs to be allowed using the firewall variables (imapproxy__allow, imapproxy__host_allow and imapproxy__group_allow) if you are using the Ferm firewall.

If you want to manually define the server to proxy connections to, use the imapproxy__imap_fqdn and imapproxy__imap_port variables.

SSL support

While imapproxy supports TLS out of the box (using values from the debops.pki role, if enabled), it does not have native support for SSL.

The recommended setup is either to run imapproxy on the same host as the IMAP server (meaning that TLS/SSL is not necessary as no proxy <-> IMAP traffic is sent over the network) or to setup the IMAP server to allow TLS traffic using explicit TLS.

If you are trying to proxy to an IMAP server that is only available using IMAPS (usually port 993), manual configuration will be necessary. The authors of imapproxy suggest setting up a SSL tunnel (e.g. using stunnel).

See /usr/share/doc/imapproxy/README.ssl in the imapproxy package for more details.

IMAP server detection

The role first checks if debops.dovecot is installed on the same host. If so, the local IMAP server will be used.

In the alternative, the role detects the preferred IMAP server by checking the DNS SRV resource records (defined by RFC 6186), looking for the IMAP or IMAPS services. The example DNS resource records used by the role are:

_imap._tcp           SRV 0 1 143  imap.example.org.
_imaps._tcp          SRV 0 1 993  imap.example.org.

At the moment only a single SRV resource record is supported by the role.

If both SRV resource records and local Ansible facts are not available, the debops.imapproxy role will fall back to using static subdomains for the respective services, based on the host domain:

IMAP:  imap.example.org

This allows for deployment of the proxy on a separate host or VM.

Example inventory

To install and configure imapproxy on a host, it needs to be present in the [debops_service_imapproxy] Ansible inventory group. You may want to use the role on the same host that is also providing the Dovecot and webmail (e.g. Roundcube) services.

[debops_all_hosts]
webmail

[debops_service_dovecot]
webmail

[debops_service_imapproxy]
webmail

Example playbook

The following playbook can be used with DebOps. If you are using these role without DebOps you might need to adapt them to make them work in your setup.

---

- name: Install and manage imapproxy
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_imapproxy' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  roles:

    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services' ]
      etc_services__dependent_list:
        - '{{ imapproxy__etc_services__dependent_list }}'

    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ imapproxy__ferm__dependent_rules }}'

    - role: imapproxy
      tags: [ 'role::imapproxy', 'skip::imapproxy' ]

This playbook is also shipped with DebOps at ansible/playbooks/service/imapproxy.yml.

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::imapproxy

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

role::imapproxy:pkg

Run tasks related to system package installation.

role::imapproxy:config

Run tasks related to the imapproxy configuration.