---

  os_users:

    - name: admin

      uid: 1000

      additional_groups:

        - sudo

      authorized_keys:

        - "{{ lookup('file', '/home/admin/.ssh/id_rsa.pub') }}"

      password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'

    - name: john

      uid: 1001

      password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'

  os_groups:

    - name: localusers

      gid: 2500

  common_packages:

    - emacs23-nox

    - screen

    - debconf-utils

  ca_certificates:

    "truststore": "{{ lookup('file', '../certs/truststore.pem') }}"

  incoming_connection_limit: 2/second

  incoming_connection_limit_burst: 6

  prompt_colour: light_green

  prompt_id: PROD

.. _ldap_client:

LDAP Client

-----------

The ``ldap_client`` role can be used for setting-up an OpenLDAP client on

destination machine.

The role implements the following:

* Installs OpenLDAP client tools.

* Sets-up global configuration file for OpenLDAP clients at /etc/ldap/ldap.conf.

Parameters

~~~~~~~~~~

**ldap_client_config** (list, optional, ``[]``)

  A list of configuration options that should be put into the LDAP configuration

  file. Each item is a dictionary with the following options defining the

  configuration parameter:

  **comment** (string, mandatory)

    Comment that will be shown in the file just above the configuration option.

  **option** (string, mandatory)

    Name of configuration option.

  **value** (string, mandatory)

    Value for configuration option.

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 9 (Stretch)

Examples

~~~~~~~~

Here is an example configuration for setting some common LDAP client options:

.. code-block:: yaml

  ---

  ldap_client_config:

    - comment: Set the base DN

      option: BASE

      value: dc=example,dc=com

    - comment: Set the default URI

      option: URI

      value: ldap://ldap.example.com/

    - comment: Set the truststore for TLS/SSL

      option: TLS_CACERT

      value: /etc/ssl/certs/example_ca.pem

    - commment: Force basic server certificate verification

      option: TLS_REQCERT

      value: demand

    - comment: Disable CRL checks for server certificate

      option: TLS_CRLCHECK

      value: none

LDAP Server

-----------

The ``ldap_server`` role can be used for setting-up an OpenLDAP server on

destination machine.

The role implements the following:

* Deploys LDAP TLS private key and certificate.

* Configures TLS versions and ciphers suppported by the server.

* Installs OpenLDAP server (package ``slapd``).

* Configures OpenLDAP server (base DN - domain, organisation, TLS, SSF, log levels).

* Sets-up separate log file for OpenLDAP server at ``/var/log/slapd.log`` (with

  log rotation included).

* Enables the ``misc`` LDAP schema (from ``/etc/ldap/schema/misc.ldif``). This

  is necessary for the mail server role.

* Enables the ``memberof`` overlay on top of default database. The overlay is

  configured to keep track of membership changes for object class

  ``groupOfUniqueNames`` via attribute ``uniqueMember``. Enforcement of

  referential integrity is turned on as well (modifications of ``memberof``

  attribute will update corresponding group as well.

* Creates a basic directory structure used by most of the other roles.

* Creates a basic directory structure used by the mail server role.

* Creates login entries for services that need to consume LDAP directory data in

  some way.

* Creates user-supplied groups in LDAP.

* Configures permissions.

* Creates LDAP entries.

* Configures firewall to allow incoming connections to the LDAP server (via both

  TCP 389 and 636).

* Sets the LDAP server administrator's password.

LDIF Templates

~~~~~~~~~~~~~~

For adding users, use::

  dn: uid=USERNAME,ou=people,BASE_DN

  objectClass: inetOrgPerson

  objectClass: simpleSecurityObject

  uid: USERNAME

  userPassword: PASSWORD_FROM_SLAPPASSWD

  cn: NAME SURNAME

  sn: SURNAME

  gn: NAME

  displayName: DISPLAYNAME

  initials: INITIALS

  mail: MAIL

  mobile: MOBILE

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**

* **ldap_client**

* **backup_client**

Backups

~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/srv/backup/slapd.bak**

  Dump of the LDAP database. LDAP database dump is created every day at 01:45 in

  the morning. This does *not* include the dump of the config database

  (``cn=config``).

Parameters

~~~~~~~~~~

**ldap_admin_password** (string, mandatory)

  Password for the default administrator account of LDAP server (the

  ``cn=admin,DOMAIN`` entry/user).

**ldap_entries** (list, optional, ``[]``)

  List of entries that should be kept in the LDAP directory. Each item is a

  dictionary describing a single LDAP entry with the following keys:

  **dn** (string, mandatory)

    LDAP DN entry.

  **state** (string, optional, ``present``)

    Whether the entry should be present or not. Value can be anything

    supported by the ``ldap_entry`` module. Keep in mind that state

    ``present`` will not update the attributes and their values if the

    entry is already present.

  **attributes** (dictionary, mandatory)

    Dictionary describing remaining attributes (except ``dn``). The keys in this

    dictionary should be the attribute names. The values should be either

    strings, for setting a single attribute value, or a list of strings if it is

    necessary to set multiple values for the same attribute.

**ldap_permissions** (list, optional, ``see below``)

  List of LDAP access rules to apply to base DN served by the LDAP server. The

  listed access control rules will *replace* all existing rules, and will be

  added in the same order they are listed in. Each item is a string that

  constitutes a single access control rule. The format should be the same as

  described in `OpenLDAP Administrator's Guide

  <http://www.openldap.org/doc/admin24/access-control.html#Access%20Control%20via%20Dynamic%20Configuration>`.

  Default value is:

  .. code-block:: yaml

    - >

      to *

      by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage

      by * break

    - >

      to attrs=userPassword,shadowLastChange

      by self write

      by anonymous auth

      by dn="cn=admin,BASEDN" write

      by * none

    - >

      to dn.base=""

      by * read

    - >

      to *

      by self write

      by dn="cn=admin,BASEDN" write

      by * none

**ldap_server_consumers** (list, optional, ``[]``)

  List of items describing additional login entries that should be created for

  services that want to be able to log-in into the LDAP server and consume the

  data present within. Each item should be a dictionary, with the following keys

  avaialable:

  - **name** (name of the service, mandatory, this will be used to construct the

    login entry DN in format of ``cn=NAME,ou=services,BASE_DN``)

  - **password** (password for the login entry, mandatory)

  - **state** (state of the service, optional, defaults to ``present``, this

    should be ``present`` or ``absent``, allowing for removal of old services)

**ldap_server_groups** (list, optional, ``[]``)

  List of groups that should be created in the LDAP directory. Each item should

  be a dictionary containing the following keys:

  - **name** (name of the group, mandatory, this will be used to construct the

    group DN in format of ``cn=NAME,ou=groups,BASE_DN``)

  - **state** (state of the group, optional, defaults to ``present``, this

    should be ``present`` or ``absent``, allowing for removal of old groups)

**ldap_server_domain** (string, optional, ``{{ ansible_domain }}``)

  Domain that should be used for constructing the base DN of default user LDAP

  database. This should be a sub-domain dedicated to organisation. The base DN

  will be constructed by putting all elements of the sub-domain as ``dc``

  entries (as per standard Debian convention). I.e. ``example.com`` would get

  transformed into ``dc=example,dc=com``.

**ldap_server_organization** (string, optional, ``Private``)

  Organization that should be specified in the base DN entry.

**ldap_server_log_level** (string, optional, ``256``)

  Log level to use for the server. This should be compatible with OpenLDAP

  configuration option ``olcLogLevel``. See `OpenLDAP Administrator's Guide

  <http://www.openldap.org/doc/admin24/slapdconf2.html#cn=config>` for value

  description and syntax.

**ldap_server_tls_certificate** (string, mandatory)

  X.509 certificate used for TLS for LDAP service. The file will be stored in

  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_ldap.pem``.

**ldap_server_tls_key** (string, mandatory)

  Private key used for TLS for LDAP service. The file will be stored in

  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_ldap.key``.

**ldap_server_ssf** (number, optional, ``128``)

  Minimum *Security Strength Factor* to require from all incoming

  connections. This applies for both remote and local connections.

**ldap_tls_ciphers** (string, optional ``NONE:+VERS-TLS1.2:+CTYPE-X509:+COMP-NULL:+SIGN-RSA-SHA256:+SIGN-RSA-SHA384:+SIGN-RSA-SHA512:+DHE-RSA:+ECDHE-RSA:+SHA256:+SHA384:+SHA512:+AEAD:+AES-128-GCM:+AES-256-GCM:+CHACHA20-POLY1305:+CURVE-ALL``)

  .. warning::

     Under Debian Stretch, the DHE ciphers are not usable due to a bug

     present in OpenLDAP 2.4.44. See

     https://bugs.launchpad.net/ubuntu/+source/openldap/+bug/1656979

     for details.

  TLS ciphers to enable on the LDAP server. This should be a GnuTLS-compatible

  cipher specification that should also include what TLS protocol versions

  should be used. Value should be compatible with OpenLDAP server option

  ``olcTLSCipherSuite``. Default value allows only TLSv1.2 and strong PFS

  ciphers.

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 9 (Stretch)

Examples

~~~~~~~~

Here is an example configuration for setting-up LDAP server:

.. code-block:: yaml

  ---

  ldap_server_domain: "example.com"

  ldap_server_organization: "Example Corporation"

  ldap_server_log_level: 256

  ldap_server_tls_certificate: "{{ lookup('file', '~/tls/ldap.example.com_ldap.pem') }}"

  ldap_server_tls_key: "{{ lookup('file', '~/tls/ldap.example.com_ldap.key') }}"

  ldap_server_ssf: 128

  ldap_permissions:

    - >

      to *

      by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage

      by * break

    - >

      to attrs=userPassword,shadowLastChange

      by self write

      by anonymous auth

      by dn="cn=admin,dc=example,dc=com" write

      by * none

    - >

      to dn.base=""

      by * read

    - >

      to *

      by self write

      by dn="cn=admin,dc=example,dc=com" write

      by users read

      by * none

  ldap_entries:

    - dn: ou=people,dc=example,dc=com

      attributes:

        objectClass: organizationalUnit

        ou: people

    - dn: ou=groups,dc=example,dc=com

      attributes:

        objectClass: organizationalUnit

        ou: groups

    - dn: uid=john,dc=example,dc=com

      attributes:

        objectClass:

          - inetOrgPerson

          - simpleSecurityObject

        userPassword: somepassword

        uid: john

        cn: John Doe

        sn: Doe

XMPP Server

-----------

The ``xmpp_server`` role can be used for setting-up Prosody, an XMPP server, on

destination machine.

The role implements the following:

* Sets-up the Prosody apt repository.

* Deploys XMPP TLS private key and certificate.

* Installs Prosody.

* Configures Prosody.

* Configures firewall to allow incoming connections to the XMPP server.

Prosody is configured as follows:

* Modules enabled: roster, saslauth, tls, dialback, posix, private, vcard,

  version, uptime, time, ping, pep, register, admin_adhoc, announce, legacyauth.

* Self-registration is not allowed.

* TLS is configured. Legacy TLS is available on port 5223.

* Client-to-server communication requires encryption (TLS).

* Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for

  incoming connections.

* Authentication is done via LDAP. For setting the LDAP TLS truststore, see

  :ref:`LDAP Client <ldap_client>`.

* Internal storage is used.

* For each domain specified, a dedicated conference/multi-user chat (MUC)

  service is set-up, with FQDN set to ``conference.DOMAIN``.

* For each domain specified, a dedicated file proxy service will be set-up, with

  FQDN set to ``proxy.DOMAIN``.

Prosody expects a specific directory structure in LDAP when doing look-ups:

* Prosody will log-in to LDAP as user

  ``cn=prosody,ou=services,XMPP_LDAP_BASE_DN``.

* User entries are read from sub-tree (first-level only)

  ``ou=people,XMPP_LDAP_BASE_DN``. Query filter used for finding users is

  ``(&(mail=$user@$host)(memberOf=cn=xmpp,ou=groups,XMPP_LDAP_BASE_DN))``. This

  allows group-based granting of XMPP service to users.

LDIF Templates

~~~~~~~~~~~~~~

For adding user to a group, use::

  dn: cn=xmpp,ou=groups,BASE_DN

  changetype: modify

  add: uniqueMember

  uniqueMember: uid=USERNAME,ou=people,BASE_DN

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**

* **backup_client**

Backups

~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/var/lib/prosody/**

  Roster information, as well as undelivered (offline) messages for all XMPP

  users. Keep in mind that list of available users and their credentials are

  stored in the LDAP directory (which is backed-up via LDAP server role).

Parameters

~~~~~~~~~~

**xmpp_administrators** (list, mandatory)

  List of Prosody users that should be granted administrator privileges over

  Prosody. Each item is a string with value equal to XMPP user ID

  (i.e. ``john.doe@example.com``).

**xmpp_domains** (list, optional, ``{{ ansible_domain }}``)

  List of domains that are served by this Prosody instance. Each item is a

  string specifying a domain.

**xmpp_ldap_base_dn** (string, mandatory)

  Base DN on the LDAP server. A specific directory structure is expected under

  this entry (as explained above) in order to locate the available domains,

  users, aliases etc.

**xmpp_ldap_password** (string, mandatory)

  Password used for authenticating to the LDAP server.

**xmpp_ldap_server** (string, mandatory)

  Fully qualified domain name, hostname, or IP address of the LDAP server used

  for user authentication and listing.

**xmpp_prosody_package** (string, optional, ``prosody-0.10``)

  Name of Prosody package from the Prosody repositories to

  install. This makes it possible to easily test the latest Prosody or

**xmpp_tls_certificate** (string, mandatory)

  X.509 certificate used for TLS for XMPP service. The file will be stored in

  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_xmpp.pem``.

**xmpp_tls_key** (string, mandatory)

  Private key used for TLS for XMPP service. The file will be stored in

  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_xmpp.key``.

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 9 (Stretch)

Examples

~~~~~~~~

Here is an example configuration for setting-up XMPP server using Prosody:

.. code-block:: yaml

  ---

  xmpp_administrators:

    - john.doe@example.com

  xmpp_domains:

    - example.com

  xmpp_ldap_base_dn: dc=example,dc=com

  xmpp_ldap_password: xmpp

  xmpp_ldap_server: ldap.example.com

  # These are default key and certificate that generated during Prosody

  # installation. Possibly you want to deploy your own.

  xmpp_tls_key: "{{ lookup('file', '/etc/prosody/certs/localhost.key') }}"

  xmpp_tls_certificate: "{{ lookup('file', '/etc/prosody/certs/localhost.crt') }}"

Mail Server

-----------

.. warning::

   It may happen that the ``clamav-freshclam`` service hasn't finished

   downloading the virus database before the ``clamav-daemon`` and

   ``clamav-milter`` services are enabled during the initial run. If mail server

   is not operational, you may need to wait for a little while for download to

   finish, and then restart the ``clamav-daemon`` and ``clamav-milter``

   services.

The ``mail_server`` role can be used for setting-up a complete mail server

solution, which includes both SMTP and IMAP service, on destination machine.

Postfix is used SMTP, while Dovecot is used for IMAP.

The role implements the following:

* Installs rsync.

* Deploys IMAP/SMTP TLS private keys and certificates.

* Installs and configures Dovecot, Postfix, ClamAV, and ClamAV Milter.

* Purges Exim4 configuration (just in case).

* Sets-up aliases for the local recipients.

* Installs SWAKS (utility for testing SMTP servers).

* Sets-up the necessary directories and files under Postfix chroot.

* Configures firewall to allow incoming connections to the mail server. This

  includes set-up of redirection from TCP port 26 to TCP port 587 (alternate

  submission port), as well as redirection from TCP port 27 to TCP port 25

  (alternate SMTP port), useful as workaround for ISP/hotel blocks.

Deployed services are configured as follows:

* Both Postfix and Dovecot look-up available domains, users, and aliases in

  LDAP.

* Incoming and outgoing mail is scanned with ClamAV (via ClamAV

  Milter). Infected mails are rejected.

* Mail is stored in directory ``/var/MAIL_USER/DOMAIN/USER``, using ``Maildir``

  format.

* TLS is required for user log-ins for both SMTP and IMAP.

* Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for

  incoming connections.

* For user submission (SMTP), users must connect and authenticate over TCP

  port 587.

* Configures TLS versions and ciphers supported by Dovecot.

* Configures TLS versions and ciphers supported by Postfix on submission port

  (587). TLS configuration on port 25 is kept intact in order to maintain maximum

  interoperability with other servers.

* RBL's are used for combating spam (if any is specified in configuration, see

  below).

* Postfix is configured to deliver undeliverable bounces to postmaster. This

  helps with detecting misconfigured applications and servers.

Both Postfix and Dovecot expect a specific directory structure in LDAP when

doing look-ups:

* Postfix will log-in to LDAP as user

  ``cn=postfix,ou=services,MAIL_LDAP_BASE_DN``.

* Dovecot will log-in to LDAP as user

  ``cn=dovecot,ou=services,MAIL_LDAP_BASE_DN``.

* Domain entries need to be available as

  ``dc=DOMAIN,ou=domains,ou=mail,ou=services,MAIL_LDAP_BASE_DN``.

* Alias entries need to be available as

  ``cn=ALIAS,ou=aliases,ou=mail,ou=services,MAIL_LDAP_BASE_DN``.

* User entries are read from sub-tree (first-level only)

  ``ou=people,MAIL_LDAP_BASE_DN``. Query filter used for finding users is

  ``(&(mail=%s)(memberOf=cn=mail,ou=groups,MAIL_LDAP_BASE_DN))``. This allows

  group-based granting of mail services to users.

LDIF Templates

~~~~~~~~~~~~~~

For adding domains, use::

  dn: dc=DOMAIN,ou=domains,ou=mail,ou=services,BASE_DN

  objectClass: dNSDomain

  dc: DOMAIN

For adding aliases, use::

  dn: cn=ALIAS,ou=aliases,ou=mail,ou=services,BASE_DN

  objectClass: nisMailAlias

  cn: ALIAS

  rfc822MailMember: REALEMAIL

For adding user to a group, use::

  dn: cn=mail,ou=groups,BASE_DN

  changetype: modify

  add: uniqueMember

  uniqueMember: uid=USERNAME,ou=people,BASE_DN

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**

* **backup_client**

Backups

~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/var/{{ mail_user }}**

  All data stored by the mail server, including mails and Sieve scripts. Keep in

  mind that list of available users and their credentials are stored in the LDAP

  directory (which is backed-up via LDAP server role).

Parameters

~~~~~~~~~~

**mail_ldap_base_dn** (string, mandatory)

  Base DN on the LDAP server. A specific directory structure is expected under

  this entry (as explained above) in order to locate the available domains,

  users, aliases etc.

**mail_ldap_url** (string, mandatory)

  LDAP URL that should be used for connecting to the LDAP server for doing

  domain/user look-ups.

**mail_ldap_tls_truststore** (string, mandatory)

  X.509 certificate chain used for issuing certificate for the LDAP service. The

  file will be stored in locations ``/etc/ssl/certs/mail_ldap_tls_truststore.pem``

  and ``/var/spool/postfix/etc/ssl/certs/mail_ldap_tls_truststore.pem``.

**mail_ldap_postfix_password** (string, mandatory)

  Password for authenticating the Postfix LDAP user.

**mail_ldap_dovecot_password** (string, mandatory)

  Password for authenticating the Dovecot LDAP user.

**mail_message_size_limit** (integer, optional, ``10240000``)

  Maximum size of message in bytes that the SMTP server should accept

  for incoming mails. If the mail message size exceeds the listed

  value, it will be rejected by the server. The size is also

  advertised as part of SMTP server capabilities (in response to the

  ``ehlo`` SMTP command).

**mail_server_tls_protocols** (list, optional, ``[ "TLSv1.2" ]``)

  List of TLS protocols the mail server should support. Each value specified

  should be compatible with Postfix configuration option

  ``smtpd_tls_mandatory_protocols`` and Dovecot configuration option

  ``ssl_protocols``.

**mail_server_tls_ciphers** (string, optional ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT``)

  TLS ciphers to enable on the mail server (for IMAP and SMTP submission). This

  should be an OpenSSL-compatible cipher specification. Value should be

  compatible with Postfix configuration option ``tls_high_cipherlist`` and

  Dovecot configuration option ``ssl_cipher_list``. Default value allows only

  TLSv1.2 and strong PFS ciphers.

**mail_user** (string, optional, ``vmail``)

  Name of the user that owns all the mail files.

**mail_user_uid** (integer, optional, ``whatever OS picks``)

  UID of the user that owns all the mail files.

**mail_user_gid** (integer, optional, ``whatever OS picks``)

  GID of the user that owns all the mail files.

**imap_max_user_connections_per_ip** (integer, optional, ``10``)

  Maximum number of IMAP connections from a single IP for a single user. Default

  value can be considered rather low, since two devices (computer and phone)

  will easily reach it.

**imap_tls_certificate** (string, mandatory)

  X.509 certificate used for TLS for IMAP service. The file will be stored in

  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_imap.pem``.

**imap_tls_key** (string, mandatory)

  Private key used for TLS for IMAP service. The file will be stored in

  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_imap.key``.

**local_mail_aliases** (dictionary, optional, ``{}``)

  Dictionary defining the local aliases. Aliases defined this way will either be

  appended to default aliases on the server, or replace the existing entries (if

  the alias/recipient is already present). Keys in the dictionary are the local

  recipients/aliases, while the value provided should be a space-separated list

  of mail addresses (or local users) where the mails should be forwarded.

**smtp_tls_certificate** (string, mandatory)

  X.509 certificate used for TLS for SMTP service. The file will be stored in

  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_smtp.pem``.

**smtp_tls_key** (string, mandatory)

  Private key used for TLS for SMTP service. The file will be stored in

  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_smtp.key``.

**imap_folder_separator** (string, optional, ``/``)

  Character used for separating the IMAP folders when clients are requesting

  listing from the server. Usually either slash(``/``) or dot(``.``).

**smtp_rbl** (list, optional, ``[]``)

  List of RBLs to use for detecting servers which send out spam. Each item is a

  string resembling the RBL domain.

**mail_postmaster** (string, optional, ``postmaster@{{ ansible_domain}}``)

  Mail address to use for the postmaster account in Dovecot.

**smtp_allow_relay_from** (list, optional, [])

  List of networks from which mail relaying is allowed even without

  authentication. Each item in the list is a string defining a network. The

  format must be compatible with Postfix ``mynetworks`` setting (for example:

  ``192.168.1.0/24``, ``myhost.example.com`` etc).

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 9 (Stretch)

Examples

~~~~~~~~

Here is an example configuration for setting-up XMPP server using Prosody:

.. code-block:: yaml

  ---

  mail_ldap_url: ldap://ldap.example.com/

  mail_ldap_tls_truststore: /etc/ssl/certs/truststore.pem

  mail_ldap_base_dn: dc=example,dc=com

  mail_ldap_postfix_password: postfix

  mail_ldap_dovecot_password: dovecot

  mail_user: vmail

  mail_user_uid: 5000

  mail_user_gid: 5000

  # All mails sent to local user root will be forwarded to external account as

  # well.

  local_mail_aliases:

    root: "root john.doe@example.com"

  imap_tls_certificate: "{{ lookup('file', '~/tls/mail.example.com_imap.pem') }}"

  imap_tls_key: "{{ lookup('file', '~/tls/mail.example.com_imap.key') }}"

  smtp_tls_certificate: "{{ lookup('file', '~/tls/mail.example.com_smtp.pem') }}"

  smtp_tls_key: "{{ lookup('file', '~/tls/mail.example.com_smtp.key') }}"

  imap_folder_separator: /

  smtp_rbl:

    - bl.spamcop.net

    - zen.spamhaus.org

  mail_postmaster: postmaster@example.com

  smtp_allow_relay_from:

    - ldap.example.com

    - xmpp.example.com

  imap_max_user_connections_per_ip: 50

Mail Forwarder

--------------

The ``mail_forwarder`` role can be used for setting-up a local SMTP server for

sending out mails and receiving mails for local users. The SMTP server is

provided by Postfix.

SMTP service on server set-up this way is not meant to be exposed to the

Internet directly, and should receive delivery failures from the relay server

instead.

The role implements the following:

* Installs and configures Postfix.

* Purges Exim4 configuration (just in case).

* Sets-up aliases for the local recipients.

* Installs SWAKS (utility for testing SMTP servers).

* Configures firewall to accept SMTP connections from SMTP relay (if one has

  been configured). This allows for delivery of bounced e-mails.

Postfix is configured as follows:

* Local destinations are set-up.

* A relay host is set.

* TLS is enforced for relaying mails, with configurable truststore for server

  certificate verification if SMTP relay is used. If SMTP relay is not used

  (configured), no certificate verification is done.

* Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for

  incoming connections.

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**

Parameters

~~~~~~~~~~

**local_mail_aliases** (dictionary, optional, ``[]``)

  Dictionary defining the local aliases. Aliases defined this way will either be

  appended to default aliases on the server, or replace the existing entries (if

  the alias/recipient is already present). Keys in the dictionary are the local

  recipients/aliases, while the value provided should be a space-separated list

  of mail addresses (or local users) where the mails should be forwarded.

**mail_message_size_limit** (integer, optional, ``10240000``)

  Maximum size of message in bytes that the SMTP server should accept

  for incoming mails. If the mail message size exceeds the listed

  value, it will be rejected by the server. The size is also

  advertised as part of SMTP server capabilities (in response to the

  ``ehlo`` SMTP command). Changing the value is primarily useful when

  SMTP from relay is allowed (via the ``smtp_from_relay_allowed``

  parameter), since incoming SMTP communication is otherwise not

  allowed at all.

**smtp_from_relay_allowed** (boolean, optional, ``True``)

  Specify if SMTP traffic from SMTP relay should be allowed or not (for bounced

  messages, for example). This parameter should be set to ``False`` on systems

  behind NAT or on systems that may not have constant network connectivity (such

  as laptops) to avoid firewall failures since SMTP relay name needs to be

  resolvable.

**smtp_relay_host** (string, optional, ``None``)

  SMTP server via which the mails are sent out for non-local recipients.

**smtp_relay_host_port** (integer, optional, ``None``)

  Port to use when connecting to the SMTP relay host.

**smtp_relay_truststore** (string, mandatory)

  X.509 certificate chain used for issuing certificate for the SMTP relay

  service. The file will be stored in location

  ``/etc/ssl/certs/smtp_relay_truststore.pem``

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~