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 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_consumers** (list, optional, ``[]``)

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

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

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

  avaialable:

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

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

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

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

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

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

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

  be a dictionary containing the following keys:

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

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

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

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

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

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

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

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

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

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

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

  Organization that should be specified in the base DN entry.

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

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

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

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

  description and syntax.

**ldap_server_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_ldap.pem``)

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

**ldap_server_tls_key** (string, optional, ``{{ tls_private_key_dir }}/{{ ansible_fqdn }}_ldap.key``)

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

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.

Parameters

~~~~~~~~~~

**xmpp_administrators** (list, mandatory)

  List of Prosody users that should be granted administrator privileges over

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

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

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

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

  string specifying a domain.

**xmpp_ldap_base_dn** (string, mandatory)

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

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

  users, aliases etc.

**xmpp_ldap_password** (string, mandatory)

  Password used for authenticating to the LDAP server.

**xmpp_ldap_server** (string, mandatory)

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

  for user authentication and listing.

**xmpp_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_xmpp.pem``)

  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_tls_key** (string, optional, ``{{ tls_private_key_dir }}/{{ ansible_fqdn }}_xmpp.key``)

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

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: /etc/prosody/certs/localhost.key

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

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

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

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

  PEM format.

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

**imap_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_imap.pem``)

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

**imap_tls_key** (string, optional, ``{{ tls_private_key_dir }}/{{ ansible_fqdn }}_imap.key``)

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

**smtp_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_smtp.pem``)

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

**smtp_tls_key** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_smtp.key``)

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

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

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

---

- name: Install Python apt bindings

  apt: name=python-apt

- name: Add Prosody repository apt key

  apt_key:

    data: "{{ lookup('file', 'prosody-debian-packages.gpg') }}"

    state: present

- name: Add Prosody repository

  apt_repository: repo="deb http://packages.prosody.im/debian jessie main" state=present

- name: Install Lua Sec library (needed for TLS)

  apt: name=lua-sec state=installed

- name: Install Lua LDAP library

  apt: name=lua-ldap state=installed

- name: Install Prosody

  apt: name=prosody state=installed

- name: Allow Prosody user to traverse the directory with TLS private keys

  user: name=prosody append=yes groups=ssl-cert

- name: Deploy XMPP TLS private key

  copy: dest="/etc/ssl/private/{{ xmpp_tls_key | basename }}" src="{{ xmpp_tls_key }}"

        mode=640 owner=root group=prosody

  notify:

    - Restart Prosody

- name: Deploy XMPP TLS certificate

  copy: dest="/etc/ssl/certs/{{ xmpp_tls_certificate | basename }}" src="{{ xmpp_tls_certificate }}"

        mode=644 owner=root group=root

  notify:

    - Restart Prosody

- name: Set-up directory for storing additional Prosody modules

  file: path=/usr/local/lib/prosody/modules/ state=directory mode=755 owner=root group=root

- name: Deploy the Prosody mod_auth_ldap module

  get_url: url=https://prosody-modules.googlecode.com/hg/mod_auth_ldap/mod_auth_ldap.lua

           dest=/usr/local/lib/prosody/modules/mod_auth_ldap.lua

- name: Set-up file permissions for the Prosody mod_auth_ldap module

  file: dest=/usr/local/lib/prosody/modules/mod_auth_ldap.lua owner=root group=root mode=644

- name: Deploy Prosody configuration file

  template: src=prosody.cfg.lua.j2 dest=/etc/prosody/prosody.cfg.lua

  notify:

    - Restart Prosody

- name: Enable and start Prosody service

  service: name=prosody enabled=yes state=started

- name: Deploy firewall configuration for XMPP server

  copy: src="ferm_xmpp.conf" dest="/etc/ferm/conf.d/30-xmpp.conf" owner=root group=root mode=640

  notify:

---

local_mail_aliases:

  root: "root john.doe@{{ testsite_domain }}"

smtp_relay_host: mail.{{ testsite_domain }}

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

backup_clients:

  - server: web.{{ testsite_domain }}

    public_key: "{{ lookup('file', inventory_dir + '/ssh/web.' + testsite_domain + '.pub') }}"

    ip: 10.32.64.18

  - server: mail.{{ testsite_domain }}

    public_key: "{{ lookup('file', inventory_dir + '/ssh/mail.' + testsite_domain + '.pub') }}"

    ip: 10.32.64.15

  - server: ldap.{{ testsite_domain }}

    public_key: "{{ lookup('file', inventory_dir + '/ssh/ldap.' + testsite_domain + '.pub') }}"

    ip: 10.32.64.12

backup_host_ssh_private_keys:

  dsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_dsa_key') }}"

  rsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_rsa_key') }}"

  ed25519: "{{ lookup('file', inventory_dir + '/ssh/backup_server_ed25519_key') }}"

  ecdsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_ecdsa_key') }}"