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

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

Role is compatible with the following distributions:

- Debian 9 (Stretch)

Examples

~~~~~~~~

Here is an example configuration for setting-up the mail forwarder:

.. code-block:: yaml

  ---

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

  # well.

  local_mail_aliases:

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

  smtp_relay_host: mail.example.com

  smtp_relay_host_port: 27

  smtp_from_relay_allowed: False

  smtp_relay_truststore: /etc/ssl/certs/example_ca_chain.pem

Web Server

----------

The ``web_server`` role can be used for setting-up a web server on destination

machine.

The role is supposed to be very lightweight, providing a basis for deployment of

web applications.

The role implements the following:

* Installs and configures nginx with a single, default vhost with a small static

  index page.

* Deploys the HTTPS TLS private key and certificate (for default vhost).

* Configures TLS versions and ciphers supported by Nginx.

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

  incoming connections.

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

* Installs and configures virtualenv and virtualenvwrapper as a common base for

  Python apps.

* Installs and configures PHP FPM as a common base for PHP apps.

The web server is configured as follows:

* No plaintext HTTP is allowed, HTTPS is mandatory. Clients connecting

  via plaintext HTTP are redirected to HTTPS.

* Clients are served with ``Strict-Transport-Security`` header with

  value of ``max-age=31536000; includeSubDomains``. This forces

  compliant clients to always connect using HTTPS to the web server

  when accessing its default domain, as well as any subdomains served

  by this web server or any other. The (client-side) cached header

  value expires after one year.

Role dependencies

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

Depends on the following roles:

* **common**

Parameters

~~~~~~~~~~

**default_https_tls_certificate** (string, mandatory)

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

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

**default_https_tls_key** (string, mandatory)

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

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

**web_default_title** (string, optional, ``Welcome``)

  Title for the default web page shown to users (if no other vhosts were matched).

**web_default_message** (string, optional, ``You are attempting to access the web server using a wrong name or an IP address. Please check your URL.``)

  Message for the default web page shown to users (if no other vhosts were

  matched).

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

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

  should be compatible with Nginx configuration option ``ssl_protocols``.

**web_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 web server. This should be an OpenSSL-compatible

  cipher specification. Value should be compatible with Nginx configuration

  option ``ssl_ciphers``. Default value allows only TLSv1.2 and strong PFS

  ciphers with RSA private keys.

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 9 (Stretch)

Examples

~~~~~~~~

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

.. code-block:: yaml

  ---

  default_https_tls_key: "{{ lookup('file', inventory_dir + '/tls/web.example.com_https.key') }}"

  default_https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/web.example.com_https.pem') }}"

  web_default_title: "Welcome to Example Inc."

  web_default_message: "You are attempting to access the web server using a wrong name or an IP address. Please check your URL."

PHP Website

-----------

The ``php_website`` role can be used for setting-up a website powered by PHP on

destination machine.

This role is normally not supposed to be used directly, but should instead serve

as the basis for writing website-specific roles. Therefore the role is written

in quite generic way, allowing the integrator to write his/her own logic for

deploying the necessary PHP applications, while still reusing a common base and

reducing the workload.

The role implements the following:

* Creates a dedicated user/group for running the PHP scripts.

* Creates a dedicated administrator user for maintaining the website.

* Creates a base directory where the website-specific code and data should be

  stored at.

* Adds nginx to website's group, so nginx could read the necessary files.

* Adds website administrator to website's group, so administrator could manage

  the code and data.

* Installs additional packages required for running the role (as configured).

* Deploys the HTTPS TLS private key and certificate (for website vhost).

* Configures PHP FPM and nginx to serve the website.

The role is implemented with the following layout/logic in mind:

* Clients are served with ``Strict-Transport-Security`` header with

  value of ``max-age=31536000; includeSubDomains``. This forces

  compliant clients to always connect using HTTPS to the web server

  when accessing its domain, as well as any subdomains served

  by this web server or any other. The (client-side) cached header

  value expires after one year.

* Website users are named after the ``FQDN`` (fully qualified domain name) of

  website, in format of ``web-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to

  ``FQDN`` where dots have been replaced by underscores (for example,

  ``web-cloud_example_com``).

* Website users are set-up via GECOS field to have their umask set to ``0007``

  (in combination with ``pam_umask``).

* Administrator users are named after the ``FQDN`` (fully qualified domain name)

  of website, in format of ``admin-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal

  to ``FQDN`` where dots have been replaced by underscores (for example,

  ``admin-cloud_example_com``).

* All websites reside within a dedicated sub-directory in ``/var/www``. The

  sub-directory name is equal to the ``FQDN`` used for accessing the

  website. Owner of the directory is set to be the application administrator,

  while group is set to be the website group. Additionally, ``SGID`` bit is set

  on the directory. This allows admin, with correct umask, to create necessary

  files and directories that should be readable (and eventually writeable) by

  the website user (running the PHP scripts) without having to become root.

* All files placed in the website directory should be either created there

  directly, or copied to the directory in order to make sure the ``SGID`` gets

  honored. **Do not move the files, the permissions will not be set correctly.**

* Within the website directory, nginx/php5-fpm will expect to find the relevant

  files within the htdocs sub-directory (this can be symlink too).

* nginx communicates with PHP FPM over a dedicated Unix socket for each website.

Role dependencies

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

Depends on the following roles:

* **common**

* **web_server**

Parameters

~~~~~~~~~~

**additional_fpm_config** (dict, optional, ``{}``)

  Additional PHP FPM configuration options that should be included for PHP

---

dependencies:

  - common

galaxy_info:

  author: Branko Majic

  description: Sets-up local SMTP server for sending out mails and receiving mails for local users

  license: BSD

  min_ansible_version: 2.9

  platforms:

    - name: Debian

      versions:

        - 9

---

dependency: {}

driver:

  name: vagrant

  provider:

    name: virtualbox

lint:

  name: yamllint

  options:

    config-file: ../../.yamllint.yml

platforms:

  - name: mail-server

    groups:

      - mail-servers

      - helper

    box: debian/contrib-stretch64

    memory: 256

    cpus: 1

    interfaces:

      - auto_config: true

        ip: 10.31.127.10

        network_name: private_network

        type: static

  - name: client1

    groups:

      - clients

      - helper

    box: debian/contrib-stretch64

    memory: 256

    cpus: 1

    interfaces:

      - auto_config: true

        ip: 10.31.127.11

        network_name: private_network

        type: static

  - name: parameters-mandatory-stretch64

    groups:

      - parameters-mandatory

    box: debian/contrib-stretch64

    memory: 256

    cpus: 1

    interfaces:

      - auto_config: true

        ip: 10.31.127.30

        network_name: private_network

        type: static

  - name: parameters-optional-stretch64

    groups:

      - parameters-optional

    box: debian/contrib-stretch64

    memory: 256

    cpus: 1

    interfaces:

      - auto_config: true

        ip: 10.31.127.31

        network_name: private_network

        type: static

  - name: parameters-no-incoming-stretch64

    groups:

      - parameters-no-incoming

    box: debian/contrib-stretch64

    memory: 256

    cpus: 1

    interfaces:

      - auto_config: true

        ip: 10.31.127.32

        network_name: private_network

        type: static

provisioner:

  name: ansible

  playbooks:

    cleanup: cleanup.yml

  config_options:

    defaults:

      force_valid_group_names: "ignore"

      interpreter_python: "/usr/bin/python3"

    ssh_connection:

      pipelining: "True"

  lint:

    name: ansible-lint

scenario:

  name: default

verifier:

  name: testinfra

  lint:

    name: flake8

---

- name: Set-up fixtures

  hosts: localhost

  connection: local

  gather_facts: false

  tasks:

    - name: Initialise CA hierarchy

      command: "gimmecert init"

      args:

        creates: ".gimmecert/ca/level1.cert.pem"

        chdir: "tests/data/"

    - name: Generate server private keys and certificates

      command:

      args:

        chdir: "tests/data/"

        creates: ".gimmecert/server/{{ item.name }}.cert.pem"

        argv:

          - "gimmecert"

          - "server"

          - "{{ item.name }}"

          - "{{ item.fqdn }}"

      with_items:

        - name: mail-server_smtp

          fqdn: mail-server

    - name: Set-up link to generated X.509 material

      file:

        src: ".gimmecert"

        dest: "tests/data/x509"

        state: link

- name: Prepare

  hosts: all

  gather_facts: false

  tasks:

    - name: Install python for Ansible

      raw: test -e /usr/bin/python3 || (apt -y update && apt install -y python3-minimal)

      become: true

      changed_when: false

- hosts: all

  become: true

  tasks:

    - name: Update all caches to avoid errors due to missing remote archives

      apt:

        update_cache: true

      changed_when: false

- hosts: all

  become: true

  tasks:

    - name: Set-up the hosts file

      lineinfile:

        path: /etc/hosts

        regexp: "^{{ item.key }}"

        line: "{{ item.key }} {{ item.value }}"

        owner: root

        group: root

        mode: 0644

        state: present

      with_dict:

        10.31.127.10: "mail-server domain1"

        10.31.127.11: "client1"

        10.31.127.30: "parameters-mandatory-stretch64"

        10.31.127.31: "parameters-optional-stretch64"

        10.31.127.32: "parameters-no-incoming-stretch64"

    - name: Install tools for testing

      apt:

        name: gnutls-bin

        state: present

- hosts: clients

  become: true

  tasks:

    - name: Install SWAKS for testing SMTP capability

      apt:

        name: swaks

        state: present

    - name: Install tool for testing TCP connectivity

      apt:

        name: hping3

        state: present

    - name: Deploy CA certificate

      copy:

        src: tests/data/x509/ca/level1.cert.pem

        dest: /usr/local/share/ca-certificates/testca.crt

        owner: root

        group: root

        mode: 0644

      notify:

        - Update CA certificate cache

  handlers:

    - name: Update CA certificate cache

      command: /usr/sbin/update-ca-certificates --fresh

- hosts: mail-servers

  become: true

  tasks:

    - name: Deploy CA certificate

      copy:

        src: tests/data/x509/ca/level1.cert.pem

        dest: /usr/local/share/ca-certificates/testca.crt

        owner: root

        group: root

        mode: 0644

      notify:

        - Update CA certificate cache

    - name: Deploy SMTP private key and certificate

      copy:

        src: "tests/data/x509/server/{{ item }}"

        dest: "/etc/ssl/{{ item }}"

        owner: root

        group: root

        mode: 0600

      with_items:

        - mail-server_smtp.cert.pem

        - mail-server_smtp.key.pem

    - name: Install Postfix

      apt:

        name: "postfix"

        state: present

    - name: Purge Exim configuration

      apt:

        name: "exim4*"

        state: absent

        purge: true

    - name: Deploy Postfix configuration

      copy:

        src: tests/data/main.cf

        dest: /etc/postfix/main.cf

        owner: root

        group: root

        mode: 0644

      notify:

        - Restart Postfix

    - name: Install tool for testing TCP connectivity

      apt:

        name: hping3

        state: present

    - name: Install SWAKS for testing SMTP capability

      apt:

        name: swaks

        state: present

    - name: Set-up port forwarding

      command: "iptables -t nat -A PREROUTING -p tcp -m tcp --dport 27 -j REDIRECT --to-ports 25"

      changed_when: false

  handlers:

    - name: Update CA certificate cache

      command: /usr/sbin/update-ca-certificates --fresh

    - name: Restart Postfix

      service:

        name: postfix

        state: restarted

- hosts: parameters-optional

  become: true

  tasks:

    - name: Create additional group for testing local aliases

      group:

        name: testuser

    - name: Create additional user for testing local aliases

      user:

        name: testuser

        group: testuser

# See /usr/share/postfix/main.cf.dist for a commented, more complete version

# Debian specific:  Specifying a file name will cause the first

# line of that file to be used as the name.  The Debian default

# is /etc/mailname.

#myorigin = /etc/mailname

smtpd_banner = $myhostname ESMTP $mail_name (Debian/GNU)

biff = no

# appending .domain is the MUA's job.

append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings

#delay_warning_time = 4h

readme_directory = no

# TLS parameters

smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem

smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key

smtpd_tls_dh1024_param_file = /etc/ssl/private/{{ inventory_hostname }}_smtp.dh.pem

smtpd_tls_dh512_param_file = /etc/ssl/private/{{ inventory_hostname }}_smtp.dh.pem

smtpd_use_tls=yes

smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache

smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache

{% if smtp_relay_host %}

smtp_tls_security_level=verify

smtp_tls_CAfile=/etc/ssl/certs/smtp_relay_truststore.pem

{% endif %}

# See /usr/share/doc/postfix/TLS_README.gz in the postfix-doc package for

# information on enabling SSL in the smtp client.

myhostname = {{ inventory_hostname }}

alias_maps = hash:/etc/aliases

alias_database = hash:/etc/aliases

myorigin = /etc/mailname

mydestination = {{ inventory_hostname }}, {{ inventory_hostname_short }}, localhost.localdomain, localhost

relayhost = {{ smtp_relay_host }}{% if smtp_relay_host and smtp_relay_host_port %}:{{ smtp_relay_host_port }}{% endif %}{{ '' }}

mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128

mailbox_command = procmail -a "$EXTENSION"

mailbox_size_limit = 0

recipient_delimiter = +

inet_interfaces = all

inet_protocols = all

# Fall-back to using native lookups (/etc/hosts etc) if DNS lookup fails. Useful

# for local overrides of mail servers.

smtp_host_lookup = dns, native

# Explicitly set maximum allowed mail size that should be accepted.

message_size_limit = {{ mail_message_size_limit }}