DEBOPS.IMAPPROXY(5)

NAME
debops.imapproxy - Manage imapproxy with Ansible

SYNOPSIS

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

DESCRIPTION

The debops.imapproxy Ansible role manages imapproxy <http://www.imapproxy.org/>, an IMAP proxy server which is used primarily to improve webmail performance.

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 by using local Ansible facts. If so, the local IMAP server will be used.

In the alternative, the role detects the preferred IMAP server by using DNS SRV Records for the following services:

_imap._tcp.{{ imapproxy__domain }} (default port 143)
_imaps._tcp.{{ imapproxy__domain }} (default port 993)

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

Finally, the role will fall back to using static domain names for the respective services, based on the host domain (imapproxy__domain):

IMAP:  imap.example.org:143

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.

DEFAULT VARIABLE DETAILS

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

  imapproxy__configuration

The imapproxy__*_configuration variables define the contents of the /etc/imapproxy.conf configuration file. The contents are defined using YAML data structures and converted to a valid configuration file via the role template.

The imapproxy__*_configuration variables are implemented using the universal configuration syntax.

/etc/imapproxy.conf is a simple configuration file which contains configuration parameters in a key value syntax (note: not key = value), meaning that the universal configuration variables are also a simple list of name and value parameters which end up as key value in /etc/imapproxy.conf.

imapproxy__default_configuration already contains a list of all the configuration parameters which are supported by imapproxy and may appear in /etc/imapproxy.conf together with comments documenting the parameters.

If you need to override any parameter, you can do so by changing imapproxy__configuration, imapproxy__group_configuration or imapproxy__host_configuration according to your needs.

  Examples

Changing a couple of configuration options:

imapproxy__configuration:
  - name: 'dns_rr'
    value: 'yes'
    state: 'present'
  - name: 'chroot_directory'
    state: 'comment'

You can see more examples in the imapproxy__default_configuration variable.

  Syntax

The imapproxy configuration options can be configured using a number of configuration entries, each containing a name parameter and a number of additional parameters (see the example above).

Supported parameters are:

name
    Required. imapproxy configuration option name. Configuration entries with the same name parameter are merged in order of appearance; this can be used to change configuration options conditionally.

    If the option parameter is specified, it is used instead of the name parameter as the key value in the generated configuration file.

value
    Optional. The value of the imapproxy configuration option. It can be specified as a string, a YAML list, True or False boolean, a null value, a positive or negative number. if the value parameter is not specified, the result will be empty.

    The value parameters from multiple configuration entries override each other.

raw Optional. String or YAML text block with text which will be included in the generated configuration file "as is". If the raw parameter is defined, it takes precedence over value parameter.

state
    Optional. If not specified or present, a given imapproxy option will be present in the configuration file. If absent, a given option will be removed from the configuration file (or not included if not present). If init, the configuration option will be prepared, but will not be active and won't show up on the generated configuration file - this can be used to prepare configuration that will be activated conditionally in another configuration entry. If ignore, a given configuration entry will not be evaluated during role execution. If comment, a given imapproxy configuration option will be present in the generated file, but commented out.

comment
    Optional. String or YAML text block with comments about a given configuration option.

copy_id_from
    Optional. Copy the internal "id" of a configuration option specified by the name parameter to the current configuration option. This parameter can be used to reorder configuration options relative to a specific option.

weight
    Optional. Positive or negative number which defines the additional "weight" of an option. Smaller or negative weight will move the option higher in the configuration file, Bigger weight will move the configuration option lower in the configuration file.

value_cast
    Optional. Specify the type of a given value to use in the configuration file. Supported types: int/integer, str/string, float, null/none, bool/boolean. This parameter is onlu useful when the value is defined using another variable, in which case the type information is not preserved by Jinja templating.

AUTHOR
David Härdeman, Reto Gantenbein

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