majic-ansible-roles Changeset

Changeset - 9727c5e3ac7c

Parent rev.

Child rev.

[Not reviewed]

0 5 0

Branko Majic (branko) - 5 years ago 2021-01-13 23:54:35
branko@majic.rs

MAR-151: Added support for Debian 10 Buster to mail_forwarder role:

- Updated role reference documentaiton.
- Updated role meta information.
- Updated tests.
- Set the smtpd_relay_restrictions configuration option for Postfix
SMTP server in mail_forwarder role (required for version found in
Debian 10 Buster).

5 files changed with 45 insertions and 1 deletions:

docs/rolereference.rst

roles/mail_forwarder/meta/main.yml

roles/mail_forwarder/molecule/default/molecule.yml

roles/mail_forwarder/molecule/default/prepare.yml

roles/mail_forwarder/templates/main.cf.j2

0 comments (0 inline, 0 general)

docs/rolereference.rst

➞

Show inline comments

@@ @@ -601,1536 +601,1537 @@ The role implements the following: @@
 * 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, mandatory)
   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). E.g. ``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)
 - Debian 10 (Buster)
 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.
 * Sets-up the Debian backports repository and pins the ``lua-ldap``
   package to it (needed for Lua 5.2 support with Prosody 0.11).
 * Deploys XMPP TLS private key and certificate.
   .. warning::
      The issued certificate must have multiple FQDNs listed as subject
      alternative names (DNS names) for each configured domain:
      - domain itself
      - ``conference.DOMAIN``
      - ``proxy.DOMAIN``
      A daily cron job is run to validate that all certificates have
      been configured and issued correctly.
 * 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, carbons, mam.
 * 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.
 * Configures TLS versions and ciphers supported by Prosody (for
   *c2s*/client connections only).
 * 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, mandatory)
   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.11``)
   Name of Prosody package from the Prosody repositories to
   install. This makes it possible to easily test the latest Prosody or
   to switch to a different nightly build. It should be noted that
   only the default version is getting properly tested. Prosody
   versions lower than ``0.10.x`` are not supported.
 **xmpp_server_archive_expiration** (string, optional, ``never``)
   Expiration period for messages stored server-side using `XEP-0313:
   Message Archive Management
   <https://xmpp.org/extensions/xep-0313.html>`_. The value should be
   compatible with `Prosody mod_mam
   <https://prosody.im/doc/modules/mod_mam>`_ configuration option
   ``archive_expires_after``.
 **xmpp_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 XMPP server. This should be an
   OpenSSL-compatible cipher specification. Value should be compatible
   with Prosody's option ``ciphers`` normally defined within the
   ``ssl`` section of configuration file (see `official documentation
   <https://prosody.im/doc/advanced_ssl_config#ciphers>`_ for details).
   Default value allows only TLSv1.2 and strong PFS ciphers with RSA
   private keys.
 **xmpp_server_tls_protocol** (string, optional, ``tlsv1_2+``)
   Protocol version the XMPP server should support for client
   connections. The value specified should be compatible with Prosody's
   ``protocol`` option normally defined within the ``ssl`` section of
   configuration file (see `official documentation
   <https://prosody.im/doc/advanced_ssl_config#protocol>`__ for
   details).
 **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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Role is compatible with the following distributions:
 - Debian 9 (Stretch)
 - Debian 10 (Buster)
 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
   website's pool. Keys are parameter names, values are associated values. Don't
   forget to include quotes in the value itself if expected value type is string.
 **additional_nginx_config** (list, optional, ``[]``)
   List providing additional Nginx configuration options to include. This can be
   useful for specifying things like error pages. Options are applied inside of a
   **server** context of Nginx configuration file.
   Each item is a dictionary with the following options describing the extra
   configuration option:
   **comment** (string, mandatory)
     Comment describing the configuration option.
   **value** (string, mandatory)
     Configuration option.
 **admin_uid** (integer, optional, ``whatever OS picks``)
   UID of the dedicated website administrator user. The user will be member of
   website group.
 **deny_files_regex** (list, optional, ``[]``)
   List of regular expressions for matching files/locations to which the web
   server should deny access. This is useful to block access to any sensitive
   files that should not be served directly by the web server. The format must be
   compatible with regular expressions used by ``nginx`` for ``location ~``
   syntax.
 **environment_indicator** (dictionary, optional, ``null``)
   Specify configuration for including environment indicator on all HTML
   pages. Indicator is a simple strip at bottom of a page with custom background
   colour, text colour, and text.
   Specifying environment indicator is useful for avoiding mistakes when testing
   by having better visibility what environment you are in
   (production/staging/test).
   The following keys need to be specified:
   **background_colour** (string, mandatory)
     Background colour to use for the strip at bottom. This should be value
     compatible with CSS ``background-color`` attribute.
   **text_colour** (string, mandatory
     Text colour to use for the strip at bottom. This should be value compatible
     with CSS ``color`` attribute.
   **text** (string, mandatory)
     Text to show in show in the strip at bottom.
 **fqdn** (string, mandatory)
   Fully-qualified domain name where the website is reachable. This value is used
   for calculating the user/group name for dedicated website user, as well as
   home directory of the website user (where data/code should be stored at).
 **index** (string, optional, ``index.php``)
   Space-separated list of files which should be treated as index files by the
   web server. The web server will attempt opening these index files, in
   succession, until the first match, or until it runs out of matches, when a
   client requests an URI pointing to directory.
 **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 ``{{ fqdn }}_https.pem``.
 **https_tls_key** (string, optional, mandatory)
   Private key used for TLS for HTTPS service. The file will be stored in
   directory ``/etc/ssl/private/`` under name ``{{ fqdn }}_https.key``.
 **php_file_regex** (string, optional, ``\.php$``)
   Regular expression used for determining which file should be interepted via
   PHP.
 **php_rewrite_urls** (list, optional, ``[]``)
   A list of rewrite rules that are applied to incoming requests. These rewrite
   rules are specifically targetted at prettying-up the URLs used by the PHP
   scripts. Each element of the list should be a string value compatible with the
   format of ``nginx`` option ``rewrite``. The keyword ``rewrite`` itself should
   be omitted, as well as trailing semi-colon (``;``).
 **rewrites** (list, optional, ``[]``)
   A list of rewrite rules that are applied to incoming requests. Each element of
   the list should be a string value compatible with the format of ``nginx``
   option ``rewrite``. The keyword ``rewrite`` itself should be omitted, as well
   as trailing semi-colon (``;``).
 **packages** (list, optional, ``[]``)
   A list of additional packages to install for this particular PHP
   appliction. This is usually going to be different PHP extensions.
 **uid** (integer, optional, ``whatever OS picks``)
   UID/GID (they are set-up to be the same) of the dedicated website
   user/group.
 **website_mail_recipients** (string, optional, ``root``)
   Space-separated list of e-mails or local users to which the mails, sent to
   either the website admin or website user, should be forwarded to. Forwarding
   is configured via ``~/.forward`` configuration file.
 Distribution compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Role is compatible with the following distributions:
 - Debian 9 (Stretch)
 Examples
 ~~~~~~~~
 Here is an example configuration for setting-up two (base) PHP websites (for
 running *ownCloud* and *The Bug Genie* applications):
 .. code-block:: yaml
     - role: php_website
       fqdn: cloud.example.com
       uid: 2001
       php_file_regex: \.php($|/)
       rewrites:
         - ^/\.well-known/host-meta /public.php?service=host-meta
         - ^/\.well-known/host-meta\.json /public.php?service=host-meta-json
         - ^/\.well-known/carddav /remote.php/carddav/ redirect
         - ^/\.well-known/caldav /remote.php/caldav/ redirect
         - ^/apps/calendar/caldav\.php /remote.php/caldav/
         - ^/apps/contacts/carddav\.php /remote.php/carddav/
         - ^/remote/(.*) /remote.php
       deny_files_regex:
         - ^(\.|autotest|occ|issue|indie|db_|console|build/|tests/|config/|lib/|3rdparty/|templates/).*
       packages:
         # For ownCloud
         - php5-gd
         - php5-json
         - php5-mysql
         - php5-curl
       https_tls_key: "{{ lookup('file', inventory_dir + '/tls/cloud.example.com_https.key') }}"
       https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/cloud.example.com_https.pem') }}"
       additional_nginx_config:
         - comment: Use custom page for forbidden files.
           value: error_page 403 /core/templates/403.php;
         - comment: Use custom page for non-existing locations/files.
           value: error_page 404 /core/templates/404.php;
       additional_fpm_config:
         "env[PATH]": "\"/usr/local/bin:/usr/bin:/bin\""
       website_mail_recipients: "root john.doe@example.com"
       environment_indicator:
         background_colour: "green"
         text_colour: "black"
         text: "TEST ENVIRONMENT"
     - role: php_website
       deny_files_regex:
         - ^\..*
       php_rewrite_urls:
         - ^(.*) /index.php?url=$1
       fqdn: tbg.example.com
       uid: 2007
       https_tls_key: "{{ lookup('file', inventory_dir + '/tls/tbg.example.com_https.key') }}"
       https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/tbg.example.com_https.pem') }}"
 WSGI Website
 ------------
 The ``wsgi_website`` role can be used for setting-up a website powered by Python
 on destination machine. The website needs to use the WSGI specification for
 making the Python web application(s) available.
 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 Python applications/packages, while still reusing a
 common base and reducing the workload.
 The role implements the following:
 * Creates a dedicated user/group for running the WSGI application.
 * 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).
 * Sets-up a dedicated Python virtual environment for website. Python
   version can be specified (default is Python 2).
 * Install ``futures`` package in Python virtual environment (required for
   Gunicorn in combination with Python 2.7).
 * Install Gunicorn in Python virtual environment.
 * Installs additional packages required for running the role in Python virtual
   environment (as configured).
 * Configures systemd to run the website code (using Gunicorn)
 * Deploys the HTTPS TLS private key and certificate (for website vhost).
 * Configures nginx to serve the website (static files served directly, requests
   passed on to Gunicorn).
 The role is implemented with the following layout/logic in mind:
 * 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 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-wiki_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 WSGI application) 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, Python virtual environment can be found within
   the ``virtualenv`` sub-directory. Switching to administrator user via login
   shell will automatically activate the virtual environment.
 * Within the website directory, nginx will expect to find the static files
   within the ``htdocs`` sub-directory (this can be symlink too). Locations/aliases
   can be configured for static file serving.
 * Within the website directory, systemd service will expect to find the website
   code within the ``code`` sub-directory (this can be symlink too).
 * nginx communicates with WSGI server over a dedicated Unix socket for each
   website.
 Role dependencies
 ~~~~~~~~~~~~~~~~~
 Depends on the following roles:
 * **common**
 * **web_server**
 Parameters
 ~~~~~~~~~~
 **additional_nginx_config** (list, optional, ``[]``)
   List providing additional Nginx configuration options to include. This can be
   useful for specifying things like error pages. Options are applied inside of a
   **server** context of Nginx configuration file.
   Each item is a dictionary with the following options describing the extra
   configuration option:
   **comment** (string, mandatory)
     Comment describing the configuration option.
   **value** (string, mandatory)
     Configuration option.
 **admin_uid** (integer, optional, ``whatever OS picks``)
   UID of the dedicated website administrator user. The user will be member of
   website group.
 **environment_indicator** (dictionary, optional, ``null``)
   Specify configuration for including environment indicator on all HTML
   pages. Indicator is a simple strip at bottom of a page with custom background
   colour, text colour, and text.
   Specifying environment indicator is useful for avoiding mistakes when testing
   by having better visibility what environment you are in
   (production/staging/test).
   The following keys need to be specified:
   **background_colour** (string, mandatory)
     Background colour to use for the strip at bottom. This should be value
     compatible with CSS ``background-color`` attribute.
   **text_colour** (string, mandatory
     Text colour to use for the strip at bottom. This should be value compatible
     with CSS ``color`` attribute.
   **text** (string, mandatory)
     Text to show in show in the strip at bottom.
 **environment_variables** (dict, optional, ``{}``)
   Specify additional environment variables that should be set for running the
   service. Environment variables will be set in both the systemd service and for
   the application's administrator user (when logged in as one).
 **fqdn** (string, mandatory)
   Fully-qualified domain name where the website is reachable. This value is used
   for calculating the user/group name for dedicated website user, as well as
   home directory of the website user (where data/code should be stored at).
 **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 ``{{ fqdn }}_https.pem``.
 **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 ``{{ fqdn }}_https.key``.
 **packages** (list, optional, ``[]``)
   A list of additional packages to install for this particular WSGI
   website. This is usually going to be development libraries for building Python
   packages.
 **proxy_headers** (dictionary, optional, ``{}``)
   Additional headers to set when proxying request to Gunicorn. Keys are header
   names, values are header values. Both should be compatible with Nginx
   ``proxy_set_header``. If you need to provide an empty value, use quotes (don't
   forget to surround them by another set of quotes for YAML syntax, for example
   ``"\"\""`` or ``'""'``).
 **python_version** (string, optional, ``2``)
   Python version to use when setting-up the Python virtual environment.
 **rewrites** (list, optional, ``[]``)
   A list of rewrite rules that are applied to incoming requests. Each element of
   the list should be a string value compatible with the format of ``nginx``
   option ``rewrite``. The keyword ``rewrite`` itself should be omitted, as well
   as trailing semi-colon (``;``).
 **static_locations** (list, optional, ``[]``)
   List of locations that should be treated as static-only, and not processed by
   the WSGI application at all. This is normally used for designating serving of
   static/media files by Nginx (for example, in case of Django projects for
   ``/static/`` and ``/media/``).
 **uid** (integer, optional, ``whatever OS picks``)
   UID/GID (they are set-up to be the same) of the dedicated website
   user/group.
 **use_paste** (boolean, optional, ``False``)
   Tell Gunicorn to assume that the passed-in ``wsgi_application`` value is a
   filename of a Python Paste ``ini`` file instead of WSGI application.
 **virtuaelnv_packages** (list, optional, ``[]``)
   A list of additional packages to install for this particular WSGI appliction
   in its virtual environment using ``pip``.
 **website_mail_recipients** (string, optional, ``root``)
   Space-separated list of e-mails or local users to which the mails, sent to
   either the website admin or website user, should be forwarded to. Forwarding
   is configured via ``~/.forward`` configuration file.
 **wsgi_application** (string, mandatory)
   WSGI application that should be started by Gunicorn. The format should be
   conformant to what the ``gunicorn`` command-line tool accepts. If the
   ``use_paste`` option is enabled, the value should be equal to filename of the
   Python Paste ini file, located in the ``code`` sub-directory. It should be
   noted that in either case the value should be specsified relative to the
   ``code`` sub-directory. I.e. don't use full paths.
 **wsgi_requirements** (list, optional, ``[ futures==3.3.0, gunicorn==19.10.0 ]``)
   Complete list of pip requirements used for deploying Gunicorn. If
   specified, this list will be used to create requirements file and
   install Gunicorn and its dependencies from that one. This allows to
   have pinned packages for both Gunicorn, futures, and their
   dependencies. The ``futures`` package is required by Gunicorn when
   using Python 2.7.
   It should be noted that this installation method is meant primarily in case of
   roles that want to take advantage of upgrade checks for pip requirements
   files, and that employ `pip-tools <https://github.com/jazzband/pip-tools>`_.
   In addition to change of installation method, when this parameter is specified
   the role will deploy necessary files for running the pip requirements upgrade
   check (see the ``common`` role for description). For this a directory is
   created under ``/etc/pip_check_requirements_upgrades/FQDN``. The same
   directory should be used by dependant roles to deploy their own ``.in`` and
   ``.txt`` files. Make sure the file ownership is set to ``root:pipreqcheck``.
   Should you need to utilise the requirements file in some manner (other than
   checking for its upgrades), it will be also stored (and made accessible to
   application user/admin)) in application's home directory under the name
   ``.wsgi_requirements.txt``.
   To create complete requirements list, it is recommended to use `pip-tools
   <https://github.com/jazzband/pip-tools>`_ (the ``pip-compile`` utility) with
   ``gunicorn`` and ``futures`` in the ``.in.`` file.
 **wsgi_requirements_in** (list, optional, ``[ futures, gunicorn ]``)
   List of top level packages to use when performing the pip
   requirements upgrade checks for the Gunicorn requirements (listed
   via ``wsgi_requirements`` parameter). For Python 3-based websites,
   it should be sufficient to list only ``gunicorn`` (``futures`` is
   required for Python 2).
 Distribution compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Role is compatible with the following distributions:
 - Debian 9 (Stretch)
 Examples
 ~~~~~~~~
 Here is an example configuration for setting-up a (base) WSGI website (for
 running a bare Django project):
 .. code-block:: yaml
     # Sample for a Django installation.
     - role: wsgi_website
       fqdn: django.example.com
       static_locations:
         - /static
         - /media
       uid: 2004
       virtualenv_packages:
         - django
       wsgi_application: django_example_com.wsgi:application
       environment_variables:
         DJANGO_SETTINGS_MODULE: "django_example_com.settings.production"
       https_tls_key: "{{ lookup('file', inventory_dir + '/tls/wsgi.example.com_https.key') }}"
       https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/wsgi.example.com_https.pem') }}"
       additional_nginx_config:
         - comment: Use custom page for forbidden files.
           value: error_page 403 /static/403.html;
         - comment: Use custom page for non-existing locations/files.
           value: error_page 404 /static/404.html;
       website_mail_recipients: "root john.doe@example.com"
       environment_indicator:
         background_colour: "green"
         text_colour: "black"
         text: "TEST ENVIRONMENT"
       proxy_headers:
         Accept-Encoding: '""'
     # Use wsgi_requirements to deploy Gunicorn.
     - role: wsgi_website
       fqdn: wsgi.example.com
       wsgi_application: wsgi:main
       wsgi_requirements:
         - gunicorn==19.7.1
 	- futures==3.1.1
 Database Server
 ---------------
 The ``database_server`` role can be used for setting-up a MariaDB database
 server on destination machine.
 The role implements the following:
 * Installs MariaDB server and client.
 * Configures MariaDB server and client to use *UTF-8* encoding by default.
 * Sets-up the database root user for passwordless login via UNIX
   socket authentication.
 * Drops the ``debian-sys-maint`` database user (which was used in
   Debian Jessie and earlier for maintenance tasks) if it is present,
   and updates the Debian system maintenance configuration file to use
   the root account over unix socket authentication.
 Role dependencies
 ~~~~~~~~~~~~~~~~~
 Depends on the following roles:
 * **common**
 Parameters
 ~~~~~~~~~~
 This role has no parameters.
 Distribution compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Role is compatible with the following distributions:
 - Debian 9 (Stretch)
 - Debian 10 (Buster)
 Examples
 ~~~~~~~~
 This role has no parameters which can be configured configure.
 Database
 --------
 The ``database`` role can be used for creating a MariaDB database and
 accompanying user on destination machine.
 The role implements the following:
 * Creates MariaDB database.
 * Creates a dedicated user capable of performing any operation on the created
   database. Username is set to be same as the name of database.
 * Sets-up pre-backup task that creates database dump in location
   ``/srv/backup/mariadb/{{ db_name }}.sql``.
 Role dependencies
 ~~~~~~~~~~~~~~~~~
 Depends on the following roles:
 * **database_server**
 * **backup_client**
 Backups
 ~~~~~~~
 If the backup for this role has been enabled, the following paths are backed-up:
 **/srv/backup/maraidb/{{ db_name }}.sql**
   Dump of the database. Database dump is created every day at 01:45 in the
   morning.
 Parameters
 ~~~~~~~~~~
 **db_name** (string, mandatory)
   Name of the database that should be created.
 **db_password** (string, mandatory)
   Password for the database user.
 Distribution compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Role is compatible with the following distributions:
 - Debian 9 (Stretch)
 - Debian 10 (Buster)
 Examples
 ~~~~~~~~
 Here is an example configuration for creating a single database (for some
 website):
 .. code-block:: yaml
   - role: database
     db_name: phpinfo_example_com
     db_password: phpinfo_example_com
 Backup Server
 -------------
 The ``backup_server`` role can be used for setting-up a server to act as backup
 storage for the backup clients. Storage is made available to the clients
 exclusively via SFTP on a dedicated port and dedicated OpenSSH server
 instance. This instance is specifically configured and tailored for this
 purpose.
 The role is primarily aimed for use with `Duplicity
 <http://duplicity.nongnu.org/>`_, but should be also usable for generic SFTP
 uploads.
 The role implements the following:

roles/mail_forwarder/meta/main.yml

➞

Show inline comments

 ---
 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:
         - 8
         - 9
         - 10

roles/mail_forwarder/molecule/default/molecule.yml

➞

Show inline comments

 ---
 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
   - name: parameters-mandatory-buster64
     groups:
       - parameters-mandatory
     box: debian/contrib-buster64
     memory: 256
     cpus: 1
     interfaces:
       - auto_config: true
         ip: 10.31.127.20
         network_name: private_network
         type: static
   - name: parameters-optional-buster64
     groups:
       - parameters-optional
     box: debian/contrib-buster64
     memory: 256
     cpus: 1
     interfaces:
       - auto_config: true
         ip: 10.31.127.21
         network_name: private_network
         type: static
   - name: parameters-no-incoming-buster64
     groups:
       - parameters-no-incoming
     box: debian/contrib-buster64
     memory: 256
     cpus: 1
     interfaces:
       - auto_config: true
         ip: 10.31.127.22
         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

roles/mail_forwarder/molecule/default/prepare.yml

➞

Show inline comments

 ---
 - 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:
 .31.127.10: "mail-server domain1"
 .31.127.11: "client1"
 .31.127.30: "parameters-mandatory-stretch64"
 .31.127.31: "parameters-optional-stretch64"
 .31.127.32: "parameters-no-incoming-stretch64"
 .31.127.20: "parameters-mandatory-buster64"
 .31.127.21: "parameters-optional-buster64"
 .31.127.22: "parameters-no-incoming-buster64"
     - 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

roles/mail_forwarder/templates/main.cf.j2

➞

Show inline comments

 # 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 }}
 # Allow relaying only from trusted networks. Do not relay mails for
 # domains for which the mail server is not responsible.
 smtpd_relay_restrictions = permit_mynetworks reject_unauth_destination

0 comments (0 inline, 0 general)