debops.imapproxy default variables

Sections

Packages and installation
Network configuration
PKI / TLS configuration
Imapproxy custom configuration
Configuration for other Ansible roles

Packages and installation 

imapproxy__packages

List of additional APT packages that should be installed with imapproxy.

imapproxy__packages: []

imapproxy__base_packages__base_packages

APT packages required for the imapproxy installation.

imapproxy__base_packages: [ 'imapproxy' ]

The FQDN address of the IMAP server which stores user mailboxes. The role first checks if a local Dovecot installation is present and, if so, uses the host FQDN. Next, the role uses DNS SRV resource records to try to find an IMAP server. Finally, imap.<domain> is used as a fallback.

The use of the FQDN instead of localhost is required for X.509 certificate verification.

imapproxy__imap_fqdn: '{{ ansible_fqdn
                          if (ansible_local|d() and ansible_local.dovecot|d() and
                             (ansible_local.dovecot.installed|d())|bool)
                          else imapproxy__imap_srv_rr[0]["target"]
                              if imapproxy__imap_srv_rr[0]["dig_srv_src"]|d("") != "fallback"
                              else imapproxy__imaps_srv_rr[0]["target"] }}'

imapproxy__imap_port

TCP port used for connecting to the IMAP server.

imapproxy__imap_port: '{{ "143"
                          if (imapproxy__imap_fqdn == ansible_fqdn)
                          else imapproxy__imap_srv_rr[0]["port"]
                              if imapproxy__imap_srv_rr[0]["dig_srv_src"]|d("") != "fallback"
                              else imapproxy__imaps_srv_rr[0]["port"] }}'

imapproxy__listen_address

The address on which imapproxy should listen for incoming connections, defaults to localhost for use with local webmail installations. If this is changed, please review the firewall variables to avoid security issues.

imapproxy__listen_address: '127.0.0.1'

imapproxy__listen_port

The port on which imapproxy should listen for incoming connections, defaults to 1143 for use with local webmail installations.

imapproxy__listen_port: '1143'

imapproxy__allow

List of IP addresses or CIDR subnets which are allowed to connect to imapproxy over the network, on all hosts in the Ansible inventory. This variable configures the firewall for all instances at the same time, for individual instance configuration you should modify the imapproxy__ferm__dependent_rules variable directly.

imapproxy__allow: []

imapproxy__group_allow

List of IP addresses or CIDR subnets which are allowed to connect to imapproxy over the network, on hosts in the specific Ansible inventory group. This variable configures the firewall for all instances at the same time, for individual instance configuration you should modify the imapproxy__ferm__dependent_rules variable directly.

imapproxy__group_allow: []

imapproxy__host_allow

List of IP addresses or CIDR subnets which are allowed to connect to imapproxy over the network, on specific hosts in the Ansible inventory. This variable configures the firewall for all instances at the same time, for individual instance configuration you should modify the imapproxy__ferm__dependent_rules variable directly.

imapproxy__host_allow: []

PKI / TLS configuration 

These variables configure the TLS support in imapproxy. Note that this should only be necessary if imapproxy is not installed on the same host as the IMAP server (e.g. the one managed by the debops.dovecot role). Also not that SSL is NOT supported out of the box by imapproxy, see /usr/share/doc/imapproxy/README.ssl for more details.

imapproxy__pki

Enable or disable support for TLS in imapproxy, managed by the debops.pki Ansible role.

imapproxy__pki: '{{ ansible_local.pki.enabled|d() | bool }}'

imapproxy__pki_path

Absolute path to the directory where PKI realms are located.

imapproxy__pki_path: '{{ ansible_local.pki.path|d("/etc/pki/realms") }}'

imapproxy__pki_realm

Name of the default PKI realm used by imapproxy.

imapproxy__pki_realm: '{{ ansible_local.pki.realm|d("domain") }}'

imapproxy__pki_ca

Name of the Root Certificate Authority certificate file used by imapproxy, relative to the PKI realm directory.

imapproxy__pki_ca: '{{ ansible_local.pki.ca|d("CA.crt") }}'

imapproxy__pki_crt

Name of the certificate file used by imapproxy, relative to the PKI realm directory.

imapproxy__pki_crt: '{{ ansible_local.pki.crt|d("default.crt") }}'

imapproxy__pki_key

Name of the private key file used by imapproxy, relative to the PKI realm directory.

imapproxy__pki_key: '{{ ansible_local.pki.key|d("default.key") }}'

imapproxy__tls_ca_path

Absolute path of the directory holding the Root Certificate Authority certificate file used in the imapproxy configuration.

imapproxy__tls_ca_path: '/etc/ssl/certs'

imapproxy__tls_ca_file

Absolute path of the Root Certificate Authority certificate file used in the imapproxy configuration.

imapproxy__tls_ca_file: '{{ imapproxy__tls_ca_path + "/ca-certificates.crt" }}'

imapproxy__tls_cert_file

Absolute path of the certificate file used in the imapproxy configuration.

imapproxy__tls_cert_file: '{{ (imapproxy__pki_path + "/" + imapproxy__pki_realm + "/" + imapproxy__pki_crt)
                            if imapproxy__pki|bool else "/etc/ssl/certs/ssl-cert-snakeoil.pem" }}'

imapproxy__tls_key_file

Absolute path of the private key file used in the imapproxy configuration.

imapproxy__tls_key_file: '{{ (imapproxy__pki_path + "/" + imapproxy__pki_realm + "/" + imapproxy__pki_key)
                           if imapproxy__pki|bool else "/etc/ssl/private/ssl-cert-snakeoil.key" }}'

imapproxy__tls_force

Imapproxy can autodetect whether to use STARTTLS by checking if the remote server advertises the LOGIN capability. A correctly configured IMAP server should not advertise this capability over remote connections.

imapproxy__tls_force: '{{ "no" if (imapproxy__imap_fqdn == ansible_fqdn or
                                   not imapproxy_pki|d(True))
                          else "yes" }}'

imapproxy__pki_hook_name

Name of the hook script which will be stored in hook directory.

imapproxy__pki_hook_name: 'imapproxy'

imapproxy__pki_hook_path

Directory with PKI hooks.

imapproxy__pki_hook_path: '{{ ansible_local.pki.hooks|d("/etc/pki/hooks") }}'

imapproxy__pki_hook_action

Specify how changes in PKI should affect imapproxy, only 'restart' is supported.

imapproxy__pki_hook_action: 'restart'

Imapproxy custom configuration 

These variables define the contents of the /etc/imapproxy.conf configuration file.

imapproxy__default_configuration

The default imapproxy configuration options defined by the role.

imapproxy__default_configuration:

  - name: 'server_hostname'
    comment: |
      This setting controls which IMAP server we proxy our connections to.
    value: '{{ imapproxy__imap_fqdn }}'

  - name: 'server_port'
    comment: |
      This setting specifies the port that server_hostname is listening on.
      This is the TCP port that we proxy inbound connections to.

      The original config file contains this note:
      If you are using SSL with IMAP Proxy, note that unless the server is
      highly non-standard, this should still be set to the server's normal,
      unencrypted IMAP port and should NOT be set to port 993, since IMAP
      Proxy uses STARTTLS to encrypt a "normal" IMAP connection.

      But note that there is nothing "non-standard" about only supporting
      IMAPS over 993 (see RFC8314).

      If the server is only available via (encrypted) port 993, please
      consult the README.ssl file for help.
    value: '{{ imapproxy__imap_port }}'

  - name: 'listen_address'
    comment: |
      This setting specifies which address the proxy server will bind to and
      accept incoming connections to.  If undefined, bind to all.
      Must be a dotted decimal IP address.
    value: '{{ imapproxy__listen_address }}'

  - name: 'listen_port'
    comment: |
      This setting specifies which port the proxy server will bind to and
      accept incoming connections from.
    value: '{{ imapproxy__listen_port }}'

  - name: 'connect_retries'
    comment: |
      This setting controls how many times we retry connecting to our server.
    value: '10'

  - name: 'connect_delay'
    comment: |
      This setting controls the delay between retries in seconds.
    value: '5'

  - name: 'cache_size'
    comment: |
      This setting determines how many in-core IMAP connection structures
      will be allocated.  As such, it determines not only how many cached
      connections will be allowed, but really the total number of simultaneous
      connections, cached and active.
    value: '3072'

  - name: 'cache_expiration_time'
    comment: |
      This setting controls how many seconds an inactive connection will be
      cached.
    value: '300'

  - name: 'proc_username'
    comment: |
      This setting controls which username the IMAP proxy process will run as.
      It is not allowed to run as "root".
    value: 'nobody'

  - name: 'proc_groupname'
    comment: |
      This setting controls which groupname the IMAP proxy process will run as.
    value: 'nogroup'

  - name: 'stat_filename'
    comment: |
      This is the path to the filename that the proxy server mmap()s to
      write statistical data to.  This is the file that pimpstat needs to
      look at to be able to provide its useful stats.
    value: '/var/run/pimpstats'

  - name: 'protocol_log_filename'
    comment: |
      protocol logging may only be turned on for one user at a time.  All
      protocol logging data is written to the file specified by this path.
    value: '/dev/null'

  - name: 'syslog_facility'
    comment: |
      The logging facility to be used for all syslog calls.  If nothing is
      specified here, it will default to LOG_MAIL.  Any of the possible
      facilities listed in the syslog(3) manpage may be used here except
      LOG_KERN.
    value: 'LOG_MAIL'

  - name: 'syslog_prioritymask'
    comment: |
      This configuration option is provided as a way to limit the verbosity
      of imapproxy.  If no value is specified, it will default to no priority
      mask and you'll see all possible log messages.  Any of the possible
      priority values listed in the syslog(3) manpage may be used here.  By
      default, you will see all possible log messages.
    value: 'LOG_WARNING'

  - name: 'send_tcp_keepalives'
    comment: |
      This determines whether the SO_KEEPALIVE option will be set on all
      sockets.
    value: 'no'

  - name: 'enable_select_cache'
    comment: |
      This configuration option allows you to turn select caching on or off.
      When select caching is enabled, imapproxy will cache SELECT responses
      from an IMAP server.
    value: 'no'

  - name: 'foreground_mode'
    comment: |
      This will prevent imapproxy from detaching from its parent process and
      controlling terminal on startup.
    value: 'no'

  - name: 'force_tls'
    comment: |
      Force imapproxy to use STARTTLS even if LOGIN is not disabled (unsecured
      connections will not be used).
    value: '{{ imapproxy__tls_force }}'

  - name: 'chroot_directory'
    comment: |
      This allows imapproxy to run in a chroot jail if desired.
      If commented out, imapproxy will not run chroot()ed.  If a directory is
      specified here, imapproxy will chroot() to that directory.
    value: '/var/lib/imapproxy/chroot'

  - name: 'preauth_command'
    comment: |
      Arbitrary command that can be sent to the server before
      authenticating users.  This can be useful to access non-
      standard IMAP servers such as Yahoo!, which requires
      (required?) the following command to be sent before
      authentication is allowed:
         ID ("GUID" "1")
      (See: http://en.wikipedia.org/wiki/Yahoo!_Mail&oldid=447046431#Free_IMAP_and_SMTPs_access )
      To use such a command, this setting should look like this:
         preauth_command ID ("GUID" "1")
      No matter what this command is, it is expected to return an
      OK response
    value: ''
    state: 'comment'

  - name: 'enable_admin_commands'
    comment: |
      Used to enable or disable the internal imapproxy administrative commands.
    value: 'no'

  - name: 'tls_ca_path'
    comment: |
      TLS configuration options
    value: '{{ imapproxy__tls_ca_path }}'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'tls_ca_file'
    value: '{{ imapproxy__tls_ca_file }}'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'tls_cert_file'
    value: '{{ imapproxy__tls_cert_file }}'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'tls_key_file'
    value: '{{ imapproxy__tls_key_file }}'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'tls_verify_server'
    value: 'yes'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'tls_ciphers'
    value: 'ALL:!aNULL:!eNULL'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'tls_no_tlsv1'
    comment: |
      Set any of these to "yes" if the corresponding TLS version is not
      sufficiently secure for your needs.
    value: 'yes'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'tls_no_tlsv1.1'
    value: 'yes'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'tls_no_tlsv1.2'
    value: 'no'
    state: '{{ "present" if imapproxy__pki|d(True) else "comment" }}'

  - name: 'auth_sasl_plain_username'
    comment: |
      Authenticate using SASL AUTHENTICATE PLAIN

      The following authentication username and password are used
      along with the username from the client as the authorization
      identity.  In order to avoid having the service wide open (no
      password needed from the client), the client is required to
      send the auth_shared_secret in leiu of a user password.

      NOTE: This functionality *assumes* that the server supports
            AUTHENTICATE PLAIN, and it does *not* verify this by
            looking at the server's capabilities list.
    value: ''
    state: 'comment'

  - name: 'auth_sasl_plain_password'
    value: ''
    state: 'comment'

  - name: 'auth_shared_secret'
    value: ''
    state: 'comment'

  - name: 'dns_rr'
    comment: |
      Use DNS round robin to cycle through all returned RRs we
      got when looking up the IMAP server with getaddrinfo().
      Default is no.
    value: 'yes'
    state: 'comment'

  - name: 'ipversion_only'
    comment: |
      Limit DNS requests to AF_INET or AF_INET6

      Set ipversion_only to 4 or 6 accordingly.
      Default if unset is AF_UNSPEC for both A and AAAA.
    value: '6'
    state: 'comment'

imapproxy__configuration

The imapproxy configuration options defined for all hosts in the Ansible inventory.

imapproxy__configuration: []

imapproxy__group_configuration

The imapproxy configuration options defined for hosts in a specific Ansible inventory group.

imapproxy__group_configuration: []

imapproxy__host_configuration

The imapproxy configuration options defined for a specific host in the Ansible inventory.

imapproxy__host_configuration: []

imapproxy__combined_configuration

The variable that combines other imapproxy configuration options and is used in the dovecot.conf template.

imapproxy__combined_configuration: '{{ imapproxy__default_configuration
                                        + imapproxy__configuration
                                        + imapproxy__group_configuration
                                        + imapproxy__host_configuration }}'

Configuration for other Ansible roles 

imapproxy__etc_services__dependent_list

Configuration for the debops.etc_services Ansible role.

imapproxy__etc_services__dependent_list:

  - name: 'imapproxy'
    port: '{{ imapproxy__listen_port }}'
    comment: 'IMAP Proxy Server'
    protocol: [ 'tcp' ]

imapproxy__ferm__dependent_rules

Configuration for the debops.ferm Ansible role.

imapproxy__ferm__dependent_rules:

  - name: 'imapproxy'
    type: 'accept'
    dport: [ 'imapproxy' ]
    saddr: '{{ imapproxy__allow + imapproxy__group_allow + imapproxy__host_allow }}'
    weight: '40'
    accept_any: False
    by_role: 'debops.imapproxy'

debops.imapproxy default variables

Packages and installation

Network configuration

PKI / TLS configuration

Imapproxy custom configuration

Configuration for other Ansible roles

Packages and installation 

Network configuration 

PKI / TLS configuration 

Imapproxy custom configuration 

Configuration for other Ansible roles 