option: BASE

      value: dc=example,dc=com

    - comment: Set the default URI

      option: URI

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

    - comment: Set the truststore for TLS/SSL

      option: TLS_CACERT

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

    - commment: Force basic server certificate verification

      option: TLS_REQCERT

      value: demand

    - comment: Disable CRL checks for server certificate

      option: TLS_CRLCHECK

      value: none

LDAP Server

-----------

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

destination machine.

The role implements the following:

* Deploys LDAP TLS private key and certificate.

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

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

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

  log rotation included).

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

  configured to keep track of membership changes for object class

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

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

  attribute will update corresponding group as well.

* Configures permissions.

* Creates LDAP entries.

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

Parameters

~~~~~~~~~~

**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 all of its attributes

  listed. 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_domain** (string, optional, ``ansible_facts[host]['domain']``)

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

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

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

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

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

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

  Organization that should be specified in the base DN entry.

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

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

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

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

  description and syntax.

  Path to file on Ansible host that contains the X.509 certificate used for TLS

  for LDAP service. The file will be copied to directory ``/etc/ssl/certs/``.

  Path to file on Ansible host that contains the private key used for TLS for

  LDAP service. The file will be copied to directory ``/etc/ssl/private/``.

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

  Minimum *Security Strength Factor* to require from all incoming

  connections. This applies for both remote and local connections.

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: ~/tls/ldap.example.com_ldap.pem

  ldap_server_tls_key: ~/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

      objectClass: organizationalUnit

      ou: people

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

      objectClass: organizationalUnit

      ou: groups

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

      objectClass:

        - inetOrgPerson

        - simpleSecurityObject

      userPassword: somepassword

      uid: john

      cn: John Doe

      sn: Doe

XMPP Server

-----------

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

destination machine.

The role implements the following:

* Sets-up the Prosody apt repository.

* Deploys XMPP TLS private key and certificate.

* Installs Prosody.

* Configures Prosody.

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

Prosody is configured as follows:

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

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

* Self-registration is not allowed.

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

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

* 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``.

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``).

  Path to file on Ansible host that contains the private key used for TLS for

  XMPP service. The file will be copied to directory ``/etc/ssl/private/``.

  Path to file on Ansible host that contains the X.509 certificate used for TLS

  for SMTP service. The file will be copied to directory ``/etc/ssl/certs/``.

**xmpp_domains** (list, optional, ``ansible_facts[host]['domain']``)

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

  string specifying a domain.

**xmpp_ldap_server** (string, mandatory)

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

  for user authentication and listing.

**xmpp_ldap_bind_dn** (string, mandatory)

  Distinguished name of LDAP user used for authenticating to the LDAP

  server. This user is used for looking-up the users available on the

  server. Users themselves authenticate via their own account.

**xmpp_ldap_password** (string, mandatory)

  Password used for authenticating to the LDAP server.

**xmpp_ldap_filter** (string, optional, ``(mail=$user@$host)``)

  LDAP filter used for obtaining a list of users available on the Prosody

  server. Two special strings can be used for specifying the user and domain,

  ``$user``, and ``$host`` within. These will be replaced with real values in

  the filter every time a user is looked-up.

**xmpp_ldap_scope** (string, optional, ``subtree``)

  Scope for performing the LDAP search for obtaining a list of users available

  on the Prosody server.

**xmpp_ldap_base** (string, optional, see below)

  Base DN under which the lists of users available on the Prosody should be

  looked-up.

  If not specified, the value will default to base DN constructed by putting all

  elements of the server's domain as ``dc`` entries (as per standard Debian

  convention). I.e. if XMPP server domain is ``example.com``, the resulting base

  DN would be ``dc=example,dc=com``.

Examples

~~~~~~~~

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

.. code-block:: yaml

  ---

  xmpp_administrators:

    - john.doe@example.com

  # These are default key and certificate that generated during Prosody

  # installation.

  xmpp_tls_key: /etc/prosody/certs/localhost.key

  xmpp_tls_certificate: /etc/prosody/certs/localhost.crt

  xmpp_domains:

    - example.com

  xmpp_ldap_server: ldap.example.com

  xmpp_ldap_bind_dn: cn=xmpp,ou=services,dc=example,dc=com

  xmpp_ldap_password: xmpp

  # This would require that the memberof overlay is available on LDAP server

  # side.

  xmpp_ldap_filter: '(&(memberOf=cn=xmpp,ou=groups,dc=example,dc=com)(mail=$user@$host))'

  xmpp_ldap_scope: "onelevel"

  xmpp_ldap_base: "ou=people,dc=example,dc=com"

Mail Server

-----------

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).

* 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 25 (alternate SMTP

  to work around common network 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.

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

  below).

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_ROOT_DN``.

* Dovecot will log-in to LDAP as user

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

* Domain entries need to be available as

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

* Alias entries need to be available as

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

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

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

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

  group-based granting of mail services to users.

Parameters

~~~~~~~~~~

**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, optional, ``/etc/ssl/certs/truststore.pem``)

  Path to TLS truststore used for verifying the LDAP certificate. Should be in

  PEM format.

**mail_service_ldap_base_dn** (string, mandatory)

  Base DN in LDAP for the mail services under which the entries (domains, users,

  aliases) can be found.

**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_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.

  Path to file on Ansible host that contains the X.509 certificate used for TLS

  for IMAP and ManageSieve services. The file will be copied to directory

  ``/etc/ssl/certs/``.

  Path to file on Ansible host that contains the private key used for TLS for

  IMAP and ManageSieve services. The file will be copied to directory

  ``/etc/ssl/private/``.

  Path to file on Ansible host that contains the X.509 certificate used for TLS

  for SMTP service. The file will be copied to directory ``/etc/ssl/certs/``.

  Path to file on Ansible host that contains the private key used for TLS for

  SMTP service. The file will be copied to directory ``/etc/ssl/private/``.

**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_facts[host]['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).

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_root_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

  imap_tls_certificate: ~/tls/mail.example.com_imap.pem

  imap_tls_key: ~/tls/mail.example.com_imap.key

  smtp_tls_certificate: ~/tls/mail.example.com_smtp.pem

  smtp_tls_key: ~/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

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).

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.

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.

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

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

**smtp_relay_truststore** (string, optional, ``/etc/ssl/certs/truststore.pem``)

  Path to the file containing full X.509 CA certificate chain used for

  validating the server certificate presented by the relay server.

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_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 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.

Parameters

~~~~~~~~~~

  Path to file on Ansible host that contains the private key used for TLS for

  HTTPS service. The file will be copied to directory ``/etc/ssl/private/``.

  Path to file on Ansible host that contains the X.509 certificate used for TLS

  for HTTPS service. The file will be copied to directory ``/etc/ssl/certs/``.

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

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

  matched).

Examples

~~~~~~~~

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

.. code-block:: yaml

  ---

  https_tls_key: "{{ inventory_dir }}/tls/web.example.com_https.key"

  https_tls_certificate: "{{ 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 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:

* 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``).

* 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.

Parameters

~~~~~~~~~~

**admin** (string, mandatory)

  Name of the operating system user in charge of maintaining the website. This

  user is capable of making modifications to website configuration anda data

  stored within the website directory.

**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.

**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)

  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. Default is ``index.php``.

**https_tls_certificate** (string, mandatory)

  Path to file on Ansible host that contains the X.509 certificate used for TLS

  for HTTPS service. The file will be copied to directory ``/etc/ssl/certs/``.

**https_tls_key** (string, mandatory)